技术原理核心

1. 协议架构设计

1.1 核心架构组件

A2A 协议采用 Client-Remote Agent 通信模型，这是理解整个协议的基础。在这个模型中：

• Client Agent：发起任务请求的一方，负责发现并调用其他 Agent 的能力
• Remote Agent：接收并处理任务的一方，暴露自己的能力给 Client

flowchart TB
    subgraph "A2A 生态系统"
        direction TB
        
        subgraph "发现层"
            AC[Agent Card<br/>/.well-known/agent.json]
        end
        
        subgraph "Client Agent"
            C1[任务管理器]
            C2[状态追踪器]
            C3[通信客户端]
        end
        
        subgraph "传输层"
            T1[HTTP/HTTPS]
            T2[Server-Sent Events]
            T3[JSON-RPC 2.0]
        end
        
        subgraph "Remote Agent"
            R1[任务处理器]
            R2[状态管理器]
            R3[通信服务端]
        end
        
        subgraph "输出层"
            AR[Artifacts<br/>结构化输出]
        end
    end
    
    AC -->|能力发现| C1
    C1 -->|创建任务| C3
    C3 -->|发送请求| T1
    T1 -->|JSON-RPC| T3
    T3 -->|路由| R3
    R3 -->|分发| R1
    R1 -->|生成| AR
    AR -->|返回| T2
    T2 -->|流式更新| C2
    
    style AC fill:#e1f5ff
    style AR fill:#ccffcc

1.2 传输层标准化

A2A 的一个关键设计决策是复用现有、被广泛理解的 Web 标准，而非发明新的传输机制：

这种设计带来了几个实际好处：

• 开发门槛低：开发者无需学习新的传输协议
• 工具生态丰富：现有的 HTTP 客户端、调试工具（如 curl、Postman）可直接使用
• 企业友好：标准 HTTP 端口（80/443），无需开放特殊端口

1.3 Agent Card：能力发现机制

Agent Card 是 A2A 的能力声明系统，类比于网站的 robots.txt 或 OpenAPI 规范。每个 A2A 兼容的 Agent 必须在 /.well-known/agent.json 端点提供一个 JSON 格式的能力描述文件。

Agent Card 结构：

