A2A接口文档

更新时间：2025-08-27

1 协议标准

本协议遵循 Google 发布的 A2A协议0.2.6版本规范。客户端请基于本版本规范进行集成。

2 接入流程

2.1 应用发布A2A渠道

将您搭建的应用发布成A2A服务，将基于A2A协议封装您的应用，发布后支持外部使用方通过SSE URL调用，可以在其他平台或使用A2A Client对接A2A服务的应用。

点击【复制】按钮复制应用发布后的AgentCard URL，请求时获取个人的API Key填到URL中，能够获取到A2A的AgentCard。AgentCard作为A2A服务的“数字名片”，对于发现和发起交互Agent至关重要。

2.2 获取AgentCard配置信息

访问AgentCard URL拿到我们发布成A2A的应用的Agent描述、Agent能力信息、服务端点和身份验证信息。A2A Client解析信息以确定该Agent是否适合给定的任务、如何构建其请求以及如何进行安全通信。AgentCard及示例参考: "3.1 AgentCard" 小节。

2.3 调用Agent

用户可以使用满足A2A协议的第三方Agent平台对接发布后的A2A应用，亦或是使用A2A Client与A2A Server进行对话。A2A请求调用和返回结构参数及示例参考"3.2 Agent调用"小节。

3 接口说明

3.1 AgentCard

接口定义

Path	/v2/a2a/${appId}/.well-known/agent.json
Method	GET
Authorization	请求签名(Bearer <AppBuilder API Key>)

请求结构

GET /v2/a2a/${appId}/.well-known/agent.json HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string

请求头域

除公共头域外，无其它特殊头域。

响应参数

字段	类型	必然存在	说明
name	string	是	Agent 名称。
description	string	是	Agent 描述。
url	string	是	Agent 服务访问地址。
version	string	是	Agent 版本号。
protocolVersion	string	是	支持的 A2A 协议版本。
capabilities	AgentCapabilities	是	Agent支持的可选功能声明。（例如，流式传输）
securitySchemes	map<string, SecurityScheme>	是	Agent 身份验证要求。
security	map<string, list[string]>	是	Agent 进行通信的安全要求，标记请求中必须存在的身份验证要求。
skills	list[AgentSkill]	是	Agent 技能列表。
provider	AgentProvider	是	Agent 提供商信息。
defaultInputModes	list[string]	是	Agent 默认支持的输入媒体类型。
defaultOutputModes	list[string]	是	Agent 默认支持的输出媒体类型。

AgentCarpabilities

字段	类型	必然存在	说明
streaming	boolean	是	是否支持 SSE 流式传输。（多智能体协同Agent发布的A2A应用只支持流式传输）

SecurityScheme

字段	类型	必然存在	说明
type	string	是	安全方案类型，这里固定是"apiKey"。
name	string	是	要使用鉴权的参数名称。
in	string	是	apiKey放置的位置，有效值为"query", "header"或"cookie"。
description	string	是	安全方案的描述信息。

AgentSkill

字段	类型	必然存在	说明
id	string	是	Agent 技能的唯一标识符。
name	string	是	技能名称。
description	string	是	技能描述。
tags	list[string]	是	技能的关键描述标签。
examples	list[string]	否	技能使用示例。
inputModes	list[string]	否	接收的媒体类型，设置时会覆盖defaultInputModes。
outputModes	list[string]	否	输出的媒体类型，设置时会覆盖defaultOutputModes。

AgentProvider

字段	类型	必然存在	说明
origanization	string	是	Agent 提供商组织。
url	string	是	Agent 提供商组织链接。

请求curl示例

curl --location 'https://appbuilder.baidu.com/v2/a2a/${appId}/.well-known/agent.json' \
--header 'X-Appbuilder-Authorization: Bearer <AppBuilder API Key>'

正确响应示例

