将 OpenAPI 转换为 LLM 工具

agents.json 规范是一种开放规范，基于 OpenAPI 标准构建，用于正式描述 API 和智能体交互的契约。当前版本为 0.1.0。

使用 Wildcard Bridge Python 包来加载、解析并运行 agents.json 文件。

快速入门

使用以下快速入门笔记本开始：

智能体	认证方式	笔记本
Resend	API Key	./examples/resend.ipynb
Stripe	Bearer Token	./examples/single.ipynb
Rootly	Bearer Token	./examples/rootly.ipynb
Twitter + Giphy	OAuth 1.0, API Key	./examples/multiple.ipynb
Resend + Hubspot + Google Sheets	OAuth 2.0, API Key	./examples/multiple-dynamic.ipynb

演示

Stripe 智能体
Google Sheets 智能体
Resend 智能体
Rootly 智能体

agents.json 规范

agents.json 规范是一种开放规范，基于 OpenAPI 标准构建，用于正式描述 API 和智能体交互的契约。

当前版本为 0.1.0。

欢迎在我们的 Discord 社区中提供反馈、分享项目并获取帮助：Discord。

模式

完整的模式可在 这里 查阅。

动机

让 AI 智能体与 API 进行交互并不容易。我们在构建智能体时也遇到了同样的问题：为了让 LLM 可靠地与 API 配合工作，并连续成功执行多个 API 调用，往往需要反复试验。

API 是为开发者设计的，而非 LLM。如果你正在为 AI 智能体构建集成，就需要为每个 API 编写样板代码、尝试不同的系统提示、优化工具定义，并将响应解析到向量存储中。

例如，Gmail API 提供了搜索线程、列出线程中的邮件以及根据 base64 RFC 822 内容回复邮件的端点。然而，LLM 需要的是一个清晰的一级指令，能够通过一个工具完成所有这些操作。

为什么 agents.json 基于 OpenAPI 构建？ — OpenAPI 是描述 API 端点如何工作和执行的行业标准。大多数 API 提供商都拥有 OpenAPI 规范，或者其 API 完全可以用 OpenAPI 描述。尽管仅凭这些规范还不足以满足 AI 智能体时代的需求，但它们为 API 与智能体之间的通信奠定了良好的基础。

因此，我们实现了 agents.json。这是我们为自己开发的解决方案，现在非常高兴与大家分享。

agents.json 文件

agents.json 是一种专为 AI 智能体设计的结构化契约 JSON 模式。API 提供商可以利用现有的 OpenAPI 规范来构建此文件，而智能体则会检查该文件以执行准确的 API 调用序列。

agents.json 规范包含对 OpenAPI 规范的一些补充——优化端点发现和 LLM 参数生成。这些补充可能包括更新描述和添加示例。

仅仅描述端点或数据模型，而不说明它们之间如何相互作用，正是导致 AI 智能体难以采取正确行动顺序的原因。

为了解决这个问题，我们引入了“流程”和“链接”。流程是一系列包含一个或多个 API 调用的契约，用于描述某个结果；而链接则描述了两个动作是如何衔接在一起的。

我们建议将该文件放置在 /.well-known/agents.json 中，以便访问 Web 服务的智能体能够轻松发现它。目前，我们维护了一个可用 agents.json 文件的注册表：[wild-card.ai/registry]。

Wildcard Bridge

Wildcard Bridge 使 LLM 能够加载、解析和运行 agents.json 文件。其工作原理如下：

1. 开发者将其智能体与一个 agents.json 文件连接。
2. 智能体选择相关的链路，并为特定任务填充参数。
3. Bridge 执行这些链路。

理想情况下，开发者只需在其工作流中添加一个 agents.json 文件，系统就会自动执行正确的集成操作序列。Bridge 支持在请求中添加 Basic、ApiKey 和 Bearer 认证。

设计原则

1. 基于 OpenAPI 标准构建
   尽可能利用现有的标准和基础设施。

2. 优化模式以适应 LLM，而非人类
   以 AI 的使用需求为导向进行设计。

3. 强制无状态性
   协调工作由调用方智能体负责。

4. 尽量减少对现有 API 的改动
   使采用过程尽可能无缝。

为什么现在？

随着 OpenAI 推出 Operator，我们见证了 AI 将要自动化的范式转变。让 AI 自由地在互联网上运行，将要求为代理构建兼具功能与安全约束的 Web 体验。然而，对于大多数服务而言，这正是 API 已经提供的功能——甚至更多。

与其仅仅优化面向 Web 代理的用户体验，不如通过丰富 API 来打造更具可扩展性、更强大且更安全的代理。API 由专为规模化设计的后端基础设施提供支持。

目前仍有许多未解之谜，也还有大量工作要做。现在就开始讨论并以迭代方式推进，能够让我们在 AI 代理开发范式的不断演进中灵活调整。

常见问题解答

API 提供商不应该自行提供代理服务器或“/agent”端点吗？

我们可以在提供商正式采纳之前，立即开始构建 agents.json 文件。无需额外的基础设施变更、服务器或新增端点。通过将执行责任交由客户端承担，这一范式依然遵循当今基于 API 的应用程序所采用的安全与编排协议。API 提供商仍然可以选择维护官方的 agents.json 文件。

为什么选择通过 SDK 进行路由，而不是直接发起 HTTP 请求？