{
  "name": "CustomerSupportAgent",
  "description": "Agent specialized in handling customer support tickets",
  "url": "https://support.example.com/a2a",
  "provider": {
    "name": "Example Corp",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "documentationUrl": "https://docs.example.com/a2a",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true
  },
  "authentication": {
    "type": "oauth2",
    "flows": ["client_credentials"]
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text", "file"],
  "skills": [
    {
      "id": "ticket-classification",
      "name": "Ticket Classification",
      "description": "Classify support tickets by priority and category",
      "tags": ["classification", "support"],
      "examples": ["Classify this ticket: ..."],
      "inputModes": ["text"],
      "outputModes": ["text", "structured"]
    }
  ]
}

关键字段解析：

发现流程：

sequenceDiagram
    participant C as Client Agent
    participant R as Remote Agent
    participant DNS as DNS/WLB
    
    C->>DNS: 解析 agent.example.com
    DNS-->>C: 返回 IP 地址
    C->>R: GET /.well-known/agent.json
    R-->>C: 返回 Agent Card
    C->>C: 解析 capabilities 和 skills
    C->>C: 选择合适的协议版本
    C->>R: POST / (A2A 请求)

2. 消息格式与数据模型

2.1 核心对象模型

A2A 协议定义了一套完整的数据模型，核心对象包括：

2.1.1 Task（任务）

Task 是 A2A 协议的核心概念，代表一个需要 Remote Agent 完成的工作单元。

interface Task {
  id: string;                    // 任务唯一标识符
  sessionId?: string;            // 会话 ID，用于关联相关任务
  status: TaskStatus;            // 当前状态
  artifacts?: Artifact[];        // 输出产物
  history?: Message[];           // 消息历史
  metadata?: Record<string, any>; // 元数据
}

2.1.2 TaskStatus（任务状态）

interface TaskStatus {
  state: TaskState;              // 状态枚举值
  message?: Message;             // 状态描述消息
  timestamp: string;             // ISO 8601 时间戳
}

enum TaskState {
  SUBMITTED = "submitted",       // 已提交，尚未开始
  WORKING = "working",           // 正在处理中
  INPUT_REQUIRED = "input-required", // 需要额外输入
  COMPLETED = "completed",       // 已完成
  CANCELED = "canceled",         // 已取消
  FAILED = "failed"              // 失败
}

状态转换图：

stateDiagram-v2
    [*] --> submitted: tasks/send
    submitted --> working: 开始处理
    working --> input-required: 需要更多信息
    input-required --> working: 提供输入
    working --> completed: 处理成功
    working --> failed: 处理失败
    submitted --> canceled: 取消请求
    working --> canceled: 取消请求
    input-required --> canceled: 取消请求
    completed --> [*]
    failed --> [*]
    canceled --> [*]

2.1.3 Message（消息）

Message 表示 Agent 之间交换的通信单元：

interface Message {
  role: Role;                    // 发送者角色
  parts: Part[];                 // 内容片段数组
  metadata?: Record<string, any>;
}

enum Role {
  USER = "user",                 // 最终用户
  AGENT = "agent"                // Agent 系统
}

2.1.4 Part（内容片段）

Part 是 Message 的原子组成单元，支持多种内容类型：

type Part = 
  | TextPart 
  | FilePart 
  | DataPart;

interface TextPart {
  type: "text";
  text: string;
}

interface FilePart {
  type: "file";
  file: {
    name?: string;
    mimeType?: string;
    bytes?: string;              // Base64 编码
    uri?: string;                // 外部 URL
  };
}

interface DataPart {
  type: "data";
  data: Record<string, any>;     // 结构化 JSON 数据
}

2.2 JSON-RPC 消息格式

A2A 使用 JSON-RPC 2.0 作为主要的 RPC 协议。以下是典型的请求/响应格式：

请求示例（tasks/send）：

{
  "jsonrpc": "2.0",
  "id": "task-001",
  "method": "tasks/send",
  "params": {
    "id": "task-unique-id",
    "sessionId": "session-123",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Analyze this sales data and provide insights"
        },
        {
          "type": "file",
          "file": {
            "name": "sales_q1.csv",
            "mimeType": "text/csv",
            "uri": "https://storage.example.com/sales_q1.csv"
          }
        }
      ]
    }
  }
}

响应示例（成功）：

{
  "jsonrpc": "2.0",
  "id": "task-001",
  "result": {
    "id": "task-unique-id",
    "sessionId": "session-123",
    "status": {
      "state": "completed",
      "timestamp": "2026-04-07T10:30:00Z"
    },
    "artifacts": [
      {
        "name": "sales-analysis",
        "parts": [
          {
            "type": "text",
            "text": "Q1 sales increased by 23% compared to Q4..."
          },
          {
            "type": "data",
            "data": {
              "growth_rate": 0.23,
              "top_product": "Product A",
              "revenue": 1500000
            }
          }
        ]
      }
    ]
  }
}

2.3 流式传输与 SSE

对于长时间运行的任务，A2A 支持通过 Server-Sent Events (SSE) 进行实时状态更新。

SSE 事件类型：

SSE 示例：

event: task-status
data: {"state": "working", "message": {"role": "agent", "parts": [{"type": "text", "text": "Processing data..."}]}, "timestamp": "2026-04-07T10:30:05Z"}

event: task-artifact
data: {"artifact": {"name": "partial-result", "parts": [{"type": "text", "text": "50% complete..."}], "append": true}, "lastChunk": false}

event: task-status
data: {"state": "completed", "timestamp": "2026-04-07T10:35:00Z"}

3. 通信流程与状态机

3.1 标准任务执行流程

sequenceDiagram
    participant C as Client Agent
    participant R as Remote Agent
    participant Ext as 外部系统
    
    Note over C,R: Phase 1: 发现
    C->>R: GET /.well-known/agent.json
    R-->>C: Agent Card (capabilities, skills)
    
    Note over C,R: Phase 2: 任务创建
    C->>R: POST / (tasks/send)
    R-->>C: Task (state: submitted)
    
    Note over C,R: Phase 3: 处理
    R->>R: 状态转换: submitted → working
    
    alt 需要外部数据
        R->>Ext: 查询/调用
        Ext-->>R: 返回数据
    end
    
    alt 需要用户输入
        R->>C: 状态: input-required
        C-->>R: 提供输入
        R->>R: 状态: working
    end
    
    Note over C,R: Phase 4: 完成
    R->>R: 生成 Artifacts
    R-->>C: Task (state: completed, artifacts: [...])

