跳转到内容
Awaken

A2A 协议

A2A 适配器实现了官方 A2A 协议，用于远程 agent 发现、任务委托与 agent 间通信。

Feature gate：server

端点

Section titled “端点”
路径方法说明
/.well-known/agent-card.jsonGET公共/默认 agent card 发现端点。
/v1/a2a/message:sendPOST向公共/默认 A2A agent 发送消息，返回 task 包装结果。
/v1/a2a/message:streamPOST通过 SSE 进行流式发送。
/v1/a2a/tasksGET列出 A2A 任务。
/v1/a2a/tasks/:task_idGET按 task ID 查询状态。
/v1/a2a/tasks/:task_id:cancelPOST取消运行中的任务。
/v1/a2a/tasks/:task_id:subscribePOST通过 SSE 订阅任务更新。
/v1/a2a/tasks/:task_id/pushNotificationConfigsPOST创建推送通知配置。
/v1/a2a/tasks/:task_id/pushNotificationConfigsGET列出推送通知配置。
/v1/a2a/tasks/:task_id/pushNotificationConfigs/:config_idGET / DELETE读取或删除推送通知配置。
/v1/a2a/extendedAgentCardGET扩展 agent card；只有 capabilities.extendedAgentCard=true 时才受支持。

租户/agent 作用域的等价路由位于 /v1/a2a/:tenant/...，例如 /v1/a2a/research/message:send、/v1/a2a/research/tasks/:task_id 和 /v1/a2a/research/tasks/:task_id/pushNotificationConfigs。

Agent Card

Section titled “Agent Card”

发现端点返回描述接口与能力的 AgentCard：

{
  "name": "My Agent",
  "description": "A helpful assistant",
  "supportedInterfaces": [
    {
      "url": "https://example.com/v1/a2a",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "general",
      "name": "General Q&A",
      "description": "Answer general questions",
      "tags": ["qa"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain"]
    }
  ]
}

Agent card 由已注册的 AgentSpec 生成。旧版顶层 url / id 字段不会再输出。

Message Send

Section titled “Message Send”
{
  "message": {
    "taskId": "optional-client-provided-id",
    "contextId": "optional-client-provided-id",
    "messageId": "msg-123",
    "role": "ROLE_USER",
    "parts": [{ "text": "Summarize this document" }]
  },
  "configuration": {
    "returnImmediately": true
  }
}

服务端会把 A2A task 映射到 Awaken 的 thread / mailbox 执行链路。响应使用 v1 的 task 包装结构：

{
  "task": {
    "id": "optional-client-provided-id",
    "contextId": "optional-client-provided-id",
    "status": {
      "state": "TASK_STATE_SUBMITTED"
    }
  }
}

如果未设置 returnImmediately 或传入 false，适配器会等待任务进入终态或中断态后再返回。

Task 状态

Section titled “Task 状态”

GET /v1/a2a/tasks/:task_id 返回 Task 资源：

{
  "id": "abc-123",
  "contextId": "abc-123",
  "status": {
    "state": "TASK_STATE_COMPLETED",
    "message": {
      "messageId": "msg-response",
      "role": "ROLE_AGENT",
      "parts": [{ "text": "..." }]
    }
  },
  "history": []
}

任务状态使用 v1 枚举名，例如 TASK_STATE_SUBMITTED、TASK_STATE_WORKING、TASK_STATE_COMPLETED、TASK_STATE_FAILED、TASK_STATE_CANCELED。

可选能力默认值

Section titled “可选能力默认值”

Awaken 当前默认启用以下 A2A 能力：

  • streaming = true
  • pushNotifications = true

extendedAgentCard 仍然是可选能力，只有在配置 ServerConfig.a2a_extended_card_bearer_token 后才会启用。未启用时，对应端点会返回符合规范的 unsupported 错误。

远程 Agent 执行

Section titled “远程 Agent 执行”

Awaken agent 可以通过内置 A2aBackend 运行或委托到远程 A2A agent；它是一个 ExecutionBackend 实现。委托时，父 agent 的 LLM 看到的是普通工具调用。root execution 时，AgentRuntime 会把 endpoint-backed agent 解析成 backend-backed execution plan。

backend 会向远端发送 message:send 请求，读取返回的 task.id，再通过 stream 或轮询 /tasks/:task_id 直到任务进入终态或中断态。它会保留远端生命周期状态，用于 continuation、等待输入/认证、取消和 artifact 输出。

远程 agent 配置写在 AgentSpec 中。RemoteEndpoint 是通用结构，A2A 通过 backend: "a2a" 指定：

{
  "id": "remote-researcher",
  "endpoint": {
    "backend": "a2a",
    "base_url": "https://remote-agent.example.com/v1/a2a",
    "auth": { "type": "bearer", "token": "..." },
    "target": "researcher",
    "timeout_ms": 300000,
    "options": {
      "poll_interval_ms": 1000
    }
  }
}

带 endpoint 的 agent 在注册了匹配 backend factory 时会按远程 backend agent 解析。当前内置远程 backend 是 A2A；没有 endpoint 的 agent 仍在本地运行。

另见

Section titled “另见”