思想领袖
指南：了解、构建和优化 API 调用代理
人工智能在科技公司中的作用正在迅速演变；人工智能的用例已经从被动的信息处理转变为能够执行任务的主动代理。根据 2025 年 3 月由 Georgian 和 NewtonX 进行的全球人工智能采用调查，91% 的成长阶段和企业公司的技术高管据报道正在使用或计划使用代理人工智能。
API 调用代理是这种转变的主要例子。API 调用代理利用大型语言模型（LLM）通过应用程序接口（API）与软件系统交互。
例如，通过将自然语言命令转换为精确的 API 调用，代理可以检索实时数据、自动执行例行任务，甚至控制其他软件系统。这一功能将人工智能代理转变为人类意图和软件功能之间的有用中间件。
公司目前正在使用 API 调用代理在各个领域，包括：
- 消费者应用：像 Apple 的 Siri 或 Amazon 的 Alexa 这样的助手被设计为简化日常任务，例如控制智能家居设备和预订。
- 企业工作流：企业已经部署了 API 代理来自动执行重复任务，例如从 CRM 中检索数据、生成报告或从内部系统中整合信息。
- 数据检索和分析：企业正在使用 API 代理来简化访问专有数据集、基于订阅的资源和公共 API，以生成见解。
在本文中，我将使用工程为中心的方法来了解、构建和优化 API 调用代理。文章中的材料基于乔治亚人工智能实验室进行的实践研究和开发。
我将解释 API 调用代理的工作原理以及如何成功地架构和工程这些代理以实现性能。最后，我将提供一个系统化的工作流程，工程团队可以使用它来实现 API 调用代理。
I. 关键定义：
- API 或应用程序接口： 一套规则和协议，允许不同软件应用程序相互通信和交换信息。
- 代理： 一种人工智能系统，旨在感知其环境、做出决定并采取行动以实现特定目标。
- API 调用代理： 一种专门的人工智能代理，能够将自然语言指令转换为精确的 API 调用。
- 代码生成代理： 一种人工智能系统，通过编写、修改和调试代码来帮助软件开发。虽然相关，但我的重点在这里主要是代理 调用 API，尽管人工智能也可以帮助 构建 这些代理。
- MCP（模型上下文协议）： 一个协议，特别是由 Anthropic 开发的，定义了大型语言模型如何连接和利用外部工具和数据源。
II. 核心任务：将自然语言转换为 API 操作
API 调用代理的基本功能是解释用户的自然语言请求并将其转换为一个或多个精确的 API 调用。这个过程通常涉及：
- 意图识别： 即使用户的目标表达模糊，也要理解用户的目标。
- 工具选择： 从一组可用选项中识别出能够实现意图的适当 API 端点（或“工具”）。
- 参数提取： 从用户的查询中识别和提取出所选 API 调用（如果有）所需的参数。
- 执行和响应生成： 执行 API 调用、接收响应，然后将此信息合成到一个连贯的答案中，或者执行后续操作。
考虑一个请求，如“嘿 Siri，今天的天气怎么样？”代理必须识别出需要调用天气 API 的需求，确定用户的当前位置（或允许指定位置），然后制定 API 调用以检索天气信息。
对于请求“嘿 Siri，今天的天气怎么样？”，一个示例 API 调用可能如下所示：
GET /v1/weather?location=New%20York&units=metric
最初的高级别挑战在于这个翻译过程，包括自然语言的模糊性以及代理需要在多步交互中保持上下文的需求。
例如，代理通常需要“记住”对话或之前的 API 调用结果的早期部分，以便为当前操作提供信息。上下文丢失是如果不明确管理则会出现的常见故障模式。
III. 架构解决方案：关键组件和协议
构建有效的 API 调用代理需要结构化的架构方法。
1. 为代理定义“工具”
为了使大型语言模型使用 API，必须以其可以理解的方式描述 API 的功能。每个 API 端点或函数通常被表示为一个“工具”。一个强大的工具定义包括：
- 对工具的目的和功能的清晰自然语言描述。
- 其输入参数（名称、类型、是否必需以及描述）的精确规范。
- 工具返回的输出或数据的描述。
2. 模型上下文协议（MCP）的作用
MCP 是大型语言模型使用工具的更标准化和更强大的关键启用器。它提供了一种结构化的格式，用于定义模型如何连接到外部工具和数据源。
MCP 标准化是有益的，因为它允许更容易地集成多样化的工具，促进工具定义在不同代理或模型之间的可重用性。此外，它是工程团队的最佳实践，首先使用诸如 OpenAPI 规范之类的良好定义的 API 规范。像 Stainless.ai 这样的工具旨在帮助将这些 OpenAPI 规范转换为 MCP 配置，从而简化使 API“代理就绪”的过程。
3. 代理框架和实现选择
有几种框架可以帮助构建代理本身。这些包括：
- Pydantic： 虽然不是专门的代理框架，但 Pydantic 对于定义工具的输入和输出的数据结构以及确保类型安全非常有用。许多自定义代理实现都利用 Pydantic 来实现这种结构完整性。
- LastMile 的 mcp_agent： 该框架专门设计用于与 MCP 配合使用，提供了一个更有意见的结构，符合像 Anthropic 这样的地方所描述的构建有效代理的做法。
- 内部框架： 也越来越常见的是使用人工智能代码生成代理（使用像 Cursor 或 Cline 这样的工具）来帮助编写代理、其工具和周围逻辑的样板代码。乔治亚人工智能实验室在与公司合作构建代理方面的经验表明，这对于创建非常小的、自定义的框架非常有用。
IV. 为可靠性和性能而进行工程设计
确保代理可靠地执行 API 调用并表现良好需要专注的工程努力。实现这一目标的两种方法是（1）数据集创建和验证以及（2）提示工程和优化。
1. 数据集创建和验证
训练（如果适用）、测试和优化代理需要高质量的数据集。该数据集应由代表性的自然语言查询及其对应的预期 API 调用序列或结果组成。
- 手动创建： 手动策划数据集可以确保高精度和相关性，但可能耗时。
- 合成生成： 使用编程或使用大型语言模型生成数据可以扩大数据集的创建，但这种方法带来了重大挑战。乔治亚人工智能实验室的研究发现，确保合成生成的 API 调用和查询的正确性和现实复杂性非常困难。通常，生成的问题要么太简单，要么不可能地复杂，使得很难衡量代理的细致性能。对合成数据进行仔细验证至关重要。
对于关键评估，一个较小的、高质量的、手动验证的数据集通常比一个大型的、嘈杂的合成数据集提供更可靠的见解。
2. 提示工程和优化
基于大型语言模型的代理的性能受到用于指导其推理和工具选择的提示的重大影响。
- 有效的提示涉及清晰地定义代理的任务，提供可用工具的描述以及结构提示以鼓励准确的参数提取。
- 使用框架如 DSPy 进行系统优化可以显著提高性能。DSPy 允许您定义代理的组件（例如，用于思想生成、工具选择、参数格式化的模块），然后使用一种编译器类似的方法，使用您的数据集中的少量示例来查找优化的提示或这些组件的配置。
V. 实现有效 API 代理的推荐路径
开发强大的 API 调用人工智能代理是一门迭代的工程学科。基于乔治亚人工智能实验室研究的发现，结果可以通过以下系统化的工作流程显著改善：
- 从清晰的 API 定义开始： 从与代理交互的 API 的结构良好的 OpenAPI 规范 开始。
- 标准化工具访问： 将您的 OpenAPI 规范转换为 MCP。像 Stainless.ai 这样的工具可以促进此过程，创建一种标准化的方式供您的代理理解和使用您的 API。
- 实现代理： 选择合适的框架或方法。这可能涉及使用 Pydantic 在自定义代理结构中定义数据结构，或者使用像 LastMile 的 mcp_agent 这样的框架，它围绕 MCP 构建。
- 在此之前，考虑将 MCP 连接到像 Claude Desktop 或 Cline 这样的工具，并手动使用此界面来感受代理如何使用它，通常需要多少次迭代才能正确使用 MCP，以及可能在实现过程中节省时间的任何其他详细信息。
- 策划高质量的评估数据集： 手动创建或仔细验证代表性自然语言查询及其预期 API 交互的数据集。这对于可靠的测试和优化至关重要。
- 优化代理提示和逻辑： 使用像 DSPy 这样的框架来完善代理的提示和内部逻辑，使用数据集来驱动准确性和可靠性的改进。
VI. 构建 API 调用代理的示例工作流程
以下是一个简化的示例，说明构建 API 调用代理的推荐工作流程：
步骤 1：从清晰的 API 定义开始
假设一个用于管理简单待办事项列表的 API，以 OpenAPI 定义：
openapi: 3.0.0
信息：
标题：待办事项 API
版本：1.0.0
路径：
/任务：
发布：
摘要：添加新任务
请求体：
required: true
内容：
application/json：
schema：
类型：对象
属性：
描述：
类型：字符串
响应：
‘201’：
描述：任务创建成功
获取：
摘要：获取所有任务
响应：
‘200’：
描述：任务列表
步骤 2：标准化工具访问
使用 Stainless.ai 等工具将 OpenAPI 规范转换为模型上下文协议（MCP）配置：
| 工具名称 | 描述 | 输入参数 | 输出描述 |
| 添加任务 | 向待办事项列表添加新任务。 | `描述`（字符串，必需）：任务的描述。 | 任务创建确认。 |
| 获取任务 | 检索待办事项列表中的所有任务。 | 无 | 任务列表，包括其描述。 |
步骤 3：实现代理
使用 Pydantic 进行数据建模，创建对应于 MCP 工具的函数。然后，使用大型语言模型来解释自然语言查询并选择合适的工具和参数。
步骤 4：策划高质量的评估数据集
创建一个数据集：
| 查询 | 预期 API 调用 | 预期结果 |
| “将‘购买杂货’添加到我的列表中。” | `添加任务`，其中 `描述` = “购买杂货” | 任务创建确认 |
| “我的列表中有什么？” | `获取任务` | 任务列表，包括“购买杂货” |
步骤 5：优化代理提示和逻辑
使用 DSPy 来完善提示，重点是清晰的指令、工具选择和使用策划的数据集进行评估和改进的参数提取。
通过集成这些构建块——从结构化的 API 定义和标准化的工具协议到严格的数据实践和系统优化——工程团队可以构建更强大、更可靠和更易于维护的 API 调用人工智能代理。
