a2a-server

Agent-to-Agent (A2A) Communication Server - 基于 WebSocket 的多智能体 P2P 通信系统

描述

实现 AI Agent 之间的实时通信和协作：

• P2P 消息转发 - Agent 间直接通信，低延迟（~10ms）
• RPC 调用 - 请求/响应模式，支持超时控制
• 发布/订阅 - 频道广播，支持多订阅者
• 能力发现 - 按能力搜索 Agent，动态路由
• 离线消息 - 支持离线 Agent，消息队列存储
• 心跳机制 - 自动检测离线，自动清理

功能

• ✅ Agent 注册与发现 - 动态注册、能力公告、元数据管理
• ✅ P2P 消息转发 - WebSocket 双向通信、低延迟
• ✅ RPC 调用 - correlationId 追踪、超时控制、错误处理
• ✅ 发布/订阅 - 频道管理、多订阅者支持
• ✅ 能力发现 - 按能力/元数据筛选、实时查询
• ✅ 离线消息队列 - 内存存储、大小限制（100 条）、自动投递
• ✅ 心跳机制 - 定期心跳、超时检测（90 秒）、自动清理
• ✅ 自动重连 - 指数退避、最大尝试次数、连接恢复
• ⏳ 信任链授权 - 待实现
• ⏳ 消息签名 - 待实现

安装

# 从 ClawHub 安装（待发布）
clawhub install a2a-server

# 或手动克隆
git clone https://github.com/YOUR_GITHUB/skills/a2a-server
cd skills/a2a-server
npm install

快速开始

1. 启动服务器

npm start
# 或
node src/server.js

# 环境变量
# A2A_PORT=8080
# A2A_HOST=localhost
# A2A_VERBOSE=true

2. 客户端连接

const { A2AClient } = require('./src/client');

const client = new A2AClient('ws://localhost:8080', {
  agentId: 'my-agent',
  capabilities: ['search', 'analyze'],
  metadata: { version: '1.0.0' },
  verbose: true,
});

await client.connect();
console.log('✅ 已连接并注册');

3. RPC 调用

// 调用远程 Agent
const result = await client.call('remote-agent', {
  action: 'search',
  query: 'AI trends'
});

console.log(result);

4. 发布/订阅

// 订阅频道
await client.subscribe('notifications');

client.on('message', (payload, from) => {
  console.log(`收到 ${from}:`, payload);
});

// 发布消息
await client.publish('notifications', {
  type: 'task-complete',
  taskId: '123'
});

5. 能力发现

// 发现所有 Agent
const agents = await client.discover();

// 按能力发现
const searchAgents = await client.discover({
  capability: 'search'
});

console.log(`找到 ${searchAgents.length} 个搜索 Agent`);

配置选项

Server 配置

Client 配置

API 参考

A2AServer

constructor(options)

创建服务器实例。

start()

启动服务器，返回 Promise。

stop()

停止服务器，关闭所有连接。

getStats()

获取统计信息：

{
  totalConnections: 100,
  totalMessages: 500,
  activeAgents: 10,
  uptime: 3600,
  memoryUsage: {...}
}

getAgents()

获取已注册 Agent 列表：

[
  {
    agentId: 'agent-1',
    capabilities: ['search'],
    metadata: {...},
    registeredAt: Date,
    lastHeartbeat: Date
  }
]

broadcast(payload, exclude)

广播消息给所有 Agent。

A2AClient

constructor(serverUrl, options)

创建客户端实例。

connect()

连接服务器，自动注册。

disconnect()

断开连接。

call(targetAgentId, payload, options)

RPC 调用：

• targetAgentId - 目标 Agent
• payload - 调用参数
• options.timeout - 超时（默认 30s）
• 返回：Promise<result>

publish(channel, payload)

发布消息到频道。

subscribe(channel)

订阅频道。

unsubscribe(channel)

取消订阅。

discover(options)

能力发现：

• options.capability - 按能力筛选
• options.filter - 按元数据筛选
• 返回：Promise<Agent[]>

heartbeat()

发送心跳。

getStatus()

获取连接状态：

{
  connected: true,
  registered: true,
  agentId: 'my-agent',
  reconnectAttempts: 0
}

on(event, listener)

事件监听：

• connected - 连接成功
• disconnected - 断开连接
• registered - 注册成功
• reconnecting - 重连中
• reconnected - 重连成功
• message - 收到频道消息

使用场景

场景 1: 多智能体协作

// Planner Agent
const planner = new A2AClient('ws://localhost:8080', {
  agentId: 'planner',
  capabilities: ['planning', 'analysis']
});
await planner.connect();

// Executor Agent
const executor = new A2AClient('ws://localhost:8080', {
  agentId: 'executor',
  capabilities: ['execution', 'tool-use']
});
await executor.connect();

