|
在 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 更稳定准确的完成任务。 wildCardagents.json与 谷歌 A2A agent.json 谷歌在最近2025谷歌云大会上又推出了ADK开源工具（Agent Development Kit），联合 50 多家巨头推出 Agent2Agent 协议，提供了标准的对话和协作方式。在其demo代码里，也看到了 agent.json 的影子。 但是只能说是设计思想相似，都是声明自己的能力相关信息，让调用方能快速解析和识别到自己。agents.json里面是服务提供方的 API 声明，而 google A2A协议里 agent.json 文件声明的是agent 的能力、响应方式、状态等描述 agent 自身的信息。注意不要混淆 wildCard 的 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.0info:title:示例APIversion:1.0.0description:这是一个使用OpenAPI3.0规范描述的示例API。paths:/greet:get:summary:获取问候信息description:根据提供的姓名返回问候信息。parameters:-name:namein:querydescription:姓名required:trueschema:type:stringresponses:'200':description:成功获取问候信息content:application/json:schema:type bjectproperties:message:type:stringexample:你好，张三！'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是专门给 AI agents使用的 JSON 文件。API 提供方可以使用他们现有的 OpenAPI 规范来构建此文件，AI agents则通过检查此文件来执行准确的 API 调用。agents.json规范在 OpenAPI 规范的基础上还进行了一些扩展，如优化端点发现和LLM 参数生成。如果把一堆 API 定义摆在 AI 面前，让它完成一个复杂的操作，这个操作可能涉及到多个 API 的调用，AI 理解这些 API 还好说，但是 AI 怎么去按照正确的顺序调用 API 来完成任务呢？为此，agents.json 引入了然后需要将加载 agents.json 文件获取预设的 flows定义 fromagentsjson.core.modelsimportFlowfromagentsjson.core.models.bundleimportBundleimportagentsjson.coreascore
# 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`"""
配置身份验证信息fromagentsjson.core.models.authimportAuthType,BearerAuthConfigauth=BearerAuthConfig(type=AuthType.BEARER,token=STRIPE_API_KEY) AI agent 执行AI 理解用户意图，选择合适的 flows，根据 AI 的响应结果，解析到待调用的 flow，进行调用，完成用户的任务。 fromopenaiimportOpenAIfromagentsjson.core.executorimportexecute_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
infoinfo中包含 agents.json 的名称、描述、版本 {"info":{"title":"AlpacaTradingandMarketDataAPIMethods","version":"0.1.0","description":"ThisspecificationenablesinteractionwiththeAlpacaTradingandMarketDataAPIsbyexposingbothindividualoperationsandcompoundorchestrationflows.EachflowishighlysearchableandembeddablesothatAIagentsanddeveloperscaninvoketoolcallsthatactuallywork."}}sourceAPI 来源，每个源引用一个 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":" laceOrderandGetOrderStatus","description":"lacesaneworderandthenretrievesthatorder'sdetailsusingthereturnedorderID.","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":"Theassetsymbolfortheorder.","required":true,"type":"string"},{"name":"side","description":"Theorderside:'buy'or'sell'.","required":true,"type":"string","enum":["buy","sell"]},{"name":"order_type","description":"Thetypeoforder(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":"Timeinforce(e.g.,'day','gtc').","required":true,"type":"string"},{"name":"qty","description":"Thequantityfortheorder.","required":false,"type":"number"},{"name":"notional","description":"Thenotionalamountfortheorder.","required":false,"type":"number"},{"name":"limit_price","description":"Limitprice(ifapplicable).","required":false,"type":"number"},{"name":"type","description":"Secondaryordertypespecification.","required":true,"type":"string"},{"name":"order_id","description":"OrderIDreturnedfromorderplacement.","required":false,"type":"string"}],"responses":{"success":{"type":"object","description":"Combinedresponsewithorderplacementandretrievaldetails.","properties":{"placed_order":{"type":"object","description":"Responsefromplacingtheorder."},"retrieved_order":{"type":"object","description":"Orderdetailsretrievedafterplacement."}},"required":["placed_order","retrieved_order"]}}}}actions中的operationId，就是OpenAPI引用源里的operationId，如alpacatrading_post_order，可以看到对应的是/v2/orders接口。 
完整schema定义，详见官方文档-schema：https://docs.wild-card.ai/agentsjson/schema 1.优化自然语言驱动：允许AI agents通过自然语言指令触发 API 操作，而非依赖传统开发者导向的接口调用方式。2.标准化任务流：通过定义多步骤任务流（flows）和动作链接（links），确保 API 调用的逻辑顺序与准确性，解决传统智能体调用时顺序混乱的问题。 3.增强可发现性：扩展 OpenAPI 的端点描述机制，帮助 AI agents更高效地发现和解析 API 功能。 该规范目前处于社区倡议阶段，但因其兼容现有 Web 生态且实现简单，被视为未来"面向智能体的 Web 协议"的有力候选。典型应用场景包括自动化客服、社交媒体管理、数据分析等需要多 API 协同的领域。
|
