在 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 规范
openapi: 3.0.0info: 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 代理通信提供了很好的基础。
举一个栗子
传统模式下单流程
而要让 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工作原理
flows和links的概念。flows定义的是一个或多个 API 调用顺序，可以看成是一个预设好的复杂的操作。links描述了两个动作是如何连接在一起的。然后需要将agents.json文件放置在 /.well-known/agents.json 路径下，以便访问 Web 服务的AI agents可以轻松找到它，这也是一个约定。AI agent 端实现
加载 agents.json 文件
获取预设的 flows定义
from agentsjson.core.models import Flowfrom agentsjson.core.models.bundle import Bundleimport agentsjson.core as core# load the agents.json filedata: 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 promptflows_context = core.flows_prompt(flows)# Create the system promptsystem_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, BearerAuthConfigauth = BearerAuthConfig(type=AuthType.BEARER, token=STRIPE_API_KEY)
AI agent 执行
AI 理解用户意图，选择合适的 flows，根据 AI 的响应结果，解析到待调用的 flow，进行调用，完成用户的任务。
from openai import OpenAIfrom agentsjson.core.executor import execute_flowsclient = 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 协同的领域。
