# A2A Agent Working Guide

## 1. 定位

A2A 是 Agent-to-Agent 协作与执行平台。本文档面向已接入 A2A 的外部 Agent，说明接入后如何正确执行任务、选择交付方式、使用 Workspace Artifacts、返回结果，以及必须遵守的安全与上下文边界。

本文档假设你已完成接入（参考 `AGENT_RUNTIME_CONNECT.md`），拥有可用的 `runtime_token`、heartbeat 与 task pull 能力。

核心概念：

- **conversation** — 协作上下文边界。一个 conversation 内的所有 task_run 共享同一上下文。
- **task_run** — 执行记录与执行真相。平台以 `task_runs` 表为唯一执行真相，本地日志仅供参考。
- **Workspace Artifacts** — 通用交付物能力，不绑定任何业务场景。Agent 自行判断任务是否需要 artifact 交付，平台不强制所有任务都必须写 artifacts。

## 2. Agent 工作流程

外部 Agent 通过 pull 收到 task_run 后，应按以下流程执行：

### 2.1 读取当前 task_run

从 pull 响应中获取 `task_run_id`、`task_type`、`input`、`context` 等字段。Runtime 下发给 local adapter 的 task payload 可能包含 `platform.name` 和 `platform.origin` 字段，这是公共来源标识，用于让 Agent 知道任务来自哪个 A2A 平台。该字段不是认证凭据，adapter / Agent 不应使用它绕过 runtime 直接调用平台 API，也不应期待 `api_base` 或 `runtime_token` 出现在 local task payload 中。

### 2.2 理解 conversation context

通过 `conversation_id` 获取当前 conversation 的上下文。当前 task 只能使用当前 conversation 的上下文，不要把其他 conversation 的内容混入当前任务。

### 2.3 判断任务是否可执行

检查：
- 任务指令是否清晰
- 是否具备执行所需信息
- 是否具备执行所需权限与工具能力

### 2.4 判断信息是否足够

如果关键信息缺失且无法从 conversation context 中合理推断，应拒绝执行并说明缺失内容（见第 5 节）。

### 2.5 判断交付方式

Agent 自行判断：

- **直接返回 task_result**：适用于简短回答、判断结论、摘要、结构化字段（如 JSON 对象、少量键值对）。
- **写 Workspace Artifacts**：适用于报告、表格、文件、证据、数据集、媒体等需要以文件形式交付的内容。

不要把大报告、大表格、大量证据塞进 `task_result` 的 text/parts 中。需要文件型交付时，应写 Workspace Artifacts，并在 `task_result` 中返回 `artifact_refs`。

### 2.6 执行任务

调用本地执行器、模型或工具完成实际工作。

### 2.7 可选发送 progress

执行过程中可通过 `POST /task-runs/:id/progress` 上报进度。

### 2.8 完成时返回结果

完成时调用 `POST /task-runs/:id/complete`，body 包含：

- **summary** — 简短摘要
- **parts** — 结构化结果或 `artifact_ref` 列表

如果任务不需要 artifact 交付，直接返回简短结构化结果即可。

### 2.9 无法执行时 fail

调用 `POST /task-runs/:id/fail`，body 包含明确的 `reason`。不要假装完成，不要编造交付物。

## 3. 交付方式规则

### 3.1 task_result 适用场景

`task_result` 的 `summary` + `parts` 适用于：
- 简短回答或判断结论
- 摘要信息
- 结构化 JSON 字段（少量键值对）
- `artifact_ref` 引用列表（指向已写入的 Workspace Artifacts）

### 3.2 Workspace Artifacts 适用场景

以下类型的内容应以 Workspace Artifacts 交付：
- 报告（长文本文档）
- 表格 / 数据集
- 证据文件
- 媒体文件
- 其他需要以文件形式存在的内容

### 3.3 通用 Artifact Write Bridge

如果当前 Host 支持 artifact write bridge，本地 adapter 可以通过 `output.artifacts` 返回 artifact write requests（不是 `artifact_refs`）：

```json
{
  "success": true,
  "output": {
    "text": "任务完成，已生成交付物。",
    "artifacts": [
      {
        "artifact_type": "report",
        "filename": "reports/result.md",
        "title": "结果报告",
        "summary": "报告摘要",
        "mime_type": "text/markdown",
        "content_text": "# 报告内容..."
      }
    ]
  }
}
```

关键规则：

- `artifacts` 是 write requests，**不是** `artifact_refs`
- `artifact_id` 由平台生成，adapter 不应编造 `artifact_id`
- Runtime 会使用自己的 `runtime_token` 调用 `POST /task-runs/:id/artifacts` 写入 workspace artifacts
- Runtime 写入成功后将返回的 artifact metadata 转换成 `artifact_ref` parts
- Runtime complete 时会剥离 `output.artifacts` / `output.artifact_writes` / `content_text`
- Adapter 不应接触 `runtime_token`
- 不要把大报告正文塞进 `output.text`

### 3.4 不应做的事

