AI Agents 实战——工具与外部集成的必要性

正如前几章所述，AI 智能体的一项关键特性与差异化优势在于它们能够与外部世界交互。LLM 虽能理解、推理并生成文本，但归根结底仍受限于其训练数据与当前上下文窗口。若要超越被动对话、执行真实而有用的动作——例如预约、查询数据库、检索实时信息或执行多步工作流——AI 智能体必须配备工具（tools） 。

工具是智能体能力的功能性扩展。它们让智能体可以调用 API、访问外部系统、获取最新数据，甚至操作结构化的知识库。

在本章中，我们将讨论以下主题：

• AI 智能体工具的“解剖”（组成）
• 硬编码函数与语义函数
• API 与 Web 服务
• 数据库与知识库
• 同步调用 vs 异步调用

在读完本章后，你将理解工具如何把 LLM 转化为能力更强的智能体——以及如何设计、连接并管理这些工具，以构建智能、以行动为导向的系统。

技术要求

你可以在本书配套的 GitHub 代码仓库获取本章的完整代码：github.com/PacktPublis…。

AI 智能体工具的组成

可以把工具定义为 AI 智能体“做事”的能力。这些“事”既可能是抓取网页，也可能是发送电子邮件；既可以是读取你的日程，也可以是在某个网站上执行操作。正如接下来要看到的，根据核心逻辑的不同，工具可以用多种方式有效增强智能体的能力。无论如何，工具在我们设计智能体应用时都具有一套可共同把握的通用组成。

在深入工具的组成之前，先澄清一些术语。

如第 2 章所述，在谈论 AI 智能体时，你经常会看到 tasks、tools、skills、plugins、functions、actions 等词被交替使用，用来指代智能体“做事”的能力。不同的 AI 编排框架也有各自的术语。例如，Semantic Kernel 使用 plugin（插件） 一词，插件又由一个或多个 functions（函数） 组成；而 LangChain 使用 tool（工具） 一词。

虽然我们可以在语义上做区分（如把 plugins 理解为集成、functions 理解为操作、skills 理解为熟练度……），但它们通常都指向同一个概念：AI 系统代表用户去执行动作。为保持一致，本文全书统一使用 tool（工具） 这个术语。

回到工具的“解剖学”：AI 智能体的工具主要由哪些要素构成？

从高层看，一个工具由以下组件定义：

• 名称（name） ：工具的唯一标识。例如，一个能在我们日历中创建预约的工具可命名为 “CalendarTool”。

• 描述（description） ：定义工具的能力。正如本书多次强调的，这一点至关重要。LLM——也就是智能体的大脑——会读取这个“标签”，据此判断是否要调用该工具（取决于用户请求），以及若调用应传入哪些参数。比如，CalendarTool 的描述可以是：

  该工具与用户日历集成，能够读取现有会议、安排新会议，并处理与日历管理相关的召回/取消等活动。

• 核心逻辑（core logic） ：工具真正的“引擎”。例如，CalendarTool 会有不同方法（获取现有会议、创建新会议等），可以实现为 Python 函数。以下示例中，我们使用 Outlook 作为日历，因此需要连接到 Microsoft Graph：

def get_outlook_calendar_events(
    access_token: str, date: str = None
):
    """
    Fetches Outlook calendar events for a given date using Microsoft Graph API.
    """
    if not date:
        date = datetime.today().date().isoformat()
    start_datetime = f"{date}T00:00:00"
    end_datetime = f"{date}T23:59:59"
    url = (
        "https://graph.microsoft.com/v1.0/me/calendarview?"
        f"startDateTime={start_datetime}&endDateTime={end_datetime}"
    )
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    response = requests.get(
        url,
        headers=headers
    )

小贴士： 想要更顺畅的编码体验？在下一代 Packt Reader 中使用 AI Code Explainer 与 Quick Copy 功能。打开本书的在线阅读版，点击 复制 按钮（1）即可把代码快速拷贝到你的开发环境；或点击 讲解 按钮（2）让 AI 助手解释一段代码。

购买本书即可免费获得下一代 Packt Reader。扫描二维码或访问 packtpub.com/unlock，然后用书名搜索本书。请务必核对版本信息，确保获取正确的版本。