尽管 OpenAPI 规范很好地描述了如何使用 API，但使用 OpenAPI Generator 和 Swagger Codegen 等工具进行代码生成并不完美。许多 API 存在一些边缘情况，这些情况通常由客户端 SDK 处理，而原始 HTTP 请求则难以应对。例如，Gmail 的 RFC2822 格式或 Twilio 的自定义 TwiML 格式，更适合通过代码解析，而非由 LLM 直接生成输入。我们在仓库中随 agents.json 文件一同提供了 OpenAPI 规范的副本，供参考使用。

这与模型上下文协议（MCP）有何不同？

MCP 设计为有状态的，依赖于客户端与服务器之间的持久连接来交换上下文和请求；而 agents.json 则是无状态的。在此模式下，代理会独立管理所有上下文。您可以利用现有的代理架构和 RAG 系统来有效处理状态问题。agents.json 允许您基于现有的发布/订阅架构、无服务器环境以及当前基础设施支持的 API 进行构建。此外，其定义由 OpenAPI 规范进行强类型化。

那 llms.txt 呢？

llms.txt 是一项使网站内容对 LLM 更加易读的标准，但它并未解决执行结构化操作的挑战。虽然 llms.txt 有助于 LLM 检索和理解信息，但 agents.json 却能让它们可靠地执行多步骤的工作流。

为什么使用 OpenAPI？

OpenAPI 是一个经过深思熟虑的标准，它随着 HTTP API 的发展而不断演进。它是描述 API 端点工作原理及调用方式的黄金标准。大多数 API 提供商都拥有 OpenAPI 规范，或者其 API 完全可以用 OpenAPI 描述。尽管这些规范尚不足以满足代理时代的需求，但它们确实为 API 与代理之间的通信奠定了良好的基础。

功能路线图

• OAuth
• 链接中的记忆与上下文管理
• 运行时字段转换
• 速率限制
• 并行任务处理
• 条件判断
• 循环
• 失败处理
• 流式传输
• 分页
• agents.json 交互式构建器
• agents.json 验证器

贡献

agents.json 规范需要社区的参与。本 GitHub 仓库将用于非正式评审，支持版本控制和公开讨论。如需交流，请加入我们的 Discord 社区：discord.gg/7AP6wSkVtQ。这是一个不断发展的项目，离不开您的反馈。

团队与维护者

本项目由 Wildcard AI 发起。

有关当前维护者的名单，请参阅 MAINTAINERS.md。

agents-json 快速上手指南

agents-json 是一个基于 OpenAPI 标准的开放规范，旨在将 API 转换为大语言模型（LLM）可直接调用的工具。它通过定义“流（Flows）”和“链接（Links）”，让 AI Agent 能够可靠地执行多步 API 调用，而无需繁琐的提示词工程或手动解析。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • 已配置好的 LLM 环境（如 OpenAI API Key 或其他兼容接口）
  • 目标服务的 API 密钥（如 Stripe, Resend, Google Sheets 等，视具体用例而定）

安装步骤

使用 pip 安装 Wildcard Bridge Python 包，这是加载、解析和运行 agents.json 的核心库。

pip install wildcard-bridge

提示：如果下载速度较慢，可以使用国内镜像源加速安装：

pip install wildcard-bridge -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

agents-json 的核心工作流是：加载 agents.json 规范文件 -> Agent 选择相应的执行链（Chain）-> Bridge 执行请求。

以下是一个最简单的概念性使用示例，展示如何在代码中集成并运行一个 Agent 任务：

1. 准备 agents.json 文件

首先，你需要一个针对特定 API（例如 Stripe 或 Resend）生成的 agents.json 文件。你可以从 官方注册表 获取，或使用官方提供的示例文件。

2. 编写 Python 脚本

使用 wildcard-bridge 加载规范并执行任务。

from wildcard_bridge import AgentBridge

# 初始化 Bridge
bridge = AgentBridge()

# 加载 agents.json 文件 (可以是本地路径或 URL)
# 这里以加载本地 stripe 的规范为例
spec_path = "./examples/stripe_agents.json"
bridge.load_spec(spec_path)

# 定义你的 LLM 和认证信息
api_key = "YOUR_STRIPE_SECRET_KEY"
llm_model = "gpt-4o" # 或其他支持的模型

# 设置认证 (支持 Basic, ApiKey, Bearer, OAuth 等)
bridge.set_auth("Bearer", api_key)

# 让 Agent 根据用户意图自动选择并执行对应的 Chain
# 例如：用户想要 "创建一个金额为 100 美元的支付意向"
user_task = "Create a payment intent for $100 USD"

response = bridge.run(
    task=user_task,
    model=llm_model
)

print(response)

3. 参考官方示例

为了更快上手，建议直接运行官方提供的 Jupyter Notebook 示例，这些示例涵盖了从单 API 调用到多 API 协同工作的场景：

• Resend (邮件发送): ./examples/resend.ipynb (需 API Key)
• Stripe (支付处理): ./examples/single.ipynb (需 Bearer Token)
• 多服务协同 (Twitter + Giphy): ./examples/multiple.ipynb
• 动态多服务 (Resend + Hubspot + Google Sheets): ./examples/multiple-dynamic.ipynb

您可以克隆仓库后直接在 Jupyter 环境中运行这些 Notebook：

git clone https://github.com/wild-card-ai/agents-json.git
cd agents-json
# 启动 Jupyter 并打开示例
jupyter notebook examples/resend.ipynb