# 调用智能体

通过 Product API 向已经发布的智能体发送消息，并持续查询任务，直到取得结果或智能体要求补充输入。

第一次调用按以下顺序进行：

1. 获取智能体调用信息，确认智能体标识和能力；
2. 发送消息并保存任务 ID；
3. 查询任务状态与结果；
4. 任务要求补充信息时，提交用户输入。

A2A 是应用与智能体通信所使用的协议。你不需要先掌握完整协议；各页面会在用到时说明请求 ID、任务、上下文和智能体产物等对象。

## 调用前

- 已按[开始使用 Product API](../getting-started.md)准备 Product API Base URL 和个人访问令牌。
- 已取得目标工作区 ID。
- 已取得一个当前工作区可用的智能体 ID 或智能体代码。

调用相关接口使用：

```text
X-API-Key: <PERSONAL_ACCESS_TOKEN>
X-Workspace-ID: <WORKSPACE_ID>
```

## 调用过程中的标识

| 值 | 来源 | 后续用途 |
| --- | --- | --- |
| `agent_id` 或 `agent_code` | 智能体列表、详情或调用信息 | 每次请求选择同一个智能体。 |
| JSON-RPC `id` | 由调用方生成 | 关联一次请求和响应，不是任务 ID。 |
| `messageId` | 由调用方生成 | 标识一条用户消息，并辅助安全重试。 |
| Task `id` | 发送消息的响应 | 查询、取消任务或提交补充输入。 |
| `contextId` | 智能体响应 | 让后续普通消息继续同一会话。 |
| `turnId` | 智能体响应 | 任务请求结构化补充输入时使用。 |

Task 是智能体的一次执行。发送消息后，服务端可能立即返回结果，也可能返回仍在运行的任务。应用必须读取任务状态，不能把 HTTP 请求成功当作智能体已经完成工作。

```{toctree}
:hidden:
:maxdepth: 1

获取智能体调用信息 <get-agent-card>
发送消息并启动任务 <call-agent-a2a>
查询任务状态与结果 <query-task-status-results>
提交后续输入 <submit-follow-up-input>
```