A2A 通信协议框架

A2A 通信协议框架 — Agent-to-Agent 通信协议的 TypeScript 实现

突破虚拟边界，让思考触达现实

完整文档: https://docs.llong.me

---

特性

• 能力发现 — AgentCard 自描述机制，让 Agent 在网络中被发现、被选择、被调用
• 双向流通信 — 基于 gRPC 的实时双向流，支持流式输出、进度反馈、中途取消
• Human in the Loop — 支持问答交互，人类作为特殊 Agent 参与协作
• 跨平台 — 浏览器与 Node.js 统一 API，Server 同时暴露 gRPC 和 WebSocket 端口
• 插件系统 — 丰富的 Hooks 扩展点，支持自定义插件开发；开箱即用，内置了 Tracing、Parasite、MCP 等生产级插件

---

安装

npm install @multi-agent/a2a
# or
bun add @multi-agent/a2a

---

快速开始

Server

import { createAgentServer } from '@multi-agent/a2a'

const server = createAgentServer({
  agentId: 'my-agent',
  name: 'My Agent',
  version: '1.0.0',
  address: 'a2a://0.0.0.0:50061',
  skills: [{
    name: 'greet',
    description: '问候用户',
    handler: async (params, ctx) => {
      ctx.stream.send({ type: 'progress', text: '处理中...' })
      ctx.stream.send({ type: 'done', text: '完成', data: { message: `Hello, ${params.name}!` } })
    },
  }],
})

await server.start()
console.log('Agent started on port 50061')

Client

import { createAgentClient } from '@multi-agent/a2a'

const client = createAgentClient({
  agentId: 'my-agent',
  address: 'a2a://localhost:50061',
})

// 获取 Agent 能力描述
const agentCard = await client.getAgentCard()
console.log('Skills:', agentCard.skills.map(s => s.name))

// 调用技能
const stream = await client.call('greet', { name: 'World' })

for await (const msg of stream) {
  console.log(`[${msg.type}] ${msg.text}`)
  if (msg.type === 'done') {
    console.log('Result:', msg.data)  // { message: 'Hello, World!' }
  }
}

---

核心概念

Message

所有通信使用统一的消息结构：

interface Message {
  type: string     // 消息类型: progress, question, answer, done, error, ...
  text: string     // 人类可读内容
  data?: any       // 结构化数据
  from?: AgentCard // 发送方身份（框架自动注入）
}

AgentCard

Agent 的身份卡片，描述其能力：

interface AgentCard {
  agentId: string
  name: string
  version: string
  description: string
  skills: SkillInfo[]
  endpoint: { host: string; port: number }
}

Bidirectional Stream

支持双向实时通信：

// Server 向 Client 提问
ctx.stream.send({ type: 'question', text: '请选择语言', data: { options: ['中文', 'English'] } })

for await (const msg of ctx.stream) {
  if (msg.type === 'answer') {
    console.log('用户选择:', msg.data.value)
    break
  }
}

---

浏览器支持

import { createAgentClient } from '@multi-agent/a2a/browser'

const client = createAgentClient({
  agentId: 'my-agent',
  address: 'a2a://localhost:50061',
})

const stream = await client.call('greet', { name: 'Browser' })

---

取消请求

支持中途取消请求：

const controller = new AbortController()
const stream = await client.call('longTask', params, { signal: controller.signal })

// 取消请求
controller.abort()

// Server 端通过 ctx.signal 感知取消
async function handler(params, ctx) {
  for (const item of items) {
    if (ctx.signal.aborted) return  // 检查取消信号
    await processItem(item)
  }
}

---

插件

通过 .use() 注册插件：

import { createAgentServer, createTracingPlugin } from '@multi-agent/a2a'

const server = createAgentServer(config)
  .use(createTracingPlugin({
    provider: {
      reportTrace: async (record) => {
        // 上报调用链追踪数据
      }
    }
  }))

await server.start()

内置插件：

Plugin	Description
createTracingPlugin	调用链追踪，记录 spanId/parentSpanId
createParasitePlugin	NAT 穿透，本地 Agent 寄生到云端
createMCPPlugin	MCP 协议集成

---

TLS 支持

生产环境启用 TLS：

const server = createAgentServer({
  address: 'a2as://0.0.0.0:50061',  // a2as:// 启用 TLS
  tls: {
    cert: '/path/to/cert.pem',
    key: '/path/to/key.pem',
  },
  // ...
})

---

相关包

Package	Description
@multi-agent/agent-kit	LLM 工具集成

---