前置条件与端点
每个 ApeMind Agent 对应一个 A2A Agent:A2A 的 Task 对应一次异步 Turn,context 对应只属于当前 API Key 的隐藏 Chat。当前定位为可异步执行、查询与取消的单轮任务(不支持同一 Task 内追问、人工确认或推送通知)。
- 凭据要求:仅接受绑定组织的 API Key(不接受浏览器 Cookie、OAuth 或匿名访客),且该 Key 对目标 Agent 具有调用权限。
- 版本协商:必须发送请求头
A2A-Version: 1.0;省略该头会按 0.3 处理并返回VersionNotSupportedError(-32009)。路径中的/v1为 ApeMind 外部协议入口前缀,{agent_id}沿用历史路径段/bots/{agent_id}。
| 用途 | 端点 |
|---|---|
| 私有 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)。
上下文、幂等与取消
contextId与命名空间隔离:不传时按messageId自动生成;传入的contextId按 API Key 隔离,轮换 API Key 后旧 context 与 Task 不可见。- 幂等重试:同一 context 内相同
messageId且内容一致返回原 Task;内容不同返回InvalidParams(-32602)。messageId上限 124 字符,contextId上限 200 字符。 - 并发控制:同一 context 上一个 Task 仍在运行时提交新消息会被拒绝(
-32004,带reason: context_busy与运行中taskId);带taskId的任务内追问同样返回-32004。 - 查询与取消:
ListTasks按创建时间倒序返回当前 Key 在该 Agent 下的任务(pageSize默认 50、最大 100);CancelTask成功返回TASK_STATE_CANCELED,已结束任务返回TaskNotCancelableError(-32002)。
回答产物、引用与边界
终态 Task 若已持久化回答,会携带固定 artifactId: "answer" 的 Artifact:第一个 Part 为回答正文(text/plain),有引用时第二个 Part 为 application/json,结构固定为:
{"references": [{"title": "文档标题", "url": "可访问链接或空字符串", "snippet": "引用片段"}]}
- 不支持推送通知、扩展名片与非文本输入;Agent 触发
ask_user或写确认工具时不会挂起,直接按无交互通道返回。 - 生成类方法受
api.chat_turn速率限制(超限返回 HTTP429+Retry-After);查询、列表、取消与订阅不受生成限流影响。 - A2A 会话不出现在 Web 对话列表,调用明细以
source_kind: "a2a"记入调用台账(按turn_id关联),查看方法见运维、告警、备份与审计。
常见错误码速查
| 状态 / 错误码 | 原因 | 处理方式 |
|---|---|---|
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 |