3.2 流式任务执行（SSE）

对于需要实时进度反馈的任务，使用 tasks/sendSubscribe 方法：

sequenceDiagram
    participant C as Client Agent
    participant R as Remote Agent
    
    C->>R: POST / (tasks/sendSubscribe)
    R-->>C: SSE Stream (Content-Type: text/event-stream)
    
    loop 处理过程中
        R-->>C: event: task-status (working)
        R-->>C: event: task-artifact (部分结果)
    end
    
    R-->>C: event: task-status (completed)
    R-->>C: event: task-artifact (最终结果, lastChunk: true)

3.3 Push Notification 机制

对于可能长时间运行的任务，Client 可以配置 Push Notification，让 Remote Agent 在状态变化时主动回调：

// 创建 Push Notification 配置
interface PushNotificationConfig {
  url: string;                   // Webhook URL
  authentication?: AuthenticationInfo; // 认证信息
  metadata?: Record<string, any>;
}

// Remote Agent 回调 payload
interface PushNotificationPayload {
  taskId: string;
  state: TaskState;
  timestamp: string;
  message?: Message;
}

流程：

1. Client 调用 tasks/pushNotification/set 配置 Webhook
2. Remote Agent 在任务状态变化时向指定 URL 发送 POST 请求
3. Client 接收通知后可选择拉取完整任务详情

4. 安全与认证机制

4.1 认证方案

A2A 支持多种认证机制，定义在 Agent Card 的 authentication 字段：

4.2 OAuth 2.0 流程示例

sequenceDiagram
    participant C as Client Agent
    participant Auth as OAuth Provider
    participant R as Remote Agent
    
    C->>Auth: 请求访问令牌 (client_credentials)
    Auth-->>C: 返回 access_token
    
    C->>R: GET /.well-known/agent.json
    R-->>C: Agent Card
    
    C->>R: POST / (tasks/send)<br/>Authorization: Bearer <token>
    R->>R: 验证令牌
    R-->>C: Task Response

4.3 任务级授权

除了连接级认证，A2A 还支持任务级授权（In-Task Authorization），允许在任务执行过程中动态验证权限：

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "task-001",
    "message": {...},
    "metadata": {
      "authorization": {
        "type": "bearer",
        "token": "task-specific-jwt"
      }
    }
  }
}

这种机制适用于：

• 需要细粒度访问控制的场景
• 任务涉及敏感数据
• 多租户环境下的权限隔离

4.4 安全最佳实践

根据 A2A 官方安全指南：

1. 传输层加密：生产环境必须使用 HTTPS
2. 令牌生命周期：Access Token 应设置合理过期时间（建议 15 分钟）
3. 范围限定：OAuth Token 应限定最小必要权限范围
4. 输入验证：严格验证所有输入数据，防止注入攻击
5. 速率限制：实现基于 IP/Token 的速率限制，防止滥用

flowchart TD
    A[Client Request] --> B{HTTPS?}
    B -->|No| C[拒绝连接]
    B -->|Yes| D{认证有效?}
    D -->|No| E[返回 401]
    D -->|Yes| F{速率限制?}
    F -->|超限| G[返回 429]
    F -->|正常| H{权限足够?}
    H -->|不足| I[返回 403]
    H -->|足够| J[处理请求]
    
    style C fill:#ffcccc
    style E fill:#ffcccc
    style G fill:#ffcccc
    style I fill:#ffcccc
    style J fill:#ccffcc

参考资料

1. A2A Protocol Specification v1.0.0 - 官方规范
2. JSON-RPC 2.0 Specification - 底层 RPC 协议
3. Server-Sent Events (SSE) Spec - W3C 标准
4. OAuth 2.0 Framework - RFC 6749
5. GitHub - a2aproject/A2A Security Guide