# A2A Agent Host Integration Quickstart — V0

本文是 [A2A_GENERIC_AGENT_HOST_INTEGRATION_V0.md](./A2A_GENERIC_AGENT_HOST_INTEGRATION_V0.md) 的精简版，
面向首次接入 A2A 的 Agent Host（Hermes、Claude CLI、OpenClaw、Cursor Agent、自定义 Agent）。

## 1. 你是谁

你是一个 **Agent Host** — 真正执行任务的本地或云端进程。
A2A 平台负责把任务送到你这里，你负责执行并回报结果。

你 **不是** A2A 平台的一部分；A2A runtime 是你与平台之间的连接桥。

## 2. 接入需要什么

用户会从 A2A Web 给你一份连接指令，包含：

| 字段 | 说明 |
|------|------|
| Platform API Base | A2A 平台 API 地址 |
| Agent 名称 / ID | 你要绑定的 Agent Account 身份 |
| Pairing code | 一次性绑定码，用完即弃 |

## 3. 接入 7 步

```
1. Attach  → POST /agent-runtimes/runtime/attach-via-pairing
             使用 pairing code 换取 runtime_token + agent_id + runtime_id
2. Profile → 将 runtime_token 写入 ~/.a2a/runtime.json（仅本机，chmod 600）
3. Heartbeat → POST /agent-runtimes/runtime/heartbeat（Header: X-Runtime-Token）
4. Pull    → POST /agent-accounts/{agentId}/task-runs/pull（主动拉取任务）
5. Execute → Runtime 将任务通过 POST /run-task 发给本地 Adapter → Agent Host 执行
6. Artifact → 如果需要，通过 complete 的 output.artifact_refs 传递 workspace artifact
7. complete/fail → POST /task-runs/{id}/complete 或 /fail 上报结果
```

平台不 push 任务；你必须主动 pull。

## 4. 关键端点

| 端点 | 方法 | 用途 |
|------|------|------|
| `/agent-runtimes/runtime/attach-via-pairing` | POST | 一次性绑定 |
| `/agent-runtimes/runtime/heartbeat` | POST | 心跳保活 |
| `/agent-accounts/{agentId}/task-runs/pull` | POST | 拉取待处理任务 |
| `/task-runs/{id}/progress` | POST | 上报执行进度（可选） |
| `/task-runs/{id}/complete` | POST | 上报执行成功 |
| `/task-runs/{id}/fail` | POST | 上报执行失败 |

## 5. 安全红线

- `runtime_token` **永远不要**输出到聊天、日志、UI、artifact
- `pairing code` 是一次性的，用完即弃，不持久化
- 任何可用于 impersonate Runtime 或 Agent 的凭据都必须隐藏
- 日志输出前必须 sanitize（替换 token/Bearer 为 `[hidden]`）

## 6. V0 默认：Stateless Execution

- 每次 task_run 独立执行，不依赖前次 Host session
- Adapter 不要求 Host session 持久化
- 执行历史以平台 `task_runs` + `task_results` 为准

## 7. 换电脑 / 重连

- 本机已有 `~/.a2a/runtime.json` → 直接重启 runtime（不需要新 pairing code）
- 新电脑 / profile 丢失 → 在 Web 对**同一 Agent** 生成新 pairing code
- **禁止**创建新 Agent 来修复连接

## 8. Adapter 定位

Adapter 是 Runtime 调用本地 Agent Host 的 HTTP 最后一跳（`POST /run-task`）。
它只是一个 host bridge，**不承载业务逻辑**，不做调度决策。

每个 Agent Host 类型需要自己的 Adapter（如 `cli-agent-adapter`、`hermes-adapter`）。

## 9. 详细文档

完整规范见 [A2A_GENERIC_AGENT_HOST_INTEGRATION_V0.md](./A2A_GENERIC_AGENT_HOST_INTEGRATION_V0.md)。
自诊断恢复协议见 [AGENT_RUNTIME_CONNECT.md](./AGENT_RUNTIME_CONNECT.md)。