// Planner 调用 Executor
const result = await planner.call('executor', {
  action: 'execute',
  task: 'analyze code'
});

场景 2: 分布式搜索

// Search Agent 注册
const searchAgent = new A2AClient('ws://localhost:8080', {
  agentId: 'search-001',
  capabilities: ['web-search', 'tavily']
});
await searchAgent.connect();

// 发现搜索 Agent
const agents = await client.discover({ capability: 'web-search' });

// 调用搜索
const result = await client.call(agents[0].agentId, {
  query: 'AI trends 2026'
});

场景 3: 通知系统

// 订阅通知
await client.subscribe('system-alerts');

client.on('message', (payload, from) => {
  if (payload.type === 'alert') {
    console.log(`⚠️ 告警：${payload.message}`);
  }
});

// 发布告警
await client.publish('system-alerts', {
  type: 'alert',
  level: 'warning',
  message: 'High CPU usage detected'
});

与现有系统集成

集成 Multi-Agent

const { MultiAgentOrchestrator } = require('../multi-agent');
const { A2AClient } = require('../a2a-server');

const a2a = new A2AClient('ws://localhost:8080', {
  agentId: 'planner-agent',
  capabilities: ['planning']
});
await a2a.connect();

const orchestrator = new MultiAgentOrchestrator();

// 注册远程工具
orchestrator.registerTool('remote-execute',
  async (params) => {
    const agents = await a2a.discover({ capability: 'execution' });
    return await a2a.call(agents[0].agentId, params);
  },
  { description: '远程执行', keywords: ['执行', '远程'] }
);

集成 ReAct Orchestrator

const { ReActOrchestrator } = require('../react-orchestrator');
const { A2AClient } = require('../a2a-server');

const orchestrator = new ReActOrchestrator();
const a2a = new A2AClient('ws://localhost:8080', {
  agentId: 'react-agent',
  capabilities: ['reasoning']
});
await a2a.connect();

// 注册远程工具
orchestrator.registerTool('remote-search',
  async (params) => {
    const agents = await a2a.discover({ capability: 'search' });
    return await a2a.call(agents[0].agentId, params);
  },
  { description: '远程搜索', keywords: ['搜索', '远程'] }
);

测试

# 运行所有测试
npm test

# 运行测试并监视
npm run test:watch

# 调试模式运行
npm run test:debug

测试框架

• 测试运行器: Jest v29.7.0
• 覆盖率目标: >80%
• 测试超时: 30秒（可配置）

测试覆盖

• ✅ 服务器基础功能（启动/停止/统计）
• ✅ Agent 注册/注销/心跳
• ✅ RPC 调用/响应（在线/离线/超时）
• ✅ 发布/订阅（单订阅者/多订阅者）
• ✅ 能力发现（全部/按能力/按元数据）
• ✅ 离线消息队列
• ✅ 错误处理
• ✅ 并发连接

测试文件

• test/a2a.test.js - 完整 Jest 测试套件
• TEST-STATUS.md - 详细测试状态

消息协议

注册消息

{
  "type": "register",
  "agentId": "planner-001",
  "capabilities": ["planning", "analysis"],
  "metadata": { "version": "1.0.0" }
}

RPC 调用

{
  "type": "call",
  "from": "planner-001",
  "to": "executor-001",
  "correlationId": "uuid-123",
  "payload": { "action": "execute", "task": "..." }
}

RPC 响应

{
  "type": "response",
  "to": "planner-001",
  "correlationId": "uuid-123",
  "payload": { "result": "success" }
}

发布消息

{
  "type": "publish",
  "channel": "notifications",
  "from": "system",
  "payload": { "type": "alert", "message": "..." }
}

性能基准

延迟（本地）

并发

已知限制

• ⚠️ 离线消息 - 内存存储，重启丢失（未来用 Redis）
• ⚠️ 认证授权 - 尚未实现（信任链待开发）
• ⚠️ 消息签名 - 尚未实现（防止伪造）
• ⚠️ 集群支持 - 单服务器（未来支持多节点）

依赖

• Node.js >= 18.0.0
• ws ^8.16.0
• uuid ^9.0.0

版本历史

v0.1.0 (2026-03-18)

• ✅ 初始版本
• ✅ WebSocket 服务器
• ✅ A2A Client
• ✅ RPC 调用
• ✅ 发布/订阅
• ✅ 能力发现
• ✅ 心跳机制

许可证

MIT

作者

小蒲萄 (Clawd) 🦞

贡献

欢迎提交 Issue 和 PR！

参考资料

• README.md - 使用指南
• IMPLEMENTATION-NOTES.md - 实施笔记
• A2A-RESEARCH.md - 调研报告