核心概念

AgentCard

AgentCard 是 Agent 的身份名片，描述 Agent 的元信息和能力。

interface AgentCard {
  agentId: string         // 唯一标识
  name: string            // 显示名称
  version: string         // 版本号
  description: string     // 能力描述
  skills: SkillInfo[]     // 技能列表
  defaultSkill: string    // 默认技能
  endpoint: Endpoint      // 网络端点
}

核心用途：

• 服务发现 - 其他 Agent 通过 AgentCard 了解该 Agent 能做什么
• LLM 理解 - 生成提示词让 LLM 理解 Agent 能力
• 动态调用 - 根据 AgentCard 中的 skills 动态选择调用

获取方式：

// Client 端获取
const card = await client.getAgentCard()

// Handler 中获取
const card = ctx.getAgentCard()

// 从消息中获取发送者信息
const senderCard = msg.from

Skill

Skill 是 Agent 对外暴露的能力，由 Handler 函数实现。

{
  name: 'translate',           // 技能名
  description: '翻译文本',      // 描述（供 LLM 理解）
  handler: translateHandler,   // 处理函数
  inputSchema: { ... },        // 输入参数 JSON Schema
}

Client 通过 client.call(skillName, params) 调用技能。

Stream

A2A 的所有通信都是 双向流：

流结束机制：Server Handler 执行完毕后，框架自动结束流，Client 的 for await 循环自动退出。

Message

流中传递的消息类型（可根据业务自行扩展）：

类型	方向	用途
progress	Server → Client	进度/流式输出
question	Server → Client	向用户提问
answer	Client → Server	回答问题
done	Server → Client	任务完成
error	Server → Client	发生错误

可扩展

消息类型是开放的，你可以定义任意 type 来满足业务需求，如 todolist、code、file 等。

Context

Handler 的第二个参数，提供运行时能力：

属性/方法	用途
ctx.stream	双向流，用于发送/接收消息
ctx.signal	AbortSignal，用于响应取消
ctx.getMetadata(key)	读取调用方传递的元数据

地址格式

A2A 使用统一地址格式：

a2a://host:port

环境	传输协议
Node.js	gRPC (HTTP/2)
浏览器	WebSocket

Client 根据运行环境自动选择协议，开发者无需关心。