选择场景 Agent,使用 A2A 发送任务,并处理 SSE 结果、任务状态与后续操作
什么是 Agent 服务
Agent 用于处理特定法律场景的任务。接入方通过 A2A 提交任务、接收流式事件,并根据任务状态处理结果、补充输入或错误。
服务索引列出 15 个场景 Agent,分为出海合规、专项合规、诉讼与执行、企业法务四类。具体接入时需核对目标 Agent 的访问权限与接入信息。
接入前准备
调用流程
1
选择 Agent 并核对接入信息
从服务索引选择目标 Agent,记录
agentCode,并按下方 Agent Card 说明核对名称、版本、能力描述与调用地址。2
发送任务
使用
message/stream 提交任务文本。为消息生成唯一的 messageId,将 Agent 编码填入 params.message.metadata.agentCode。3
接收事件并检查任务状态
按 SSE 事件读取增量内容和状态,保存返回的
taskId 与 contextId。根据状态处理完成、等待补充信息或失败;断线后的操作见下文。服务地址
下表列出服务基础地址、请求路径和完整请求地址。查询 Agent Card 时,将 <agentCode> 替换为目标 Agent 详情页中的编码。
| 配置项 | 配置值 |
|---|---|
| 服务基础地址 | https://farui.cn-beijing.aliyuncs.com |
| Agent 调用方法与路径 | POST /a2a/agent |
| Agent 调用地址(完整 URL) | https://farui.cn-beijing.aliyuncs.com/a2a/agent |
| Agent Card 方法与路径 | GET /a2a/.well-known/agent-card.json?agentCode=<agentCode> |
| Agent Card 地址(完整 URL) | https://farui.cn-beijing.aliyuncs.com/a2a/.well-known/agent-card.json?agentCode=<agentCode> |
请求头
调用 Agent 时携带以下 HTTP 请求头。认证方式与检索 API 相同,JSON 请求体按下方 A2A 格式填写。
| 请求头 | 填写说明 |
|---|---|
Authorization | 必填,填写 API Key 原文,省略 Bearer 前缀 |
x-acs-date | 必填,填写发起请求时的 UTC 时间,使用 ISO 8601 格式,精确到秒并以 Z 结尾,每次请求重新生成 |
x-acs-version | 必填,填写 2026-10-19 |
Content-Type | JSON 请求体使用 application/json |
x-acs-date 必须是本次请求发起时的 UTC 时间,使用 ISO 8601 格式,精确到秒并以 Z 结尾,例如 2026-11-10T08:00:00Z。首次消息、后续任务操作和重试都要重新生成。
读取 Agent Card
使用上表路径并填入目标 agentCode,查询名称、版本、能力说明和技能。卡片的 url 字段提供调用地址。
以下为 Agent Card 结构示例,不是某个 Agent 的实时卡片:
skills 列出该 Agent 的技能名称、描述和标签。
发送流式消息
向 POST /a2a/agent 发送 message/stream 请求,响应为 SSE。下面的 JSON 是请求体模板;替换 Agent 编码和任务文本,并为本次消息生成唯一的 messageId。
文本任务
| 文件类型 | 扩展名 | mimeType 填写值 |
|---|---|---|
| Markdown | .md | text/markdown |
.pdf | application/pdf | |
| JPEG 图片 | .jpg、.jpeg | image/jpeg |
| PNG 图片 | .png | image/png |
| Word 97–2003 | .doc | application/msword |
| Word Open XML | .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| text或者txt | .text或.txt | text/plain |
curl 请求示例
将上方请求体保存为 UTF-8 编码的 request.json。将目标环境的服务基础地址设为 FARUI_API_BASE_URL,个人 API Key 原文设为环境变量 FARUI_API_KEY,然后发送请求:
消息字段
以下 message.* 字段均位于请求的 params 对象中,例如 Agent 编码的完整路径为 params.message.metadata.agentCode。
string
path
required
消息唯一标识。重试同一消息时使用原标识及原内容,内容冲突时会返回
-32010。string
path
required
用户消息固定为
user。array
path
required
消息片段列表。文本片段使用
kind: text 和 text 字段。string
path
可选对话上下文标识,多轮对话时沿用已有上下文。
string
path
可选任务标识,需要恢复已有任务时使用。
string
path
required
Agent 路由身份。缺失、无法识别或与已有任务归属冲突时,请求会被拒绝。
tenantId 和 userId 由服务端根据 API Key 补充。调用方禁止在请求中传入这两个字段,包括首次消息和后续任务操作。接入方应自行生成唯一的 messageId,保存返回的任务与上下文标识,并按 SSE 事件流处理增量结果、状态和错误。不要在每次重试时生成新的消息标识。处理 SSE 事件
接收 SSE 时检查每个 data 帧中的 JSON-RPC 响应:有 error 时按错误处理;业务事件通过 result.kind 区分,主要包括 status-update、artifact-update 和 data。以下均为结构示例,taskId、contextId 和时间戳使用示意值。
状态事件:
Task 状态
| 状态 | 含义 | 当前流处理 |
|---|---|---|
submitted | 任务已提交 | 继续接收事件 |
working | Agent 正在执行 | 继续接收事件 |
input-required | 等待用户补充信息 | 当前流结束,保存任务与上下文并等待后续回答 |
completed | 任务成功完成 | 终态,结束处理 |
failed | 任务执行失败 | 终态,记录错误并结束处理 |
canceled | 任务已取消 | 终态,结束处理 |
input-required 不是业务终态,事件中的 final 可为 false,但当前 SSE 流会结束。后续回答必须沿用正确的任务与上下文归属,不能把等待输入误判为 completed。流式错误
错误也可能出现在 SSE data 帧中,因此不能只检查普通 HTTP 或 JSON 响应:
后续任务操作
根据已有任务的状态选择操作,并保留原任务的 Agent 与调用方归属。
| 方法 | 用途 | 响应形式 |
|---|---|---|
message/stream | 发送消息并接收任务事件 | SSE |
tasks/get | 查询当前任务状态与结果 | JSON-RPC |
tasks/cancel | 取消任务 | JSON-RPC |
tasks/resubscribe | 重新订阅已有任务事件 | SSE |
askQuestion/answer | 回答 Agent 的追问 | SSE |
tasks/get 返回任务当前的状态与结果,不返回完整状态迁移历史;只有 completed 状态的返回内容包含最终正文 artifact。
断线后重新订阅
收到任务标识后若 SSE 断开,通过 tasks/resubscribe 重新订阅同一任务。params.id 使用原 taskId,params.metadata.agentCode 使用原 Agent 编码。若已保存 SSE 的 id,将它原样放入 params.lastEventId。
-32014,先使用 tasks/get 查询任务状态,再决定是否需要发起新任务。