A2A 连接与任务协作

A2A 连接 Agent，MCP 连接工具。本指南描述灵犀指本地内核当前暴露的接口；它不是云端账户 API，也不保证兼容任意版本的第三方 A2A 客户端。注册远端 Agent、创建委派记录和实际远程执行是不同操作。

1. 启动和认证

先启动 IDE／内核并登录，确认本地许可有效。内核默认监听回环地址；端口冲突时会选择其他端口，以实际配置或启动日志为准，不要直接使用文档中的示例端口。

全局配置目录由 LINGXIZHI_HOME 决定，未指定时使用可执行文件同级 data。其中 lxz.config.json 的 server.auth_token 是本地访问令牌，空值时内核会生成并写回。不要将配置、令牌或带认证头的命令输出上传到公开日志。

当前组合路由有三层检查：本地 server.auth_token、有效登录许可，以及 A2A 的 A2A_API_KEY。两个令牌检查都读取同一个 Authorization: Bearer ...，因此当前配置必须使 A2A_API_KEY 等于本地 server.auth_token。在启动内核的进程环境中设置后重启；只给已经启动的进程外部设置环境变量不会生效。这个令牌也能访问本地其他受保护接口，只应交给可信客户端，不要通过公网暴露服务。

发现入口 /.well-known/agent-card.json 公开；业务接口需要上述认证。A2A_AUTH_ENABLED=false／0 是开发绕过选项，不是正常配置方法，且不会取消全局认证和许可检查。

下面变量由你替换，尖括号不是有效凭据。令牌从本机配置安全读取，勿将真实值提交进脚本仓库：

$a2aBase = 'http://127.0.0.1:<实际端口>'
$a2aToken = '<本地 server.auth_token，与启动环境 A2A_API_KEY 一致>'
$headers = @{ Authorization = "Bearer $a2aToken" }
Invoke-RestMethod "$a2aBase/.well-known/agent-card.json"

Card 返回描述、能力和端点。它不代表你的登录许可或模型凭据已经可用。执行前设置启动环境 LXZ_PROJECT_ROOT 为允许 Agent 操作的项目目录；未设置时任务使用内核进程当前目录。

2. 创建、查询和取消任务

REST 请求字段使用 camelCase，成功包装为 {"success":true,"data":...}；业务失败通常是 HTTP 400 和 {"success":false,"error":"..."}。创建成功只说明任务已提交，执行结果仍需查询。

$body = @{ text = '请只分析项目目录结构，不修改文件' } | ConvertTo-Json
$created = Invoke-RestMethod "$a2aBase/api/a2a/tasks/create" -Method Post -Headers $headers -ContentType 'application/json' -Body $body
if (-not $created.success) { throw $created.error }
$taskId = $created.data.id
$contextId = $created.data.contextId
Invoke-RestMethod "$a2aBase/api/a2a/tasks/$taskId" -Headers $headers

data 含 id、contextId、status、history、artifacts、metadata。status.state 使用 submitted、working、completed、failed、canceled 等小写连字符值。只有终态及其结果能证明执行结束；不要把 submitted 当作完成。协议还定义 input-required、auth-required、rejected，并非每条执行路径都会发出所有状态。

后续请求可提供 contextId 关联任务，可选 skill 指定能力。它不是后台管理角色或云端账户权限。

$followUp = @{ text = '继续说明各目录用途'; contextId = $contextId } | ConvertTo-Json
# 确有需要时再提交，避免重复启动任务。
# Invoke-RestMethod "$a2aBase/api/a2a/tasks/create" -Method Post -Headers $headers -ContentType 'application/json' -Body $followUp

# 对仍在运行且确实需要停止的任务执行：
Invoke-RestMethod "$a2aBase/api/a2a/tasks/$taskId/cancel" -Method Post -Headers $headers

取消不会撤销任务已经写入的文件或其他外部副作用。终态任务可能无法再次取消，读取返回的业务错误即可，不应盲目重试创建。

3. 接收 SSE 事件

已创建任务可通过 GET /api/a2a/tasks/:id/stream 接收事件。使用支持设置 Bearer 头的客户端；浏览器原生 EventSource 无法直接设置该头，不能以 query token 假定能通过 A2A 认证。

curl.exe --no-buffer --header "Authorization: Bearer $a2aToken" "$a2aBase/api/a2a/tasks/$taskId/stream"

事件名包括 task-created、task-updated、task-completed、task-failed、task-canceled，内容按 event:／id:／data: 解析。流断开后重新查询任务状态，不能把连接关闭本身当作成功。REST 流不提供持久历史重放承诺；晚订阅可能只能看到终态，客户端必须处理这一情况。

需要提交并立即订阅时，向 /a2a/subscribe POST JSON-RPC tasks/sendSubscribe 请求，返回 SSE；也可以向 /a2a/jsonrpc 调用同名方法，取得订阅 ID，再连接 /a2a/sse/:subscription_id。不要混淆任务 ID 与订阅 ID。

4. JSON-RPC 调用

POST /a2a/jsonrpc 使用相同认证。下面是查询已有任务的请求体；将 taskId 替换为实际值：

{
  "jsonrpc": "2.0",
  "id": "read-task-1",
  "method": "tasks/get",
  "params": { "taskId": "a2a_<实际 ID>" }
}

支持 tasks/send、tasks/get、tasks/list、tasks/cancel、tasks/sendSubscribe、tasks/pushNotification/set、agents/card。JSON-RPC 结果在 result，错误在 error，即使 HTTP 200 也需要检查协议错误。

创建任务的 params.message 必须有 role、parts 和 Unix 秒 timestamp，不能直接把 REST 的 text 体发到 JSON-RPC：

{
  "jsonrpc": "2.0",
  "id": "create-task-1",
  "method": "tasks/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "只分析，不修改文件" }],
      "timestamp": 1793232000
    }
  }
}

示例 timestamp 仅演示格式，实际发送使用当前 Unix 秒。回调配置属于主动对外 HTTP 调用，配置前核对目标地址和允许发送的数据，不要将推送能力等同于可靠消息队列。

5. 注册、发现、信任与委派

注册用于描述外部 Agent，以下最小体可提交至 POST /api/a2a/agents/register：

{
  "id": "team-review-agent",
  "name": "Team review agent",
  "version": "1.0.0",
  "organization": "example-team",
  "description": "内部审查服务",
  "capabilities": [],
  "endpoints": []
}

空能力和端点只适合验证注册流程，不能据此执行远程协作。真实能力结构包含 name、description、inputSchema、outputSchema；端点含 url、protocol、description，协议枚举须匹配当前内核类型。

发现时 skill 优先于 organization，两者不是自动组合过滤；minTrustScore 和 capabilities 还会后置过滤。信任事件支持 success、failure、timeout、cancelled、security_violation、endorsement、complaint；它是调用方上报，不是外部认证证明。

委派要求目标信任分至少 30。当前 REST 委派返回 requestId、chainId 等记录信息，该接口本身不发起远端任务执行，不能拿它的成功返回当作远端已完成工作。注册中心条目的 trust level 与信任引擎分数也并非自动同步的同一存储。

限制与排错

任务、上下文、注册中心、信任及委派状态保存在内存，重启后不能恢复。任务池上限 100，订阅上限 200，每订阅事件缓冲 64 条，任务监控超时 30 分钟；不要用于需要长期可追溯或可靠重放的外部生产编排。A2A 请求体上限 1 MiB。

内核 API · MCP 配置

Hook 自动化