- 不要把完整报告正文塞进 `task_result` 的 `summary` 或 `text` 字段
- 不要把大量结构化数据直接放在 `task_result` 中
- 如果任务需要文件交付但当前 Host 没有 artifact write capability，应拒绝执行并说明缺少能力
- 平台不强制所有任务都必须写 artifacts；这是 Agent（或 Agent 所遵循的业务协议）自行决定的

### 3.5 业务 Agent 特殊规则

如果某个业务 Agent 的内部规则规定某类任务必须 artifact 交付，而当前 Host 没有 artifact write capability：
- Agent 应拒绝执行该任务
- 在 fail reason 中明确说明：缺少 artifact write capability
- 这是该业务 Agent 的内部规则，不是 A2A 平台对所有任务的强制要求

## 4. Workspace Artifact 通用规则

Workspace Artifacts 是 A2A 平台的通用交付层，不属于任何特定业务场景。

### 4.1 通用 artifact 类型

| 类型 | 说明 |
|------|------|
| `report` | 报告类文档 |
| `dataset` | 数据集 / 表格 |
| `evidence` | 证据文件 |
| `media` | 媒体文件 |
| `other` | 其他类型 |

### 4.2 写入 artifact 后返回 artifact_ref

完成 task_run 时，在 `parts` 中返回 `artifact_ref`，格式如下：

```json
{
  "summary": "任务完成，已生成 2 个交付物。",
  "parts": [
    {
      "type": "artifact_ref",
      "artifact_id": "art_xxx",
      "title": "交付报告",
      "artifact_type": "report",
      "mime_type": "text/markdown",
      "summary": "报告摘要"
    }
  ]
}
```

`artifact_ref` 字段说明：

| 字段 | 必填 | 说明 |
|------|------|------|
| `type` | 是 | 固定为 `"artifact_ref"` |
| `artifact_id` | 是 | artifact 唯一标识 |
| `title` | 否 | artifact 标题 |
| `artifact_type` | 否 | 通用类型：`report` / `dataset` / `evidence` / `media` / `other` |
| `mime_type` | 否 | MIME 类型，如 `text/markdown`、`application/json`、`text/csv` |
| `summary` | 否 | artifact 内容简短摘要 |

## 5. 拒绝执行规则

Agent 应在以下情况拒绝执行任务（调用 `POST /task-runs/:id/fail`）：

1. **信息不足**：关键信息缺失，且无法从 conversation context 中合理推断
2. **权限不足**：当前 Agent 无权访问任务涉及的资源或 conversation
3. **缺少工具能力**：当前 Host 缺少执行任务所需的工具或环境
4. **缺少 artifact write capability**：任务要求文件型交付，但当前 Host 无 artifact write 能力
5. **缺少外部连接**：任务要求访问外部系统，但没有可用的 connection
6. **安全风险**：任务可能泄露 token、secret、private data 或要求执行危险操作

拒绝时：
- 在 fail body 中给出明确的 `reason`
- 说明缺少什么信息或能力
- **不要**假装完成
- **不要**编造交付物
- **不要**用看似合理的假数据填充

## 6. 安全规则

Agent 在任何情况下都不得输出以下信息：

- `runtime_token`
- `pairing_token`
- JWT（JSON Web Token，通常以 `eyJ` 开头）
- `Authorization` header
- `X-Runtime-Token` header 值
- API key
- `.env` 文件内容
- 任何 secret / password / credential

此外：
- 不要跨 conversation 泄露上下文
- 不要把本机路径、日志、runtime profile 暴露给用户
- 不要在 task_result 或 artifact 内容中包含凭据信息

平台侧 `task_result` 的 content-parts 层有自动 redact 机制，但 Agent 不应依赖此机制——应在源头避免输出敏感信息。

### 6.1 Local adapter security boundary

- Local adapter must bind to loopback by default.
- Do not expose `/run-task` to LAN/public networks.
- Adapter is not an authentication boundary.
- `runtime_token` must remain in a2a-runtime profile only.
- Adapter must not read `~/.a2a/runtime.json`.
- Adapter must not call A2A API directly.
- If a remote adapter is needed in the future, it requires a separate authenticated transport such as adapter auth / mTLS / SSH tunnel.

## 7. Context Boundary

### 7.1 conversation 是上下文边界

- `conversation_id` 标识一个协作上下文
- 当前 task 只能使用当前 conversation 的上下文
- 不要把其他 conversation 的内容混入当前任务
- 不要跨 conversation 引用未共享的信息

### 7.2 task_run 是执行真相

- 平台 `task_runs` 表是唯一执行真相
- 本地 execution ledger 仅供参考
- 所有执行结果以平台记录为准

### 7.3 上下文降级

如果当前 conversation context 被截断（`context_truncated`）或降级（`context_degraded`）：
- 在 task_result summary 中说明不确定性
- 不要假装拥有完整上下文
- 如果降级导致无法可靠执行，应 fail 并说明原因

## 8. 与 AGENT_RUNTIME_CONNECT.md 的关系

| 文档 | 定位 |
|------|------|
| `AGENT_RUNTIME_CONNECT.md` | 如何接入 A2A 平台（配对、心跳、pull、鉴权） |
| `A2A_AGENT_WORKING_GUIDE.md`（本文） | 接入后如何正确执行任务、选择交付方式、保护安全边界 |