Skip to main content

Agent 接入指南

选择场景 Agent,使用 A2A 发送任务,并处理 SSE 结果、任务状态与后续操作

什么是 Agent 服务

Agent 用于处理特定法律场景的任务。接入方通过 A2A 提交任务、接收流式事件,并根据任务状态处理结果、补充输入或错误。 服务索引列出 15 个场景 Agent,分为出海合规、专项合规、诉讼与执行、企业法务四类。具体接入时需核对目标 Agent 的访问权限与接入信息。

接入前准备

准备项说明
API Key 与权限按接入认证准备已启用的个人 API Key,并使用具有目标 Agent 访问权限的身份调用
agentCode从目标 Agent 详情页获取实际编码,用于指定场景 Agent;不要使用名称拼音或其他 Agent 的编码代替
调用方身份由服务端根据 API Key 补充,请求中禁止传入 tenantId 和 userId
请求头Authorization 填写 API Key 原文,x-acs-date 每次请求重新生成;版本与请求体格式见下方请求头
客户端按 JSON-RPC 2.0 组织请求,并处理 SSE 事件流中的数据、状态和错误

调用流程

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-TypeJSON 请求体使用 application/json
x-acs-date 必须是本次请求发起时的 UTC 时间,使用 ISO 8601 格式,精确到秒并以 Z 结尾,例如 2026-11-10T08:00:00Z。首次消息、后续任务操作和重试都要重新生成。

读取 Agent Card

使用上表路径并填入目标 agentCode,查询名称、版本、能力说明和技能。卡片的 url 字段提供调用地址。 以下为 Agent Card 结构示例,不是某个 Agent 的实时卡片:
{
  "protocolVersion": "0.2.1",
  "name": "<Agent名称>",
  "version": "<版本>",
  "description": "<Agent描述>",
  "url": "<卡片返回的调用地址>",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "<技能ID>",
      "name": "<技能名称>",
      "description": "<技能描述>",
      "tags": ["<标签>"]
    }
  ]
}
skills 列出该 Agent 的技能名称、描述和标签。

发送流式消息

向 POST /a2a/agent 发送 message/stream 请求,响应为 SSE。下面的 JSON 是请求体模板;替换 Agent 编码和任务文本,并为本次消息生成唯一的 messageId。 文本任务
当前运行时不支持 message/send,流式发起任务请使用 message/stream。
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/stream",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "msg-001",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "<任务文本>"
        }
      ],
      "metadata": {
        "agentCode": "<Agent 编码>"
      }
    }
  }
}
文件任务
{
  "jsonrpc": "2.0",
  "id": "req-file-290edd5af20a42e395087ee64ec99f48",
  "method": "message/stream",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "msg-file-6134ef55670d4daaa18c2bced41d1f85",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "分析下这块上传文件的内容"
        },
        {
          "kind": "file",
          "file": {
            "uri": "https://example.com/files/document.md",
            "name": "乌兹别克斯坦更新进口中国鲜食柑橘植物检疫要求.md",
            "mimeType": "text/markdown"
          }
        }
      ],
      "metadata": {
        "agentCode": "farui-assistant"
      }
    }
  }
}
mimeType枚举类型
文件类型扩展名mimeType 填写值
Markdown.mdtext/markdown
PDF.pdfapplication/pdf
JPEG 图片.jpg、.jpegimage/jpeg
PNG 图片.pngimage/png
Word 97–2003.docapplication/msword
Word Open XML.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
text或者txt.text或.txttext/plain

curl 请求示例

将上方请求体保存为 UTF-8 编码的 request.json。将目标环境的服务基础地址设为 FARUI_API_BASE_URL,个人 API Key 原文设为环境变量 FARUI_API_KEY,然后发送请求:
curl --no-buffer --request POST \
  --url "${FARUI_API_BASE_URL%/}/a2a/agent" \
  --header "Authorization: ${FARUI_API_KEY}" \
  --header "x-acs-date: $(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
  --header 'x-acs-version: 2026-10-19' \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

消息字段

以下 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 和时间戳使用示意值。 状态事件:
data: {"jsonrpc":"2.0","id":"req-001","result":{"kind":"status-update","taskId":"task-001","contextId":"ctx-001","status":{"state":"working","timestamp":"2026-11-06T08:00:00Z"},"final":false}}
文本产物增量事件:
data: {"jsonrpc":"2.0","id":"req-001","result":{"kind":"artifact-update","taskId":"task-001","contextId":"ctx-001","artifact":{"artifactId":"artifact-001","parts":[{"kind":"text","text":"<增量文本>"}]},"append":true,"lastChunk":false}}
心跳是不含业务数据的注释帧,客户端应忽略其内容并保持连接:
: ping

Task 状态

状态含义当前流处理
submitted任务已提交继续接收事件
workingAgent 正在执行继续接收事件
input-required等待用户补充信息当前流结束,保存任务与上下文并等待后续回答
completed任务成功完成终态,结束处理
failed任务执行失败终态,记录错误并结束处理
canceled任务已取消终态,结束处理
input-required 不是业务终态,事件中的 final 可为 false,但当前 SSE 流会结束。后续回答必须沿用正确的任务与上下文归属,不能把等待输入误判为 completed。

流式错误

错误也可能出现在 SSE data 帧中,因此不能只检查普通 HTTP 或 JSON 响应:
data: {"jsonrpc":"2.0","id":"req-001","error":{"code":-32015,"message":"Agent未激活或不存在","data":null}}
主要错误码与排查方法见错误与排障。

后续任务操作

根据已有任务的状态选择操作,并保留原任务的 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。
{
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "tasks/resubscribe",
  "params": {
    "id": "task-001",
    "lastEventId": "1",
    "metadata": {
      "agentCode": "<原 Agent 编码>"
    }
  }
}
检查重新订阅的响应和后续事件。若返回 -32014,先使用 tasks/get 查询任务状态,再决定是否需要发起新任务。