通信协议开发

本页只描述当前源码能够共同验证的 wire contract。它适合调试或实现实验性第三方 Adapter，不代表已经发布长期稳定的公共协议 SDK。

需求

第三方 Adapter 需要：

• 主动建立到 Agent Core TCP 服务的连接；
• 按 UTF-8 JSON、换行符 \n 分帧；
• 发送 JSON-RPC 2.0 请求、响应和通知；
• 持有与实例记录匹配的 instance_id 和 auth_token；
• 在握手后注册工具并处理 Agent Core 发来的调用。

当前 Adapter 实际目标为 127.0.0.1:27541。Agent Core 服务端监听设置不能推导出 Adapter 已支持跨主机配置。

架构

帧与消息

每个 JSON 值编码为一行：

{"jsonrpc":"2.0","method":"pong"}\n

Agent Core 和 Bedrock 都按 \n 累积拆帧。不要依赖 TCP 包边界，也不要在一帧中拼接多个 JSON 值。

握手与认证

Adapter 连接后发送带 id 的 handshake 请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "handshake",
  "params": {
    "instance_id": "<instance id>",
    "auth_token": "<secret token>",
    "version": {
      "protocol": "1.0.0",
      "edition": "java"
    },
    "mod": "<adapter version>"
  }
}

edition 当前使用 java 或 bedrock。Java 还可能发送实验性 world_name 与 world_online。成功响应的共同可依赖字段是：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "version": "<server version>",
    "server_name": "<server name>",
    "max_tools": 0
  }
}

Bedrock 源码明确在服务端未返回心跳间隔时使用 10 秒默认值。不要依赖旧文档中的固定 session_id 响应。

握手前除握手和心跳兼容消息外的请求会被拒绝，当前可见错误为 -32002 Not authenticated。认证失败和版本校验的精确错误结构应以目标 Agent Core 版本的 tcp/handshake.ts 为准。

工具注册

当前 Adapter 使用 register_tools 通知：

{
  "jsonrpc": "2.0",
  "method": "register_tools",
  "params": {
    "instance_id": "<instance id>",
    "tools": [
      {
        "name": "example_ping",
        "description": "返回连通状态",
        "category": "perception",
        "input_schema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      }
    ]
  }
}

Agent Core 收到后按工作区替换动态工具列表。工具 Schema 的可选字段和归一化逻辑仍可能变化；实现第三方 Adapter 时应针对目标版本测试。

工具调用

单次调用使用请求：

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tool_call",
  "params": {
    "tool_name": "example_ping",
    "parameters": {},
    "timeout_ms": 30000
  }
}

当前主 Agent pipeline 主要发送 tool_call_batch：

{
  "jsonrpc": "2.0",
  "id": "batch-1",
  "method": "tool_call_batch",
  "params": {
    "calls": [
      {
        "tool_name": "example_ping",
        "parameters": {},
        "timeout_ms": 30000
      }
    ]
  }
}

心跳和事件

Agent Core 发送 ping，Adapter 以 pong 回复；当前服务端兼容 pong 请求或通知。Adapter 还可发送 event、status_report 以及 Java 世界上线/离线通知。事件 payload 属于快速演进区，应直接对照目标版本处理器。

执行

1. 先实现换行分帧和 JSON-RPC id 匹配。
2. 连接后立即握手；认证成功前不要注册工具。
3. 用通知发送完整工具列表。
4. 实现 tool_call，再根据目标版本实现 tool_call_batch。
5. 对未知 method 返回 JSON-RPC -32601，对无效参数返回 -32602。
6. 记录 id、method、耗时和错误码，但绝不能记录 auth_token。
7. 分别与当前 Java、Bedrock 和 Agent Core 集成测试。

稳定边界

因此第三方 Adapter 必须声明兼容的 Alice/Agent Core 版本。不要把当前 1.0.0 字符串理解为已经承诺语义化向后兼容。