在上面的示例里，工具的核心逻辑基于 API 集成——我们通过 Microsoft Graph API 执行操作。然而，在 AI 工具的语境中，其核心逻辑会随用例与集成需求而变化。

在接下来的小节中，我们将逐一进行剖析。

硬编码函数与语义函数

这一类指由开发者显式定义的逻辑，可以通过传统的编程结构（硬编码逻辑），也可以通过自然语言描述（语义函数）来实现。

硬编码函数

硬编码函数是以代码实现的传统逻辑。它们具有确定性并面向特定任务，也就是严格按开发者的指令执行。对于不需要外部 API 或学习能力的简单工具、计算、格式化或业务规则，这类函数非常理想。

例如，我们可以做一个把摄氏温度转换为华氏温度的工具：

def convert_celsius_to_fahrenheit(celsius: float) -> float:
    return (celsius * 9/5) + 32

通过再添加两个要素（名称与描述），我们就能把这个函数包装为智能体的一个工具。在多种实现方法中，可以利用 LangChain 的 @tool 装饰器，它会自动推断名称与描述（第 6 章将详细介绍 LangChain 的组件与术语体系）：

@tool
def convert_celsius_to_fahrenheit(celsius: float) -> float:
    """tool to convert temperature from celsius to Fahrenheit"""
    return (celsius * 9/5) + 32

该工具会使用函数名作为其名称（convert_celsis_to_fahrenheit，原文如此），并将文档字符串作为其描述。智能体在被问到例如“20 摄氏度等于多少华氏度？”时就可以调用它。

这类硬编码函数速度快、开销小、无外部依赖，非常适合做通用的小工具逻辑。

语义函数

另一方面，语义函数用自然语言进行描述，但在底层会映射到代码。它们在诸如 Semantic Kernel 这样的框架中尤为强大：在该框架中，术语体系将 插件（plugin） 视为一组 函数（functions） 。对于语义插件，其典型结构如下。

以 Semantic Kernel 框架中一个内置插件 WriterPlugin 为例：

WriterPlugin/
└── Acronym/
        ├── config.json
        └── skprompt.txt
└── AcronymGenerator/
        ├── config.json
        └── skprompt.txt
└── Brainstorm/
        ├── config.json
        └── skprompt.txt
….

该插件包含 16 个函数。每个函数由一个 JSON 文件（用于设置函数描述及其他配置参数）与一个文本文件（用自然语言描述具体的“语义技能”）定义。

以 AcronymGenerator 函数的“解剖结构”为例：

配置文件：

{
  "schema": 1,
  "description": "Given a request to generate an acronym from a string, generate an acronym and provide the acronym explanation.",
  "execution_settings": {
    "default": {
      "max_tokens": 256,
      "temperature": 0.7,
      "top_p": 1.0,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0,
      "stop_sequences": [
        "#"
      ]
    }
  }
}

文本文件（节选）：

# Name of a super artificial intelligence
J.A.R.V.I.S. = Just A Really Very Intelligent System.
# Name for a new young beautiful assistant
F.R.I.D.A.Y. = Female Replacement Intelligent Digital Assistant Youth.
# Mirror to check what's behind
B.A.R.F. = Binary Augmented Retro-Framing.
# Pair of powerful glasses created by a genius that is now dead
E.D.I.T.H. = Even Dead I'm The Hero.
# A company building and selling computers
I.B.M. = Intelligent Business Machine.
….

如你所见，这个文本文件里完全没有代码；它只是一组首字母缩略词的示例。借助这个特定语义函数，智能体便能按描述要求生成合适的缩略词并给出解释。示例如下：

• 用户输入：“为一个魔法瞬间传送头盔生成一个缩写”
• 智能体输出（由该缩写技能驱动）：“M.A.G.I.C. = Mobile Apparatus for Guaranteed Instantaneous Conveyance”

通常，当你需要精确性、性能或底层逻辑时，应优先使用硬编码函数；而当你希望让 AI 基于自然语言描述更灵活地判断某个函数是否相关时，则应采用语义函数。

