Phase 81 — A2A协议引擎设计

版本: v4.1.0 创建日期: 2026-03-10 状态: ✅ 已实现 (v4.1.0)

---

一、模块概述

Phase 81 实现Google A2A (Agent-to-Agent) 协议标准引擎，支持Agent Card发现、Task生命周期管理、实时订阅和能力协商，构建开放的Agent互操作网络。

1.1 核心目标

1. A2A协议: 完整实现Google A2A标准，Agent间标准化通信
2. Agent Card: 基于JSON-LD的Agent能力描述和服务发现
3. Task生命周期: submitted → working → input-required → completed → failed 全流程管理
4. 实时订阅: SSE/WebSocket推送Task状态变更
5. 能力协商: Agent间自动匹配能力和协商合作方式

1.2 技术架构

┌──────────────────────────────────────────────────┐
│              A2A Protocol Engine                  │
│                                                  │
│  ┌───────────────────┐  ┌──────────────────────┐ │
│  │ AgentCardRegistry │  │ TaskLifecycleManager │ │
│  │ JSON-LD发现       │  │ 状态机+事件驱动      │ │
│  │ 能力索引+匹配     │  │ 超时+重试+回滚       │ │
│  └───────────────────┘  └──────────────────────┘ │
│  ┌───────────────────┐  ┌──────────────────────┐ │
│  │ SubscriptionMgr   │  │ CapabilityNegotiator │ │
│  │ SSE/WebSocket推送 │  │ 能力匹配+协商        │ │
│  │ 事件过滤+缓冲     │  │ 版本兼容+降级        │ │
│  └───────────────────┘  └──────────────────────┘ │
│  ┌──────────────────────────────────────────────┐ │
│  │           A2A IPC Layer (8 handlers)         │ │
│  └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

---

二、核心模块设计

2.1 A2AProtocolEngine (ai-engine/a2a/a2a-protocol-engine.js)

A2A协议引擎主模块，管理Agent Card、Task和订阅。

常量:

• TASK_STATUS: SUBMITTED, WORKING, INPUT_REQUIRED, COMPLETED, FAILED, CANCELED
• CARD_STATUS: ACTIVE, INACTIVE, EXPIRED
• SUBSCRIPTION_TYPE: TASK_UPDATE, AGENT_STATUS, CAPABILITY_CHANGE

核心方法:

• initialize(deps) — 初始化引擎，加载本地Agent Card
• discoverAgents(filter) — 发现可用Agent（按能力、区域、状态过滤）
• sendTask({ targetAgentId, task, timeout }) — 向目标Agent发送Task
• getTaskStatus(taskId) — 获取Task当前状态和中间结果
• subscribeUpdates({ agentId, taskId, eventTypes }) — 订阅状态变更推送
• registerCard(card) — 注册本地Agent Card到网络
• updateCard(cardId, updates) — 更新Agent Card信息
• listPeers(filter) — 列出已发现的Peer Agent
• negotiateCapability({ agentId, requiredCapabilities }) — 与Agent协商能力匹配
• _handleTaskStateTransition(taskId, newStatus, data) — 内部状态机转换
• _validateAgentCard(card) — 验证Card格式符合A2A规范
• destroy() — 销毁引擎，清理订阅

2.2 A2AIPC (ai-engine/a2a/a2a-ipc.js)

IPC通道注册和参数校验。

---

三、数据库设计

-- Phase 81: A2A Protocol
CREATE TABLE IF NOT EXISTS a2a_agent_cards (
  id TEXT PRIMARY KEY,
  agent_name TEXT NOT NULL,
  description TEXT,
  capabilities TEXT,          -- JSON array of capability descriptors
  endpoint_url TEXT,
  auth_type TEXT DEFAULT 'none',
  status TEXT DEFAULT 'active',
  version TEXT DEFAULT '1.0',
  metadata TEXT,              -- JSON-LD metadata
  last_seen INTEGER,
  created_at INTEGER
);

CREATE TABLE IF NOT EXISTS a2a_tasks (
  id TEXT PRIMARY KEY,
  source_agent_id TEXT NOT NULL,
  target_agent_id TEXT NOT NULL,
  status TEXT DEFAULT 'submitted',
  task_type TEXT,
  input_data TEXT,            -- JSON task input
  output_data TEXT,           -- JSON task output
  error_message TEXT,
  timeout_ms INTEGER DEFAULT 30000,
  retries INTEGER DEFAULT 0,
  created_at INTEGER,
  updated_at INTEGER,
  completed_at INTEGER
);

CREATE TABLE IF NOT EXISTS a2a_subscriptions (
  id TEXT PRIMARY KEY,
  subscriber_id TEXT NOT NULL,
  target_agent_id TEXT,
  task_id TEXT,
  event_types TEXT,           -- JSON array
  active INTEGER DEFAULT 1,
  created_at INTEGER
);

---

四、IPC接口设计

Phase 81 — A2AIPC (8 handlers)

通道	说明
a2a:discover-agents	发现可用Agent
a2a:send-task	发送Task
a2a:get-task-status	获取Task状态
a2a:subscribe-updates	订阅状态更新
a2a:register-card	注册Agent Card
a2a:update-card	更新Agent Card
a2a:list-peers	列出Peer Agent
a2a:negotiate-capability	协商能力匹配

---

五、前端集成

Pinia Stores

• a2aProtocol.ts — Agent Card列表、Task管理、订阅状态、Peer列表

Vue Pages

• A2AProtocolPage.vue — Agent发现/Task管理/能力协商/订阅管理

Routes

• /a2a-protocol — A2A协议管理

---

六、配置选项

a2aProtocol: {
  enabled: false,
  discoveryIntervalMs: 30000,
  taskTimeoutMs: 60000,
  maxRetries: 3,
  subscriptionBufferSize: 100,
  cardExpirationMs: 86400000,
},

---

七、测试覆盖

测试文件: src/main/ai-engine/a2a/__tests__/a2a-protocol-engine.test.js测试数量: 24 tests

分类	数量	说明
初始化	3	引擎初始化、Card加载、依赖注入
Agent发现	4	按能力过滤、按状态过滤、空结果、超时处理
Task生命周期	6	状态转换链、超时重试、失败回滚、取消操作
订阅管理	4	创建订阅、事件过滤、取消订阅、缓冲机制
Agent Card	4	注册验证、更新、过期清理、JSON-LD格式校验
能力协商	3	匹配成功、部分匹配降级、不兼容拒绝

---

八、Context Engineering

• step 5.1: setA2AProtocolContext() — 注入A2A协议引擎上下文