官网：https://docs.wild-card.ai/agentsjson/introduction
github地址：https://github.com/wild-card-ai/agents-json
在 AI 时代的浪潮下，wildCard 团队在 OpenAPI 基础之上，实现了 agents.json规范，它是一个基于 OpenAPI 标准的开放规范，通过将互联网上的服务提供方（如alibaba.com、谷歌邮箱等）提供的 API 进行进一步的结构化描述，使 AI agents 可以更稳定更准确的调用API Service，是一个专门为 AI agent 设计的与网络服务提供方的交互方案。
MCP 与 agents.json
相较 MCP 而言，共同点都是让 AI agent有能力获取外部数据，但 agents.json 更侧重的是AI agent与互联网服务提供商的交互，保证多步骤调用的可靠性，使 AI agent 更稳定准确的完成任务。
wildCard agents.json 与 谷歌 A2A agent.json
谷歌在最近2025谷歌云大会上又推出了ADK开源工具（Agent Development Kit），联合 50 多家巨头推出 Agent2Agent 协议，提供了标准的对话和协作方式。在其demo代码里，也看到了 agent.json 的影子。
但是只能说是设计思想相似，都是声明自己的能力相关信息，让调用方能快速解析和识别到自己。 agents.json 里面是服务提供方的 API 声明，而 google A2A协议里 agent.json 文件声明的是 agent 的能力、响应方式、状态等描述 agent 自身的信息。注意不要混淆 wildCard的 agents.json 和 A2A 的 agent.json。
client 中使用 agent.json
A2A 的 agent.json概览
详见 google A2A 协议项目：https://github.com/google/A2A/tree/0ad9630e044d72c22428f129165fe4c0de385902
谷歌 A2A 协议的 agent.json 定义：https://github.com/google/A2A/blob/0ad9630e044d72c22428f129165fe4c0de385902/specification/json/a2a.json
继续回到今天的主角 agents.json。
OpenAPI是什么，为什么要基于 OpenAPI 规范
开头提到，agents.json规范是一个基于 OpenAPI 标准的开放规范，那为什么要基于 OpenAPI 规范呢？先看看 OpenAPI 的定义。
OpenAPI 规范（OpenAPI Specification，简称 OAS）是一种用于描述和定义 RESTful API 的标准化语言。它使得人类和计算机无需访问源代码、文档或通过网络流量检查，就能发现和理解服务的功能。通过遵循 OpenAPI 规范，开发者可以利用各种工具自动生成 API 文档、客户端和服务器端代码，以及进行自动化测试等。
使用 OpenAPI 规范，开发者可以以机器可读的格式（如 JSON 或 YAML）描述 API 的各个方面，包括端点、操作、请求和响应格式等。这种标准化的描述方式有助于确保 API 的一致性和可维护性。
下面举一个 OpenAPI 的例子：
openapi: 3.0.0 info: title: 示例 API version: 1.0.0 description: 这是一个使用 OpenAPI 3.0 规范描述的示例 API。 paths: /greet: get: summary: 获取问候信息 description: 根据提供的姓名返回问候信息。 parameters: - name: name in: query description: 姓名 required: true schema: type: string responses: '200': description: 成功获取问候信息 content: application/json: schema: type: object properties: message: type: string example: 你好，张三！ '400': description: 请求参数错误 '500': description: 服务器内部错误
将这份配置放到 https://editor.swagger.io/上，可以很容易且界面友好的看到这个接口的描述，这个就是 OpenAPI 规范。
当前大多数的传统的应用与API Service 的交互方式都是通过 POST、GET、DELETE、PATCH、PUT 等方式，并按照API Service 里的入参定义才能正确的调用服务拿到返回结果。
传统应用请求 API 模式
总体而言，OpenAPI 规范通过提供一致、标准化的 API 描述，促进了 API 的设计、开发和维护，提高了开发效率和系统的可互操作性。大多数 API 提供商都有 OpenAPI 规范，或者可以通过 OpenAPI 完全描述其 API。这些规范本身对于 AI 代理的时代来说并不足够，但为 API 代理通信提供了很好的基础。
举一个栗子
下面举一个例子，仅示例，不代表真实流程。例如我要在alibaba.com上订购一批衣服，要完成这个行为，在传统的客户端处理方式是，先调用商品详情接口确认商品最新信息；再调用下单接口，进行下单，获取订单的 id；再轮询调用查询订单状态接口获取订单状态。
传统模式下单流程
而要让 AI agent 帮你完成这个任务，则可以通过自然语言的方式告诉AI，“我要订购一批这个红色连衣裙，数量是 xx,尺寸大小是 xx，...”
agent-json 请求 API 模式
这里说明一下，这里仅是示例，不是要对比 AI agent 和传统模式下单流程的优劣，仅是说明 AI agent 是如何与服务提供方进行交互的，与传统模式的区别在哪里。
AI agent 首先会从服务提供商处加载 agents.json文件，来获取服务提供方提供的预设的flows，flows 可以看做是一系列预设的复杂操作，每个 flow 里定义了要执行的动作（一个动作对应调用一个 API）和执行顺序。
AI agent理解了用户的意图后，会选择合适的flows进行调用，例如选择了一个下单的 flow，里面包含要执行查商品信息、下订单、查订单状态 API，选择好后，使用 execute_flow 执行 flow，会自动且准确地调用下单 api 和获取订单状态 api，来完成用户任务。
agents.json工作原理
agents.json 是专门给 AI agents使用的 JSON 文件。API 提供方可以使用他们现有的 OpenAPI 规范来构建此文件，AI agents则通过检查此文件来执行准确的 API 调用。
agents.json 规范在 OpenAPI 规范的基础上还进行了一些扩展，如优化端点发现和LLM 参数生成。如果把一堆 API 定义摆在 AI 面前，让它完成一个复杂的操作，这个操作可能涉及到多个 API 的调用，AI 理解这些 API 还好说，但是 AI 怎么去按照正确的顺序调用 API 来完成任务呢？
为此，agents.json 引入了flows和links的概念。flows定义的是一个或多个 API 调用顺序，可以看成是一个预设好的复杂的操作。links描述了两个动作是如何连接在一起的。
然后需要将agents.json文件放置在 /.well-known/agents.json 路径下，以便访问 Web 服务的AI agents可以轻松找到它，这也是一个约定。
AI agent 端实现
加载 agents.json 文件
获取预设的 flows定义
from agentsjson.core.models import Flow from agentsjson.core.models.bundle import Bundle import agentsjson.core as core # load the agents.json file data: Bundle = core.load_agents_json(agents_json_url) flows = data.agentsJson.flows
设置 prompt
将 flows 的上下文注入到系统 prompt 中，使 AI 知道有哪些flows可以使用：
from agentsjson.core import ToolFormat # Format the flows data for the prompt flows_context = core.flows_prompt(flows) # Create the system prompt system_prompt = f"""You are an AI assistant that helps users interact with the Stripe API. You have access to the following API flows: {flows_context} Analyze the user's request and use the appropriate API flows to accomplish the task. You must give your arguments for the tool call as Structued Outputs JSON with keys `parameters` and `requestBody`"""
配置身份验证信息
from agentsjson.core.models.auth import AuthType, BearerAuthConfig auth = BearerAuthConfig(type=AuthType.BEARER, token=STRIPE_API_KEY)
AI agent 执行
AI 理解用户意图，选择合适的 flows，根据 AI 的响应结果，解析到待调用的 flow，进行调用，完成用户的任务。
from openai import OpenAI from agentsjson.core.executor import execute_flows client = OpenAI(api_key=OPENAI_API_KEY) query = "Create a new Stripe product for tie-die tshirts priced at $10, $15, and $30 for small, medium, and large sizes" response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": query} ], tools=core.flows_tools(flows, format=ToolFormat.OPENAI), temperature=0 ) response = execute_flows(response, format=core.ToolFormat.OPENAI, bundle=data, flows=flows, auth=auth) response
这个加载 agents.json文件、获取tools、执行 flows 的过程，在 agents.json中，称为 Wildcard Bridge。
理解 agents.json - Schema解析
下面是一个官方示例的电商网站的 agents.json
info
info中包含 agents.json 的名称、描述、版本
{ "info": { "title": "Alpaca Trading and Market Data API Methods", "version": "0.1.0", "description": "This specification enables interaction with the Alpaca Trading and Market Data APIs by exposing both individual operations and compound orchestration flows. Each flow is highly searchable and embeddable so that AI agents and developers can invoke tool calls that actually work." } }
source
API 来源，每个源引用一个 OpenAPI 3+规范，可以引入多个 API，做混合调用。
{ "sources": [ { "id": "alpacatrading", "path": "https://raw.githubusercontent.com/wild-card-ai/agents-json/refs/heads/integrations/alpaca/agents_json/alpaca/trading_openapi.yaml" }, { "id": "alpacamarketdata", "path": "https://raw.githubusercontent.com/wild-card-ai/agents-json/refs/heads/integrations/alpaca/agents_json/alpaca/marketdata_openapi.yaml" } ] }
ovrrides(可选)
允许覆盖或自定义任何 API 操作中的特定字段，非必填
{ "overrides": [ { "sourceId": "payment_gateway", "operationId": "processPayment", "fieldPath": "parameters.0.required", "value": true } ] }
flows ⭐️️⭐️️⭐️️⭐️️最核心
预设的流程，一个 agents.json中可以定一个多个 flow，每个flow 可以看做一个动作，包含一个或者多个 API 的调用。调用的 API 可以来自不同的 OpenAPI 定义，以达到混合调用的目的。
actions：每个 action 对应一个 API 调用；
links：flow的入参与action中的入参的绑定关系，使用正确的参数来调用 API ；
fields: 描述参数、可选的 requestBody 以及响应；
{ "id": "order_roundtrip", "title": "Place Order and Get Order Status", "description": "Places a new order and then retrieves that order's details using the returned order ID.", "actions": [ { "id": "order_roundtrip_place_action", "sourceId": "alpacatrading", "operationId": "alpacatrading_post_order" }, { "id": "order_roundtrip_get_action", "sourceId": "alpacatrading", "operationId": "alpacatrading_get_order_by_order_i_d" } ], "links": [ { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.symbol" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.symbol" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.side" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.side" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.order_type" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.order_type" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.time_in_force" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.time_in_force" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.qty" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.qty" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.notional" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.notional" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.limit_price" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.limit_price" } }, { "origin": { "actionId": "order_roundtrip", "fieldPath": "parameters.type" }, "target": { "actionId": "order_roundtrip_place_action", "fieldPath": "requestBody.type" } }, { "origin": { "actionId": "order_roundtrip_place_action", "fieldPath": "responses.success.id" }, "target": { "actionId": "order_roundtrip_get_action", "fieldPath": "parameters.order_id" } } ], "fields": { "parameters": [ { "name": "symbol", "description": "The asset symbol for the order.", "required": true, "type": "string" }, { "name": "side", "description": "The order side: 'buy' or 'sell'.", "required": true, "type": "string", "enum": [ "buy", "sell" ] }, { "name": "order_type", "description": "The type of order (e.g., 'market', 'limit', 'stop', 'stop_limit', 'trailing_stop').", "required": true, "type": "string", "enum": [ "market", "limit", "stop", "stop_limit", "trailing_stop" ] }, { "name": "time_in_force", "description": "Time in force (e.g., 'day', 'gtc').", "required": true, "type": "string" }, { "name": "qty", "description": "The quantity for the order.", "required": false, "type": "number" }, { "name": "notional", "description": "The notional amount for the order.", "required": false, "type": "number" }, { "name": "limit_price", "description": "Limit price (if applicable).", "required": false, "type": "number" }, { "name": "type", "description": "Secondary order type specification.", "required": true, "type": "string" }, { "name": "order_id", "description": "Order ID returned from order placement.", "required": false, "type": "string" } ], "responses": { "success": { "type": "object", "description": "Combined response with order placement and retrieval details.", "properties": { "placed_order": { "type": "object", "description": "Response from placing the order." }, "retrieved_order": { "type": "object", "description": "Order details retrieved after placement." } }, "required": [ "placed_order", "retrieved_order" ] } } } }
actions中的operationId，就是OpenAPI引用源里的operationId，如alpacatrading_post_order，可以看到对应的是/v2/orders接口。
完整schema定义，详见官方文档-schema：https://docs.wild-card.ai/agentsjson/schema
agents.json总结
核心作用
1.优化自然语言驱动：允许AI agents通过自然语言指令触发 API 操作，而非依赖传统开发者导向的接口调用方式。
2.标准化任务流：通过定义多步骤任务流（flows）和动作链接（links），确保 API 调用的逻辑顺序与准确性，解决传统智能体调用时顺序混乱的问题。
3.增强可发现性：扩展 OpenAPI 的端点描述机制，帮助 AI agents更高效地发现和解析 API 功能。
解决的核心问题
- API 与 LLM 的适配问题：传统 API 设计面向开发者而非大语言模型，导致AI agents需要编写大量适配代码并反复调试。例如需要通过调用多个 API 完成的复杂操作可通过 agents.json 简化为单一自然语言指令。
- 多步骤调用可靠性：通过预定义任务流（如自动化营销流程或金融交易），避免AI agents在串联多个 API 时出现逻辑错误。
- 部署兼容性：采用无状态设计，由客户端管理调用状态，支持现有身份认证体系（如 OAuth2），无需改造基础设施即可部署。
技术特性
- 基于 OpenAPI 扩展：复用 OpenAPI 的接口描述能力，新增交互规则和 LLM 优化字段（如语义化参数命名）。
- 轻量级集成：仅需在网站固定路径托管 JSON 文件，即可被AI agents自动发现和解析，部署成本极低。
- 生态开放性：作为提案标准，允许通过自定义字段扩展功能，同时通过版本控制保障兼容性。
该规范目前处于社区倡议阶段，但因其兼容现有 Web 生态且实现简单，被视为未来"面向智能体的 Web 协议"的有力候选。典型应用场景包括自动化客服、社交媒体管理、数据分析等需要多 API 协同的领域。
来源 | 阿里云开发者公众号
作者 | 徐盛（宗衡）