接下来，当把智能体与外部服务集成时，我们需要引入 API 与 Web 服务 的概念。

APIs 与 Web 服务

在扩展 AI 智能体或工具的能力时，API 与 Web 服务在把语言模型连接到外部世界方面起着至关重要的作用。

定义

API（应用程序编程接口） 是软件应用彼此通信的一种方式。它定义了一组规则，规定一个程序如何向另一个程序请求数据或服务——通常通过互联网进行。API 无处不在：当你的应用获取天气、加载电子邮件或叫一辆 Uber 时，都是在使用 API。

API 通常遵循 HTTP 协议，并使用如下方法：

• GET：用于检索数据（例如：获取你所在城市的当前天气）
• POST：用于发送新数据（例如：提交新的用户注册表单）
• PUT：用于更新已有数据（例如：编辑你的个人资料信息）
• DELETE：用于删除数据（例如：从账号中删除已保存的地址）

这些操作属于所谓的 RESTful API——一种在 Web 上构建 API 的流行架构风格。

这些工具充当通往实时系统的连接器，使 AI 能够从云平台、第三方服务或企业后端执行动作或检索实时数据。它们本质上弥合了 LLM 的推理能力与其运行所需的实时、动态数字环境之间的鸿沟。

请注意，听到 “API” 时，我们往往会立刻想到诸如 Google Maps 或 OpenWeather 之类的 Web 服务，但并非所有 API 都是外部的——有些完全存在于你的应用或企业环境内部。在为智能体构建工具或用语言模型编排工作流时，这一点的区分非常重要。

下面来探讨你会遇到的主要 API 类型。

Web API

Web API 通过互联网对外（或半对外）公开，通常由第三方提供。它们配有文档、速率限制与访问令牌。当你希望让 AI 查询天气、通过 Slack 发送消息，或从金融服务获取股价时，就会调用这类 API。

注释
Web API 是可通过 HTTP/HTTPS 远程访问的服务，通常以 REST 或 GraphQL 暴露接口，让应用检索或操作托管在其他地方的数据。多数 SaaS 平台都提供面向公众的 Web API。

示例：OpenWeatherMap API（按城市获取天气）、Stripe API（处理支付）、Microsoft Graph API（与 Outlook、Teams、OneDrive 交互）。

内部/企业 API

许多组织在防火墙之后或虚拟网络内运行内部 API。这些 API 驱动着核心业务系统，例如库存管理、客户数据库、预订引擎或人力资源平台。

注释
内部 API 通常需要安全的网络访问（例如 VPN 或 VNet 集成）。

可执行的示例操作：

• GET /orders/{id}：从企业资源规划（ERP）系统获取某位客户的订单
• POST /leave-request：创建员工请假申请
• GET /pricing-rules：返回内部定价逻辑

如果你在为企业场景构建 AI 智能体，你的大多数工具很可能要对接内部 API，而非外部 API。

后端函数 API（服务网格或微服务）

在基于微服务的架构中，不同服务通过内部 HTTP API 相互通信。它们通常容器化部署，可能运行在 Kubernetes 上，并位于如 Istio 或 Linkerd 等**服务网格（service mesh）**之后。

定义
微服务是一种软件架构风格：应用被拆分为更小、可独立部署的服务。每个服务完成特定业务功能，并通过轻量级协议（如 HTTP API）与其他服务通信。
服务网格是管理微服务间通信的基础设施层，提供安全、可靠、可观测的通信能力，处理流量路由、负载均衡、服务发现、认证与遥测等任务，而不增加微服务本身的复杂度。

从 AI 的视角看，这些与其他 API 并无二致——但通常延迟更低，且可能不需要互联网访问。当你构建在内部多个服务之间执行多步逻辑的智能体时，它们非常适合做内部编排。

无服务器函数 / 轻量级 API

有时，你需要的 API 尚不存在。借助 Azure Functions、AWS Lambda 或 Google Cloud Functions 等工具，你可以快速创建自己的轻量级 HTTP 端点，作为动态工具使用。

这类服务采用**无服务器（serverless）**模型，颠覆了传统托管方式：你无需管理服务器、扩缩容或操心基础设施，只需编写函数、部署到云提供商，即可通过 API 调用。

