A2A Protocol

什么是 A2A Protocol?

Agent2Agent Protocol（A2A）是由谷歌发起并与50多家技术合作伙伴共同开发的一个开源协议，旨在实现不同人工智能（AI）代理之间的标准化通信与协作。它为AI代理提供了一种通用的“语言”，使其能够跨平台、跨框架和跨供应商安全地交换信息、协调行动和执行复杂任务。更多信息

AgentWeave 实现的是 A2A 协议版本 0.3（兼容 @a2a-js/sdk 0.3.x 的 JSON-RPC 规范）。

Agent Card 地址

Agent card 通过 well-known 路径提供（两个文件名返回同一份 card）：

https://rest.agentweave.ai/api/v1/agents/{agentId}/.well-known/agent-card.json
https://rest.agentweave.ai/api/v1/agents/{agentId}/.well-known/agent.json

Agent Card

{
    "name": "Mimi",
    "description": "I am your virtual girlfriend, a dynamic and gentle companion.",
    "url": "https://rest.agentweave.ai/api/v1/agents/google_vertex_ai_rag_6d99c644-052a-4dc4-9964-2139cb30af6d/a2a",
    "version": "1.0",
    "protocolVersion": "0.3",
    "capabilities": {
        "streaming": true,
        "pushNotifications": false,
        "stateTransitionHistory": false
    },
    "defaultInputModes": ["text"],
    "defaultOutputModes": ["text"],
    "skills": [
        {
            "id": "google_vertex_ai_rag_6d99c644-052a-4dc4-9964-2139cb30af6d",
            "name": "Mimi",
            "description": "I am your virtual girlfriend, a dynamic and gentle companion.",
            "tags": ["companion"],
            "examples": ["Um, did you miss me today?"],
            "inputModes": ["text"],
            "outputModes": ["text"]
        }
    ],
    "provider": {
        "organization": "Agent Weave",
        "url": "https://www.agentweave.ai/"
    },
    "securitySchemes": {
        "bearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT"
        },
        "apiKeyAuth": {
            "type": "apiKey",
            "in": "header",
            "name": "api-key"
        }
    },
    "security": [{ "bearerAuth": [] }, { "apiKeyAuth": [] }]
}

上述 card 中的 url 字段即 A2A 协议端点，向它发送 JSON-RPC 请求。返回结果还带有一个 AgentWeave 专有的 metadata 对象（模型、任务类型、支持的文件类型等），属于 A2A 规范之外的扩展。

鉴权

对 A2A 端点的每个请求都必须使用 securitySchemes 中声明的一种方式鉴权：

• Bearer（JWT）： Authorization: Bearer <JWT>
• API key： api-key: <your-api-key>

方法

端点接受标准的 A2A JSON-RPC 2.0 请求：

• message/send — 发送消息并获得单个 JSON-RPC 响应（非流式）。下文有说明。
• message/stream — 发送消息并返回 text/event-stream（SSE）；每个事件是一个 JSON-RPC 响应，携带增量的 status-update / artifact-update。
• tasks/get、tasks/cancel — 任务生命周期辅助方法。

旧的 tasks/send / tasks/sendSubscribe 方法名仍兼容保留，但新接入请使用 message/send / message/stream。

请求体（message/send）

{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
        "message": {
            "kind": "message",
            "messageId": "9b7c2f1e-3a4d-4c8e-9f2a-1b2c3d4e5f60",
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "Hello!"
                }
            ]
        },
        "configuration": {
            "blocking": true,
            "acceptedOutputModes": ["text", "text/plain"]
        }
    }
}

关键字段：

• jsonrpc：必须为 "2.0"。
• id：JSON-RPC 请求 id（任意字符串/数字，会在响应中原样返回）。
• method："message/send"。
• params.message.kind：必须为 "message"。
• params.message.messageId：本条消息的唯一 id（如 UUID）。
• params.message.role："user"。
• params.message.parts[].kind：内容类型，如 "text"。
• params.message.parts[].text：消息内容。
• params.configuration.blocking：true 表示等待最终结果后再返回。

新会话不要设置 params.message.taskId —— 服务端会新建 task。传入未知的 taskId 会返回 TaskNotFound 错误。

返回数据

message/send 返回一个 JSON-RPC 响应，其 result 为一个 Task：

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "kind": "task",
        "id": "b1f0e2c4-...",
        "contextId": "3d5a7e9b-...",
        "status": {
            "state": "completed"
        },
        "artifacts": [
            {
                "artifactId": "a7c1...",
                "name": "response",
                "parts": [
                    {
                        "kind": "text",
                        "text": "Hi there!"
                    }
                ]
            }
        ]
    }
}

关键返回字段：

• result.kind："task"。
• result.status.state：任务状态，如 "completed" / "working" / "failed"。
• result.artifacts[].parts[].kind / text：Agent 的回复内容。

出错时不返回 result，而是返回 error 对象，例如 { "jsonrpc": "2.0", "id": "1", "error": { "code": -32600, "message": "Invalid JSON-RPC Request." } }。