A2A 1.0 协议接入

以标准 A2A 1.0 协议将 ApeMind Agent 暴露给多智能体编排框架:读取私有 Agent Card,通过 JSON-RPC / SSE 异步发送任务、查询状态、订阅流式输出与取消任务。

前置条件与端点

每个 ApeMind Agent 对应一个 A2A Agent:A2A 的 Task 对应一次异步 Turn,context 对应只属于当前 API Key 的隐藏 Chat。当前定位为可异步执行、查询与取消的单轮任务(不支持同一 Task 内追问、人工确认或推送通知)。

用途 端点
私有 Agent Card GET /v1/a2a/bots/{agent_id}/agent-card.json
JSON-RPC / SSE 协议入口 POST /v1/a2a/bots/{agent_id}

ApeMind 不暴露公开的 /.well-known/agent-card.json。读取名片与调用入口共用同一把 Bearer API Key,无权访问返回 404。名片声明 JSON-RPC 传输、streaming: true、pushNotifications: false、输入 text/plain、输出 text/plain 与 application/json(结构化引用)。

调用示例

curl(读取 Agent Card 与非阻塞 SendMessage)

export APEMIND_BASE_URL="https://apemind.ai"
export APEMIND_API_KEY="<API_KEY>"
export APEMIND_AGENT_ID="<AGENT_ID>"

# 1. 读取私有 Agent Card
curl -fsS "${APEMIND_BASE_URL}/v1/a2a/bots/${APEMIND_AGENT_ID}/agent-card.json" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}"

# 2. 发送异步任务(方法名使用 PascalCase:SendMessage / SendStreamingMessage / GetTask / ListTasks / CancelTask / SubscribeToTask)
curl -fsS "${APEMIND_BASE_URL}/v1/a2a/bots/${APEMIND_AGENT_ID}" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "8f0c2c1e-6f1a-4c1e-9a3e-0b1d2f3a4b5c",
        "role": "ROLE_USER",
        "parts": [{"text": "总结一下最新的报销制度"}]
      },
      "configuration": {"returnImmediately": true}
    }
  }'

官方 Python SDK

import os
import uuid
import httpx
from a2a.client.card_resolver import A2ACardResolver
from a2a.client.client import ClientConfig
from a2a.client.client_factory import ClientFactory
from a2a.types import a2a_pb2 as pb

base_url = os.environ["APEMIND_BASE_URL"]
api_key = os.environ["APEMIND_API_KEY"]
agent_id = os.environ["APEMIND_AGENT_ID"]

async def run():
    async with httpx.AsyncClient(
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=60,
    ) as http:
        card = await A2ACardResolver(
            http,
            base_url,
            agent_card_path=f"v1/a2a/bots/{agent_id}/agent-card.json",
        ).get_agent_card()
        client = ClientFactory(ClientConfig(httpx_client=http, streaming=True)).create(card)

        request = pb.SendMessageRequest(
            message=pb.Message(
                message_id=str(uuid.uuid4()),
                role=pb.Role.ROLE_USER,
                parts=[pb.Part(text="总结一下最新的报销制度")],
            )
        )
        async for event in client.send_message(request):
            print(event)

阻塞、异步与流式语义

方式 适用场景 服务端行为
SendMessage(默认阻塞) 短任务、调用方可持续保活 等待 Task 进入终态再返回
SendMessage + returnImmediately: true 长任务、异步工作流 立即返回 SUBMITTED / WORKING 的 Task,后续用 GetTask 或 SubscribeToTask 获取结果
SendStreamingMessage 需要实时逐字展示 先发 Task 快照,再以 TaskArtifactUpdateEvent(append=true) 推送增量,结束前发一次 append=false, lastChunk=true 的完整终版回答与引用,随后发终态事件

连接生命周期与任务生命周期解耦:客户端断线或网关超时不会取消运行中的 Task。重连后调用 GetTask 取结果,或对仍在运行的 Task 调用 SubscribeToTask 续订(对已终态 Task 订阅返回 UnsupportedOperationError)。

上下文、幂等与取消

回答产物、引用与边界

终态 Task 若已持久化回答,会携带固定 artifactId: "answer" 的 Artifact:第一个 Part 为回答正文(text/plain),有引用时第二个 Part 为 application/json,结构固定为:

{"references": [{"title": "文档标题", "url": "可访问链接或空字符串", "snippet": "引用片段"}]}

常见错误码速查

状态 / 错误码 原因 处理方式
HTTP 401 / 403 缺少或无效 API Key、使用了登录会话,或 License 处于只读模式 仅使用有效组织 API Key(Bearer 认证)并核对权限与 License
HTTP 404 Agent 不存在、无权调用或非 Agent 类型 核对 agent_id 与组织调用权限
HTTP 429 触发 api.chat_turn 限流 按 Retry-After 退避重试
-32009 缺少或不支持 A2A-Version 添加请求头 A2A-Version: 1.0
-32001 / -32002 Task 不存在/无权访问,或已终态不可取消 核对 taskId 与当前 API Key,已结束任务直接调 GetTask
-32004 / -32602 context_busy、任务内追问、订阅已结束 Task,或同 messageId 内容冲突 等待前序 Task 结束、不带 taskId 发新消息或更换新 messageId

下一步