这种方式非常适合 AI 工具开发，因为它允许你快速搭建小而专一的函数——每个函数完成一个明确任务，比如摘要一份文档、格式化报告，或从某系统获取过滤后的数据。

可能性的范式与示例

一旦理解了这种范式，可能性将变得近乎无限。以下是一些智能体系统中 API 工具可以完成的示例：

表 5.1：不同任务对应的 API 示例

场景	工具说明	示例 API
“给我的团队发一条关于发布的消息。”	向 Slack 或 Teams 等共享沟通平台发送实时消息。	Slack Web API：使用 chat.postMessage 向指定频道发布更新。
“在我们的内部财务系统中创建一张新发票。”	将结构化数据（如客户与金额）写入安全的内部会计应用。	内部财务 API：使用 POST /invoices 在公司的 ERP 系统中创建发票。
“在内部各服务之间更新订单状态。”	一个微服务接收订单状态变更，并相应更新其他服务。	订单服务 API：使用 PATCH /orders/{id} 在后端服务之间同步订单状态。
“从文档中抽取关键词用于打标签。”	轻量级函数接收原始文本并返回抽取的关键词，用于搜索或元数据。	Azure Function：使用自定义 POST /extract-keywords 端点根据文本输入返回关键术语。

理解 Web、内部、后端（微服务）、无服务器 等不同类型 API 的差异，有助于你设计更智能、更模块化、也更安全的 AI 架构。

在构建工具时，问问自己：

• AI 是否需要与外部世界通信？——Web API
• 数据是否被公司防火墙保护在内部？——内部 API
• 这是你应用自身的后端业务逻辑吗？——微服务
• 需要快速而简单的实现吗？——无服务器函数

为任务选择合适的 API 类型，就为你的 AI 智能体奠定了成功的基础。

在下一节中，我们将探讨另一类用于为智能体补充外部知识的工具。

数据库与知识库

正如本书第 1 章所探讨的，在 ChatGPT 发布之后，给 LLM 注入外部知识是 GenAI 版图上最早实现的里程碑之一。我们看到，为 LLM 提供外部知识以“落地”的典型范式是 RAG（检索增强生成） 。不过，需要重点考虑两点：

• 数据形式多样，而 RAG 通常更适用于非结构化数据（文本、图像、音频……）。
• 面向**智能体（agentic AI）**的场景，可借助其固有的“推理”层，让传统 RAG 流水线变得更“智能”。

因此，先区分两大数据类别。

结构化数据（Structured data）

这类数据以**行、列与模式（schema）**存在——典型如 SQL 表、CRM 字段、库存记录。其可预测、可查询、易过滤/排序。针对这类数据，工具通常包装：

• SQL 查询（例如：SELECT * FROM orders WHERE status = 'pending'）
• 面向业务系统的 API 调用（如 Salesforce、SAP）

第二种（调用业务系统 API）本质上属于上一节“API 与 Web 服务”中的工具类别。接下来我们聚焦通过结构化查询与结构化数据库交互的情境。

在 AI 智能体（以及更广义的 AI 应用）语境中，支持“用自然语言进行智能数据库检索”的巩固范式是 text-to-query（文本到查询） 。其高层步骤如下：

1. 用户以自然语言提问——例如：“在美国销量最高的专辑是什么？ ”
2. LLM 将问题翻译为 SQL 语句——例如：

SELECT album_name, artist_name, units_sold
FROM album_sales
WHERE country = 'US'
ORDER BY units_sold DESC
LIMIT 1;

3. LLM 基于查询结果，生成通顺的自然语言答案——例如，SQL 返回：“在美国销量最高的专辑是 The Eagles 的《Greatest Hits》，销量 3800 万张。”

该思路同样适用于其他结构化数据（其查询语言可能不同于 T-SQL）。从智能体的实现视角看，效果取决于系统消息与工具描述中我们提供的指令集合。

非结构化数据（Unstructured data）

这是杂乱但信息富集的数据：长文本、邮件、PDF、音频转录、聊天记录等。你无法简单用一个 WHERE 子句来查询它——需要语义理解。