{
  "version": "1.0.0",
  "description": "1",
  "skills": [
    {
      "name": "网页探索Agent",
      "description": " 具备问题分析、信息检索、操作浏览器和获取网页内容的能力。可模拟人类自主操作网页，完成自动点击、输入、选择等操作，更好支持内容检索与获取，帮助轻松完成网页浏览、信息查询、内容筛选等任务。",
      "id": "9f301aed00c1402d8f2cc8faa6a8c91e",
      "tags": []
    },
    {
      "name": "代码编写Agent",
      "description": " 具备问题分析、生成和运行代码的能力。支持生成并运行Python代码来解决用户数据处理和分析、数据可视化、数学计算等方面的需求。支持文件格式包含：xlsx、csv、jsonl、json、docx和pdf。",
      "id": "0e31d072c92347728ae9e2ef204c0ac0",
      "tags": []
    },
    {
      "name": "报告撰写Agent",
      "description": " 具备专业化、结构化报告输出能力。可基于用户需求或各类输入信息完成报告的框架搭建、内容组织、逻辑梳理与格式化呈现。支持内容输出为HTML及Markdown的文件格式。",
      "id": "c46edaee42f44c31afa94c75a56727c1",
      "tags": []
    }
  ],
  "protocolVersion": "0.2.6",
  "url": "http://demo.com",
  "provider": {
    "organization": "baiduqianfan",
    "url": "https://console.bce.baidu.com/ai_apaas/appCenter"
  },
  "capabilities": {
    "streaming": true
  },
  "securitySchemes": {
    "apiKeyAuth": {
      "description": "API Key认证鉴权",
      "in": "header",
      "name": "Authorization",
      "type": "apiKey"
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "name": "我的Agent应用"
}

错误响应示例

{
    "code": "NotFoundResource",
    "message": "A2AServerNotPublishedYet",
    "request_id": "uuid"
}

3.2 Agent调用

从AgentCard的url中获取Agent域名，再将AppBuilder API Key放置到AgentCard中定义的SecuritySchema验证要求中请求调用Agent。

接口定义

Path	/v2/${appId}
Method	POST
Content-Type	application/json
Authorization	请求签名(Bearer <AppBuilder API Key>)

请求结构

POST /a2a/${appId} HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json

{
  "id": "uuid",
  "jsonrpc": "2.0",
  "method": "message/stream",
  "params": {
    "message": {
      "kind": "message",
      "parts": [
        {
          "kind": "text",
          "text": "今天天气",
          "metadata": {}
        }
      ],
      "role": "user"
    }
  }
}

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名	类型	是否必填	说明
jsonrpc	string	是	指定JSON-RPC协议版本的字符串，固定为"2.0"。
id	string	是	消息id。
method	string	是	AgentCard支持SSE流式请求，请填写："mesage/steam"。
params	MessageSendParams	是	请求参数。

MessageSendParams

字段	类型	是否必填	说明
message	Message	是	发送的消息内容。

Message

字段	类型	是否必填	说明
role	string	是	发送消息对象。填写"user"表示当前消息是用户发送的。
parts	list[Part]	是	消息内容，每项为TextPart/FilePart/DataPart之一结构。
messageId	string	否	消息发送方生成的消息标识。
taskId	string	否	指定关联的任务ID，用于继续任务流程执行。
contextId	string	否	与消息关联的上下文标识。
kind	string	是	结构类型，这里固定为："message"。
metadata	MessageMetadata	否	与消息关联的元数据，用于支持扩展AppBuilder对话API参数。

Part

Part包含TextPart、DataPart和FilePart三种接结构，通过kind取值进行区分。

(1) TextPart

字段	类型	是否必填	说明
kind	string	是	标识此内容类型，TextPart固定为"text"。
text	string	是	文本消息内容。

(2) DataPart

字段	类型	是否必填	说明
kind	string	是	标识此内容类型，DataPart固定为"data"。
data	dict	是	结构化数据。

(3) FilePart

字段	类型	是否必填	说明
kind	string	是	标识此内容类型，TextPart固定为"text"。
file	File	是	文件内容，支持标识为URI或base64编码字节。

File

字段	类型	是否必填	说明
name	string	否	文件名称。
mime	string	否	文件媒体类型。
bytes	string	否	文件base64编码字节，与uri二选一提供。
uri	string	否	文件uri，与bytes二选一提供。

MessageMetadata

用于支持扩展AppBuilder对话API参数。

字段	类型	是否必填	说明
end_user_id	string	否	终端用户ID，由用户自行定义与维护，限制6 - 64字符。
file_ids	list[string]	否	如果在AppBuilder中上传了文件，可以将文件id放入该字段，目前只处理第一个文件。

响应头域

除公共头域外，无其它特殊头域。

响应参数

字段	类型	必然存在	说明
jsonrpc	string	是	指定JSON-RPC协议版本的字符串，固定为"2.0"。
id	string	是	消息id。
result	Task/TaskAritfactUpdateEvent/TaskStatusUpdateEvent	否	Agent 返回信息，请求处理成功时返回。
error	JSONRPCError	否	请求处理失败时返回。

Task

字段	类型	必然存在	说明
id	string	是	指定JSON-RPC协议版本的字符串，固定为"2.0"。
contextId	string	是	消息id。
status	TaskStatus	否	Agent 返回信息，请求处理成功时返回。
history	list[Message]	否	历史对话消息。
aritfacts	list[Artifact]	否	Agent任务生成的输出结构。
kind	string	否	结构类型，这里固定为："task"。

TaskStatus

字段	类型	必然存在	说明
state	string	是	任务的当前状态： submitted: 任务已提交。 working: 任务正在处理中。 input-required: 任务需要客户端提供额外输入。 completed: 任务已成功完成。 canceled: 任务已被取消。 failed: 任务执行失败。 rejected：任务因远程代理拒绝而终止。 TaskStatus.message可能包含错误详细信息。 auth-required：Agent需要客户端或用户进行额外身份验证才能继续。 unknown: 任务状态未知。
timestamp	string	否	状态的更新时间戳。

Artifact

字段	类型	必然存在	说明
artifactId	string	是	指定JSON-RPC协议版本的字符串，固定为"2.0"。
name	string	是	输出的当前阶段名称。
parts	list[Part]	是	输出的内容结构。
metadata	ArtifactMetadata	是	与输出内容关联的元数据，用于支持传输AppBuilder对话API相关的输出信息。

ArtifactMetadata

该字段用于支持传输AppBuilder对话API相关的输出信息。

字段	类型	是否必然存在	说明
name	string	否	消息名字，用于在同一个组件输出相同type的内容，但是作用不同时，使用该字段进行区分
raw_data	object	否	由开发者请求透传，内部系统返回的信息。
usage	object	否	大模型的token用量。
metrics	object	否	耗时、性能、内存等trace及debug所需信息，服务于下游的Trace及监控需求。
type	string	是	消息类型说明，包括text、code、files、urls、oral_text、references、image等。该字段的取值决定了下面的text字段的内容结构。
text	object	是	消息具体内容。每种type对应本字段的结构是不同的。
visible_scope	string	否	该消息的可见范围，包括user、llm、all，影响消息渲染效果枚举值： all ：全部，包括大模型和用户。 llm：大模型。 user：用户。默认为all。
event	object	是	事件消息

更多内部数据接口参考千帆AppBuilder对话接口文档。

TaskArtifactUpdateEvent

字段	类型	必然存在	说明
taskId	string	是	指定JSON-RPC协议版本的字符串，固定为"2.0"。
contextId	string	是	消息id。
artifact	Artifact	是	Agent 返回信息，请求处理成功时返回。
append	boolean	否	如果为true标识该部分追加到相同artifactId的已返回的结果中。
lastChunk	boolean	否	如果为true表示这条信息是这个artifact的最后更新。
kind	string	是	结构类型，这里固定为："artifact-update"。
metadata	ArtifactUpdateMetadata	是	与本次事件关联的元数据，用于支持传输AppBuilder对话API相关的元数据。

ArtifactUpdateMetadata

字段	类型	是否必然存在	说明
conversation_id	string	是	会话标识ID，用于推送。
end_user_id	string	否	终端用户ID。
is_completion	boolean	是	流式消息推送回答结果是否完结。
message_id	string	是	消息id，即一轮对话的id。一轮对话在流式场景下会多次消息推送的message_id将保持一致。
role	string	是	输出该消息的角色，包括tool、assisatnt、user。
status	string	是	当前对话状态。 running done error interrupt
trace_id	string	是	调用标识ID，便于追踪。
user_id	object	是	开发者id。

TaskStatusUpdateEvent

字段	类型	必然存在	说明
taskId	string	是	正在更新状态的任务ID。
contextId	string	是	关联任务的上下文ID。
status	TaskStatus	是	新的任务状态。
final	boolean	否	如果为true，表示是本次流更新的最终事件。服务器通常在这之后关闭SSE连接。
kind	string	是	结构类型，这里固定为："status-update"。

JSONRPCError

字段	类型	必然存在	说明
code	int	是	错误代码。
message	string	是	错误描述信息。

请求 curl 示例

curl --location 'http://appbuilder.baidu.com/a2a/${appId}' \
--header 'Authorization: Bearer <AppBuilder API Key>' \
--header 'Content-Type: application/json' \
--data '{
  "id": "uuid",
  "jsonrpc": "2.0",
  "method": "message/stream",
  "params": {
    "message": {
      "kind": "message",
      "parts": [
        {
          "kind": "text",
          "text": "今天天气"
        }
      ],
      "role": "user"
    }
  }
}'

正确响应示例

data: {
    "jsonrpc": "2.0",
    "result": {
        "taskId": "taskid-1",
        "contextId": "contextid-1",
        "kind": "artifact-update",
        "artifact": {
            "artifactId": "artifactid-1",
            "name": "/thought/plan",
            "parts": [],
            "metadata": {
                "event": {
                    "create": "",
                    "id": "eventid-1",
                    "name": "/thought/plan",
                    "status": "preparing"
                },
                "is_end": false,
                "is_event_done": false,
                "metrics": {
                    "begin_time_stamp": null,
                    "current_time_stamp": null
                },
                "name": "",
                "render": {
                    "component_detail": {
                        "is_workflow": false,
                        "name": "",
                        "thought": ""
                    }
                },
                "text_raw": {
                    "info": ""
                },
                "type": "text",
                "visible_scope": "all"
            }
        },
        "append": true,
        "lastChunk": false,
        "metadata": {
            "conversation_id": "conversationid-1",
            "end_user_id": "",
            "is_completion": false,
            "message_id": "msgid-1",
            "role": "tool",
            "status": "preparing",
            "trace_id": "traceid-1",
            "user_id": "userid-1"
        }
    },
    "id": "id-1"
}

data: {
    "jsonrpc": "2.0",
    "result": {
        "taskId": "taskid-1",
        "contextId": "contextid-1",
        "kind": "artifact-update",
        "artifact": {
            "artifactId": "artifactid-1",
            "name": "/thought/plan",
            "parts": [
                {
                    "kind": "text",
                    "text": "已经完成任务"
                }
            ],
            "metadata": {
                "event": {
                    "create": "",
                    "id": "eventid-1",
                    "name": "/thought/plan",
                    "status": "running"
                },
                "is_end": false,
                "is_event_done": false,
                "metrics": {
                    "begin_time_stamp": null,
                    "current_time_stamp": null
                },
                "name": "",
                "render": {
                    "component_detail": {
                        "is_workflow": false,
                        "name": "",
                        "thought": ""
                    }
                },
                "type": "text",
                "visible_scope": "all"
            }
        },
        "append": true,
        "lastChunk": false,
        "metadata": {
            "conversation_id": "conversationid-1",
            "end_user_id": "",
            "is_completion": false,
            "message_id": "msgid-1",
            "role": "tool",
            "status": "running",
            "trace_id": "traceid-1",
            "user_id": "userid-1"
        }
    },
    "id": "id-2"
}

data: {
    "jsonrpc": "2.0",
    "result": {
        "taskId": "taskid-1",
        "contextId": "contextid-1",
        "kind": "status-update",
        "status": {
            "state": "completed",
            "timestamp": "2025-08-27T08:20:43.604369041+08:00"
        },
        "final": true
    },
    "id": "id-3"
}

错误响应示例

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32700,
        "message": "Server received JSON that was not well-formed."
    }
    "id": "id-4"
}

概述

数据分析