除了MCP我們還有什麼？

2025-05-05 01:37 阿里雲開發者

阿里妹導讀
本文詳細描述 agents.json ，涵蓋了其背景、工作原理、與 OpenAPI 的關係等內容。
官網：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.0info:  title: 示例 API  version: 1.0.0  description: 這是一個使用 OpenAPI 3.0 規範描述的示例 API。paths:  /greet:    get:      summary: 獲取問候資訊      description: 根據提供的姓名返回問候資訊。      parameters:        - name: namein: 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 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.authimportAuthType, 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 協同的領域。
精準識別，輕鬆整合人臉比對服務
傳統自建人臉比對應用面臨著技術複雜、成本高昂及維護困難等挑戰。透過採用本方案，企業無需自行訓練和部署深度學習模型，快速接入人臉比對服務。人臉比對服務適用於人身核驗與安防監控等多種場景，為企業提供高效、精準且易於實施的身份認證。    
點選閱讀原文檢視詳情。

相關文章