在 LLM 语境中，我们已讨论过：非结构化数据通常存储于向量数据库，并通过 RAG 流水线检索。然而，随着 AI 系统愈发智能体化，检索的角色也必须演进。智能体不仅是对输入被动回应的模型；它还是会评估任务、审视可用工具并决定最优推进方式的主动决策者。在这种语境下，把向量数据库视作可调用的动态工具（而非固定步骤）会引入重要的推理层：智能体可以决定是否需要检索、如何构造有效查询、选取哪个数据源，以及拿到信息后做什么。

这种从静态检索到智能体检索（agentic retrieval）的转变，使 RAG 呈现更审慎、目标导向的行为。

举例而言：我们想调研“长新冠（long COVID）”的症状，并依赖存放于向量数据库的一组临床论文。

传统 RAG 在用户提问“长新冠的症状有哪些？”时，流程大致为：

• 输入：原样接收用户问题。
• 嵌入与检索：将问题转为向量，在医疗文档的向量库里做相似度检索。
• 上下文注入：把相似度最高的 3–5 段落直接传给语言模型。
• 生成回答：模型仅基于这些检索片段生成答案。

输出通常是基于最相似段落的合理总结，但缺乏对文献类型、来源可信度、地区/时间/人群（成人 vs 儿童）等上下文的意识。

而在智能体 RAG中，可能是这样：

• 意图理解：识别“long COVID”为医学术语，判断用户需要可靠的临床综述。
• 工具选择：在可用工具中，评估并选择对同行评议期刊/官方健康指南进行向量检索最为合适。
• 查询优化：将问题重写为更精确的检索式：
  “SARS-CoV-2 感染后急性期后遗症（PASC，俗称长新冠）的最新临床症状与影响”。
• 检索与推理：用优化后的查询调用向量库工具；若结果缺少近期研究，则加**日期过滤（如 2022 年后）**或切换到另一知识源（如 CDC 的结构化 API）。
• 多源综合：抽取要点、去重整合，按常见/罕见/新出现进行区分并组织回答。

这样得到的答案更有据可依、具上下文意识，还能按需区分如“成人 vs 儿童”、标注“最近研究的时间点”等。

图 5.1：智能体化 RAG 示例

此外，这种方式支持更复杂的交互：向量数据库终将只是智能体众多工具之一。智能体可以把检索到的数据与其他工具的输出结合，或者当向量库的领域覆盖不足时，直接切换工具。由此，检索不再只是后端环节，而是融入智能体更宏观的决策闭环。

图 5.2：包含 VectorDB 作为工具的多工具 AI 智能体示例

将向量数据库嵌入为可调用工具，使检索与智能体架构的核心原则——自治性、适应性与情境感知——保持一致。智能体不再只是“检索被问到的内容”，而是先判断值得检索什么，以及为何。这一智能层不仅提升了答案的准确性与相关性，也解锁了企业 AI 系统中的全新工作流。

同步调用与异步调用

随着我们构建越来越智能的 AI 智能体——这些系统能够推理、规划并与外部工具交互——理解这些工具如何被调用就变得至关重要。在智能体工具设计中，一个常被忽视却极其重要的区分是：工具是同步运作，还是异步运作。

这不仅仅是实现层面的细枝末节。工具的执行方式会直接影响你的智能体应用的性能、可扩展性与响应性。

首先，让我们从编程中同步调用与异步调用的概念定义开始。

图 5.3：同步与异步过程示例

在编程中，同步调用是指一个函数/方法调用会阻塞后续执行，直到它完成为止。程序会在该函数返回结果后，才继续执行下一条指令。这种模式直观、易于推理，但在处理慢操作（如文件 I/O、网络请求、数据库访问）时，可能造成性能瓶颈。

例如，下面的 Python 函数以同步方式读文件：

# Synchronous file read in Python
with open("report.txt", "r") as file:
    content = file.read()
print("File content loaded.")

在这种情况下，程序在读完整个文件之前，不会打印 “File content loaded”。

