agents.json：智能体通过自然语言与API交互的开源规范

综合介绍

agents.json 是 Wildcard AI 团队开发的一款开源规范，基于 OpenAPI 标准，旨在让智能体通过自然语言与 API 实现高效通讯。它通过结构化的 JSON 文件定义智能体与 API 的交互契约，优化了端点发现和参数生成，解决了智能体调用 API 时顺序混乱、准确性低的问题。项目版本为 0.1.0，托管在 GitHub（https://github.com/wild-card-ai/agents-json），采用 Apache 2.0 许可证，鼓励社区参与。借助 Wildcard Bridge Python 包，开发者可加载、解析并运行 agents.json 文件，轻松实现多步骤 API 调用的自动化。

Agents.json 是一个开源的 JSON 规范，它正式描述了 API 和 AI 智能体交互的合约，建立在 OpenAPI 标准之上。

功能列表

• 自然语言驱动 API 调用：智能体用日常语言触发 API 操作。
• 基于 OpenAPI 的扩展：在 OpenAPI 上新增交互规则，优化智能体使用。
• 任务流与链接：定义多步骤任务流（flows）和动作链接（links），确保调用顺序。
• 无状态设计：客户端管理状态，支持现有基础设施部署。
• SDK 支持：Wildcard Bridge 加载并运行规范文件，简化开发。

使用帮助

获取与准备

agents.json 是一个规范文件，使用时需结合 SDK 或手动编写。以下是具体操作：

1. 获取 agents.json 文件

• 官方示例：
  从 Wildcard AI 提供的快速入门笔记本获取，如：
  • Resend：resend.ipynb
  • Stripe：single.ipynb
  • Google Sheets 等：multiple-dynamic.ipynb
• 自定义编写：
  根据 完整 schema，创建文件。例如：

  {
  "apiVersion": "0.1.0",
  "baseUrl": "https://api.example.com",
  "chains": {
  "get_data": {
  "description": "获取指定数据",
  "agent_instructions": "根据用户输入提取数据",
  "steps": [{"endpoint": "/data", "method": "GET"}]
  }
  }
  }

建议放置在 /.well-known/agents.json 路径，便于智能体发现。

2. 安装 Wildcard Bridge

• 要求：Python 3.10+。
• 步骤：
  1. 运行命令：

     pip install wildcard-bridge
     

  2. 验证：

     python -c "import wildcard_bridge; print(wildcard_bridge.__version__)"
     

3. 配置环境

• 认证支持：支持 Basic、ApiKey、Bearer 三种认证。例如：

  from wildcard_bridge import Bridge
  bridge = Bridge(auth={"type": "ApiKey", "key": "your-api-key"})
  

• 连接智能体：接入支持的 LLM（如 OpenAI），并准备基础提示。

操作主要功能

功能 1：加载并解析规范文件

• 步骤：
  1. 加载文件：

     bridge.load_agents_json("path/to/agents.json")
     

  2. 查看任务链：

     chains = bridge.get_available_chains()
     print(chains)  # 输出可用任务，如 ["get_data"]
     

• 用途：了解支持的操作，准备运行。

功能 2：执行任务流

• 步骤：
  1. 运行任务：

     result = bridge.run_chain("get_data", {"query": "sales report"})
     print(result)  # 输出 API 返回结果
     

  2. 检查返回数据。
• 场景：用户说“给我销售报告”，智能体自动调用 API。

功能 3：调试与优化

• 调试：

  bridge.enable_debug()
  result = bridge.run_chain("get_data", {"query": "test"})
  

  查看日志，确保每步正确。

• 优化：调整 agent_instructions 或示例，提升智能体准确性。

特色功能操作

任务流与链接设计

• 操作流程：
  1. 定义多步骤任务流，例如 Gmail 回复：

     {
     "chains": {
     "reply_email": {
     "description": "回复邮件",
     "agent_instructions": "根据用户输入回复邮件",
     "steps": [
     {"endpoint": "/threads/{threadId}", "method": "GET"},
     {"endpoint": "/messages/send", "method": "POST"}
     ]
     }
     }
     }
     

  2. 运行：

     bridge.run_chain("reply_email", {"threadId": "123", "reply": "已收到"})
     

• 亮点：通过 flows 和 links 确保调用顺序正确，智能体无需自行推理。

无状态与现有系统兼容

• 实现：
  SDK 在客户端运行，适配无服务器环境：

  def lambda_handler(event, context):
  bridge = Bridge(auth={"type": "Bearer", "token": event["token"]})
  bridge.load_agents_json("s3://bucket/agents.json")
  return bridge.run_chain("task", event["args"])
  

• 优势：无需改动 API 服务端，直接使用。

示例：Stripe 支付查询

• agents.json：

  {
  "baseUrl": "https://api.stripe.com/v1",
  "chains": {
  "check_payment": {
  "description": "查询支付状态",
  "agent_instructions": "根据支付 ID 返回状态",
  "steps": [{"endpoint": "/charges/{chargeId}", "method": "GET"}]
  }
  }
  }
  

• 运行：

  result = bridge.run_chain("check_payment", {"chargeId": "ch_123"})
  print(result)
  

• 效果：智能体直接返回支付状态，简单高效。

注意事项

• 安全：密钥存储在环境变量中，避免泄露。
• 社区：加入 Discord 获取支持。
• 文档：参考 官方文档。