7.0
热点
AI SCORE
开源项目2025-03-04 01:01
Agents.json：为 LLM 统一 API 调用规范
Hacker News · github.com#Agent#OpenAPI
Editor brief · 编辑速览
开源项目定义了 Agent 调用第三方服务的 OpenAPI 标准。对构建 AI 应用和多模型集成的开发者有实用参考价值。
agents.json Specification 是一个开放规范，构建于 OpenAPI 标准之上，用于正式描述 API 与 Agent 交互的契约。当前版本为 0.1.0。
使用 Wildcard Bridge Python package 加载、解析并运行 agents.json。
使用任一 quickstart notebook 即可开始：
agents.json Specification 是一个开放规范，构建于 OpenAPI 标准之上，用于正式描述 API 与 Agent 交互的契约。
当前版本为 0.1.0。
欢迎在我们的 Discord 中提供反馈、分享你的项目并寻求帮助。
完整 schema 可在此处查看。
让 AI Agent 与 API 交互并非易事。和许多 Agent 开发者一样，我们也遇到了同样的问题：为了让 API 能够可靠地与 LLM 配合，需要不断调整；要连续成功执行多次 API 调用，更是一个反复试错的过程。
API 是为开发者设计的，而不是为 LLM 设计的。如果你正在为 AI Agent 构建集成，那么针对每一个 API，你都需要编写样板代码、试验 system prompt、优化工具定义，并将响应解析到 vector store 中。
以 Gmail API 为例，它提供了搜索 thread、列出 thread 中的邮件，以及使用 base64 编码的 RFC 822 内容回复邮件等 endpoint。而 LLM 真正需要的，是一个清晰的顶层指令，通过一个工具就能完成这一切。
为什么 agents.json 构建于 OpenAPI 之上？——OpenAPI 是描述 API endpoint 如何工作以及如何执行的黄金标准。大多数 API 提供商都有 OpenAPI spec，或者其 API 可以由 OpenAPI 完整描述。单靠这些 spec 尚不足以满足 AI Agent 时代的需求，但它们为 API 与 Agent 之间的通信奠定了出色的基础。
因此，我们实现了 agents.json。我们最初为自己构建了它，现在也很高兴能与你分享。
agents.json 是一种由结构化契约组成的 JSON schema，专为 AI Agent 设计。API 提供商使用现有的 OpenAPI spec 构建此文件，Agent 则检查该文件，从而准确地执行一系列 API 调用。
agents.json spec 在 OpenAPI spec 的基础上增加了一组扩展，针对 endpoint 发现和 LLM 参数生成进行了优化。这些扩展可以包括更新描述和添加示例。
如果只描述 endpoint 和数据模型，却不说明它们如何协同交互，AI Agent 就很难采取正确的操作序列。
为了解决这个问题，我们引入了 flow 和 link。Flow 是由一次或多次 API 调用组成、用于描述某个结果的契约。Link 则描述两个 action 如何衔接在一起。
我们建议将该文件放置在 /.well-known/agents.json，以便访问 Web 服务的 Agent 能够轻松发现它。目前，我们维护着一个 registry，用于收录可用的 agents.json 文件。
Wildcard Bridge 让 LLM 能够加载、解析并运行 agents.json。其工作方式如下：
开发者将自己的 Agent 与一个 agents.json 文件连接起来。
Agent 选择相关的 chain，并针对给定任务填充参数。
Bridge 运行这些 chain。
我们期望实现这样的开发体验：开发者只需在工作流中添加一个 agents.json 文件，系统便会执行该集成所需的正确 action 集合。Bridge 支持为请求添加 Basic、ApiKey 和 Bearer authentication。
尽可能利用现有标准与基础设施。
尽可能利用现有标准与基础设施。
设计时以 AI 使用为核心。
设计时以 AI 使用为核心。
编排由调用方 Agent 负责。
编排由调用方 Agent 负责。
让采用过程尽可能顺畅。
让采用过程尽可能顺畅。
随着 OpenAI 发布 Operator，我们已经看到 AI 自动化范式发生了转变。让 AI 在互联网上自由运行，意味着需要针对 Agent 在 Web 体验中同时构建相关功能与安全护栏。然而，对于绝大多数服务而言，这恰恰是 API 已经提供的能力，而且 API 能做的还不止这些。
与其仅为 Web Agent 优化 UX，不如增强 API，从而构建更具可扩展性、更强大且更安全的 Agent。API 背后有为规模化运行而构建的后端基础设施作为支撑。
目前仍有一些开放问题，也还有更多工作要做。现在就开始讨论并进行迭代式构建，可以让我们拥有一个持续调整的空间，与 AI Agent 开发中不断演进的范式共同前进。
即使提供商尚未正式采用，我们现在也可以开始构建 agents.json 文件。无需额外修改基础设施，无需增加服务器，也无需创建新的 endpoint。通过让客户端负责执行，这一范式遵循了现有 API 应用如今采用的相同安全与编排协议。API 提供商仍然可以选择维护官方的 agents.json 文件。
尽管 OpenAPI spec 很好地描述了 API 的使用方式，但使用 OpenAPI Generator 和 Swagger Codegen 等工具进行 code generation 并不完美。许多 API 存在一些边缘情况，这些情况已在 client SDK 中得到处理，却没有在原始 HTTP 请求中解决。例如，Gmail 的 RFC2822 格式或 Twilio 自定义的 TwiML 格式，更适合由代码解析，而不是让 LLM 将其生成为输入。为了便于使用，我们在 repository 中的 agents.json 文件旁附上了 OpenAPI spec 的副本。
MCP 被设计为有状态协议，依赖客户端与服务器之间的持久连接来交换上下文和请求；Agents.json 则是无状态的。在这里，Agent 独立管理所有上下文。你可以利用现有的 Agent 架构和 RAG 系统，有效处理状态。Agents.json 允许你使用现有的 pub/sub 架构、serverless 环境，以及 API 如今已经支持的基础设施进行构建。此外，其定义由 OpenAPI spec 提供强类型约束。
llms.txt 是一个很出色的标准，可以让网站内容更易于被 LLM 阅读，但它没有解决执行结构化 action 时面临的挑战。llms.txt 帮助 LLM 检索和理解信息，而 agents.json 则让它们能够可靠地执行多步骤工作流。
OpenAPI 是一项经过深思熟虑的标准，并随着 HTTP API 的变化不断演进。它是描述 API endpoint 如何工作以及如何执行的黄金标准。大多数 API 提供商都有 OpenAPI spec，或者其 API 可以由 OpenAPI 完整描述。这些 spec 尚不足以完全满足 Agent 时代的需求，但确实为 API↔Agent 通信奠定了出色的基础。
agents.json Specification 需要社区的参与和意见。这个 GitHub repository 将用于承载非正式评审，以便进行版本控制和公开讨论。如需参与讨论，请加入 Discord 社区。这是一个持续演进的项目，离不开你的反馈。
该项目由 Wildcard AI 发起。
当前维护者名单请参阅 MAINTAINERS.md。