与之相对，异步调用是一种非阻塞的函数调用形式，它允许程序在操作于后台进行时继续执行。当结果准备就绪时，会通过回调、事件或 Promise/Future（取决于语言）来处理。异步编程对构建响应迅速、可扩展的系统至关重要，尤其是在需要并发管理多个I/O 受限任务的环境中。

例如，下面的 Python 函数以异步方式读文件：

import aiofiles
import asyncio
async def read_file():
    async with aiofiles.open("report.txt", "r") as file:
        content = await file.read()
    print("File content loaded.")
asyncio.run(read_file())

在这里，程序在读取文件的同时还能继续处理其他任务，这对I/O 密集型应用非常理想。

回到 AI 智能体的语境，同步与异步调用的概念与工具的调用机制密不可分。

图 5.4：AI 智能体语境下的同步与异步过程示例

在同步流程中，智能体发起请求并等待响应，在得到响应前，无法继续做其他事情。
在 AI 工作流中，以下短时且可预测的任务一般适合同步方式：

• 单位转换（例如：摄氏度转华氏度）
• 日期或数字的格式化
• 简单的数据库查找
• 调用快速的 API（例如本地微服务）

采用异步调用时，智能体发起调用但不阻塞；它会先继续做别的工作，等结果返回时再进行处理。
这在以下场景尤为有用：

• 调用慢速或高延迟的 API（如第三方服务、外部数据库）
• 执行I/O 受限操作（如文件上传、网页抓取）
• 并行发起多个调用（如批量数据查询）

异步工具能让智能体更具响应性，并能同时处理多项工作，从而提升性能与用户体验。

在同步与异步之间做选择并不只是实现细节——它直接影响智能体的行为：

• 响应性：异步工具让智能体在等待长时操作时仍能保持响应；
• 并行性：异步调用可以批量/并发运行，尤其适合从多个数据源检索；
• 错误处理：异步工具更易整合重试、降级或超时逻辑，而不至于“卡死”智能体。

来看一个场景：假设你的智能体需要汇总来自五个区域系统的周销售报告。同步版本会一个接一个地获取——耗时约为5 倍。异步版本会同时抓取五份报告。

@tool
async def fetch_sales_report(region: str) -> str:
    """Fetches the weekly sales report for a given region."""
    await asyncio.sleep(2)  # Simulated network delay
    return f"{region} sales report: total sales $100k"

async def fetch_all_reports():
    regions = ["North", "South", "East", "West", "Central"]
    tasks = [fetch_sales_report(region) for region in regions]
    results = await asyncio.gather(*tasks)
    return "\n".join(results)

借助异步模式，智能体获取五份报告所需时间大致与获取一份相当。

那么，该用哪种方式？ 一般而言：

• 当操作很快、阻塞也不会降低用户体验，或任务必须严格顺序执行且每一步依赖上一步的结果时，同步更合适；
• 若面对高延迟操作、等待会导致效率低下，和/或智能体需要同时处理多任务时，首选异步。

许多 AI 系统会混合使用同步与异步工具——这完全没问题。关键是有意图地设计工具，明确哪些任务可以阻塞，哪些任务应当非阻塞。

像 LangChain 与 Semantic Kernel 等框架同时支持这两种模式，通常需要你正确注册工具，以便运行时能相应地处理它们。

总结

随着 AI 系统从简单的语言处理器演进为能推理、规划与行动的自治智能体，外部工具与集成的角色变得不可或缺。仅靠语言模型本身只能理解与生成文本；而通过工具（无论是 API、数据库，还是领域特定函数），它们才获得与真实世界交互的能力。这些集成将模型的触角延伸到训练数据之外，使其能够访问实时信息、触发外部动作、检索领域知识。无论是同步还是异步，通过符号式查询还是语义检索，工具构成了把被动模型转化为主动系统的脚手架。最终，正是对这些外部组件进行深思熟虑的设计与编排，决定了现代 AI 智能体的智能性、可靠性与实用性。

在下一章，我们将把上述理念付诸实践，构建第一个利用迄今讨论组件的 AI 智能体。

参考资料

• Semantic Kernel 插件：learn.microsoft.com/en-us/seman…
• LangChain 工具：python.langchain.com/docs/how_to…