A2A 1.0协议详解与智能体通信开发实践

1. A2A 1.0协议概述与背景

A2A（Agent-to-Agent）协议1.0版本是2026年3月发布的全新通信标准，专为智能体间交互设计。与0.3版本相比，1.0版本进行了架构级的重构，导致两个版本完全不兼容。这种不兼容性主要体现在以下几个关键方面：

• 协议绑定方式从单一接口改为多接口支持（JSON-RPC、GRPC、HTTP+JSON）
• 消息角色命名从简单字符串改为规范化前缀（如"user"→"ROLE_USER"）
• 消息部分结构简化（移除kind字段）
• 方法命名规范化（如"message/send"→"SendMessage"）

重要提示：由于1.0版本发布较晚，目前多数AI训练数据仍基于0.3版本，这导致自动生成的代码示例经常出现版本混淆问题。在实际开发中需要特别注意版本标识。

2. Agent Card 1.0详解

2.1 核心字段解析

Agent Card是A2A协议的核心元数据描述文件，1.0版本对其结构进行了重大调整。以下是一个完整的地理空间路线规划Agent示例：

json复制{
  "name": "GeoSpatial Route Planner Agent",
  "description": "提供高级路线规划、交通分析和自定义地图生成服务",
  "supportedInterfaces": [
    {
      "url": "https://georoute-agent.example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  }
}

关键变更点：

1. supportedInterfaces取代了原来的单一接口声明，支持多种协议绑定
2. 新增extendedAgentCard能力标识，用于控制是否支持认证后获取扩展信息
3. 安全方案声明改为securitySchemes映射结构

2.2 字段规范说明

AgentCard主结构字段：

特别注意事项：

• protocolVersion必须明确指定"1.0"
• 接口URL必须使用HTTPS（本地测试除外）
• 第一个supportedInterfaces条目将作为默认接口

3. 协议实现实战

3.1 开发环境搭建

推荐使用以下技术栈进行A2A 1.0 Agent开发：

bash复制# 初始化项目
npm init -y
npm install @a2a-relay/server express --save
npm install @types/node @types/express tsx typescript --save-dev

关键依赖说明：

• @a2a-relay/server：A2A官方中间件库
• tsx：TypeScript即时执行环境
• express：Web服务框架

3.2 基础Agent实现

以下是支持天气查询和待办事项管理的非流式Agent核心代码：

typescript复制// 天气数据库
const weatherDB = {
  '北京': { temp: '15°C', condition: '晴' },
  '上海': { temp: '18°C', condition: '多云' }
};

// 消息处理函数
function processMessage(text: string) {
  if (text.includes('天气')) {
    const city = Object.keys(weatherDB).find(c => text.includes(c));
    return `${city}天气：${weatherDB[city].temp} ${weatherDB[city].condition}`;
  }
  return `未知指令：${text}`;
}

// A2A端点配置
app.post('/a2a/v1', (req, res) => {
  const { method, params } = req.body;
  
  if (method === 'SendMessage') {
    const response = processMessage(params.message.parts[0].text);
    res.json({
      result: {
        messages: [{
          role: 'ROLE_AGENT',
          parts: [{ text: response }]
        }]
      }
    });
  }
});

3.3 流式Agent实现

流式Agent需要实现SendStreamingMessage方法并保持长连接：

typescript复制// 流式生成器
async function* generateStream(text: string) {
  const words = text.split(' ');
  for (const word of words) {
    await new Promise(r => setTimeout(r, 100));
    yield { content: word + ' ' };
  }
}

// 流式端点
app.post('/a2a/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  
  for await (const chunk of generateStream(req.body.text)) {
    res.write(`data: ${JSON.stringify(chunk)}\n\n`);
  }
  
  res.end();
});

4. 迁移与兼容方案

4.1 版本差异对照表

4.2 渐进式迁移策略

1. 双模式运行：同时实现0.3和1.0接口

   typescript复制// 兼容0.3的端点
   app.post('/v0.3/message', handleLegacyMessage);
   
   // 1.0端点
   app.post('/v1.0/SendMessage', handleV1Message);
   

2. 客户端引导：

   • 通过HTTP头A2A-Version: 1.0声明版本
   • 在错误响应中包含迁移提示

3. 监控过渡：

   bash复制# 监控版本使用情况
   a2a-monitor --version-stats
   

实践经验：建议设置6个月的迁移窗口期，期间维护双版本支持，之后逐步淘汰0.3版本。

5. 调试与问题排查

5.1 常见错误代码

5.2 诊断工具推荐

1. A2A Inspector：

   bash复制npx a2a-inspector verify-card --url https://agent.example.com/.well-known/agent-card.json
   

2. Wireshark插件：

   • 安装A2A协议解析插件
   • 过滤a2a协议流量

3. 测试套件：

   javascript复制const test = new A2AValidator('1.0');
   test.validateAgentCard(cardJson);
   

6. 性能优化建议

6.1 连接管理

typescript复制// 保持HTTP长连接
app.use((req, res, next) => {
  res.set('Connection', 'keep-alive');
  next();
});

6.2 缓存策略

1. Agent Card缓存：

   • 客户端应缓存至少5分钟
   • 使用ETag进行条件请求

2. 消息缓存：

   typescript复制const messageCache = new LRU({
     max: 1000,
     ttl: 60 * 1000
   });
   

6.3 负载测试

使用a2a-benchmark工具进行压力测试：

bash复制a2a-benchmark --url https://agent.example.com/a2a/v1 --rps 1000 --duration 60s

7. 安全实践

7.1 认证配置示例

json复制{
  "securitySchemes": {
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://example.com/oauth/authorize",
          "tokenUrl": "https://example.com/oauth/token"
        }
      }
    }
  }
}

7.2 必须的安全措施

1. 所有生产环境接口必须使用HTTPS
2. 实现请求签名验证
3. 定期轮换签名密钥
4. 限制接口访问频率

8. 扩展与自定义

8.1 扩展Agent Card

json复制{
  "capabilities": {
    "extendedAgentCard": true
  },
  "x-custom-info": {
    "supportEmail": "contact@example.com"
  }
}

8.2 自定义技能

typescript复制{
  "skills": [{
    "id": "custom-weather",
    "name": "增强天气查询",
    "inputModes": ["application/json"],
    "outputModes": ["application/geo+json"]
  }]
}

9. 客户端实现指南

9.1 发现流程

1. 获取Agent Card：

   bash复制curl https://agent.example.com/.well-known/agent-card.json
   

2. 选择协议绑定：

   javascript复制const interface = card.supportedInterfaces.find(i => 
     i.protocolBinding === 'JSONRPC'
   );
   

9.2 消息交换示例

javascript复制const response = await a2aClient.sendMessage({
  role: 'ROLE_USER',
  parts: [{ text: '北京天气' }]
}, {
  protocol: '1.0',
  endpoint: interface.url
});

10. 未来演进

虽然1.0版本刚刚发布，但协议委员会已公布演进路线：

1. 2026Q4：增加二进制协议绑定支持
2. 2027Q2：内置服务发现机制
3. 2028：计划发布2.0版本

建议开发者通过GitHub参与协议规范的讨论和贡献。