A2A Inspector：深入探讨智能体间通信调试

A2A（智能体间）协议代表了 AI 智能体以结构化方式相互通信的标准化方法。随着 AI 系统变得更加复杂和互联，拥有强大的工具来调试、检查和验证这些通信变得至关重要。本文探讨了 A2A Inspector的架构和实现，这是一个网络调试工具，旨在帮助开发者理解和故障排除 A2A 智能体交互。

什么是 A2A Inspector？

A2A Inspector是一个综合性的网络工具，允许开发者：

• 连接到 A2A 智能体 通过指定其基础 URL
• 检查智能体卡片 以了解功能和规格
• 验证协议合规性 对照 A2A 规范
• 监控实时通信 通过交互式聊天界面
• 调试 JSON-RPC 消息 使用详细的控制台视图

该工具弥合了复杂智能体通信与开发者理解之间的差距，为以前是智能体间交互黑盒的内容提供了可见性。

架构概述

Inspector遵循现代三层架构：

前端层（TypeScript + Socket.IO）

• 技术栈：TypeScript、Socket.IO 客户端、esbuild
• 职责：用户界面、实时通信处理、消息显示
• 关键特性：响应式聊天界面、可折叠调试控制台、JSON 模态查看器

后端层（Python + FastAPI）

• 技术栈：FastAPI、Socket.IO、A2A SDK、Pydantic
• 职责：智能体通信、消息验证、WebSocket 管理
• 关键特性：实时消息代理、协议验证、会话管理

目标层（A2A 智能体）

• 协议：基于 HTTP/WebSocket 的 JSON-RPC 2.0
• 功能：消息处理、任务执行、工件生成
• 标准：符合 Google A2A 规范

实现深入探讨

1. 智能体发现和连接

连接过程从智能体卡片发现机制开始：

# 来自 backend/app.py
async with httpx.AsyncClient(timeout=30.0) as client:
    card_resolver = A2ACardResolver(client, agent_url)
    card = await card_resolver.get_agent_card()

系统从众所周知的端点 /.well-known/agent-card 获取智能体卡片，该端点提供关于智能体功能、支持的输入/输出模式和可用技能的基本元数据。

2. 协议验证引擎

Inspector的关键特性之一是其综合验证系统。validators.py 模块实现了严格的检查：

智能体卡片验证：

• 必需字段存在（name、description、url、version 等）
• URL 格式验证（具有适当协议的绝对 URL）
• 数据类型合规性（数组、对象、字符串）
• 技能数组验证

消息验证：

• JSON-RPC 2.0 合规性
• 消息类型验证（task、status-update、artifact-update、message）
• 基于消息类型的必需字段存在
• 智能体响应的角色验证

def validate_message(data: dict[str, Any]) -> list[str]:
    """根据消息类型验证来自智能体的传入消息。"""
    if 'kind' not in data:
        return ["来自智能体的响应缺少必需的 'kind' 字段。"]
    
    kind = data.get('kind')
    validators = {
        'task': _validate_task,
        'status-update': _validate_status_update,
        'artifact-update': _validate_artifact_update,
        'message': _validate_message,
    }
    
    validator = validators.get(str(kind))
    if validator:
        return validator(data)
    
    return [f"收到未知消息类型：'{kind}'。"]

3. 实时通信层

Inspector使用 Socket.IO 进行双向通信，实现实时消息交换和调试：

连接管理：

# 客户端会话的全局状态管理
clients: dict[str, tuple[httpx.AsyncClient, A2AClient, AgentCard]] = {}

@sio.on('initialize_client')
async def handle_initialize_client(sid: str, data: dict[str, Any]) -> None:
    """为会话初始化 A2A 客户端连接。"""
    # 存储客户端连接与会话 ID 以供后续使用

消息代理： 后端充当智能代理，将用户消息转发给 A2A 智能体，同时提供全面的日志记录和验证：

@sio.on('send_message')
async def handle_send_message(sid: str, json_data: dict[str, Any]) -> None:
    """处理带有验证和调试的消息发送。"""
    # 将消息转发给 A2A 智能体
    # 根据协议验证响应
    # 发出调试日志和格式化响应

4. 前端状态管理

TypeScript 前端同时管理多个关注点：

Socket 事件处理：

socket.on('agent_response', (event: AgentResponseEvent) => {
    const messageId = `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
    messageJsonStore[messageId] = event;
    
    const validationErrors = event.validation_errors || [];
    
    if (event.error) {
        appendMessage('agent error', `[error] 错误：${event.error}`, messageId, false, validationErrors);
        return;
    }
    
    // 处理不同的消息类型：task、status-update、artifact-update、message
});

调试控制台集成： Inspector提供了一个可调整大小的调试控制台，显示原始 JSON-RPC 通信，使开发者能够理解确切的协议交换。

通信流程和序列

以下序列图说明了完整的通信流程：

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端 (TypeScript)
    participant Backend as 后端 (FastAPI)
    participant A2AAgent as A2A 智能体服务器
    
    User->>Frontend: 输入智能体 URL 并点击连接
    Frontend->>Backend: POST /agent-card（带 URL 和 socket ID）
    Backend->>A2AAgent: HTTP GET /.well-known/agent-card
    A2AAgent-->>Backend: 智能体卡片 JSON
    Backend->>Backend: 验证智能体卡片
    Backend-->>Frontend: 智能体卡片 + 验证结果
    Frontend->>Frontend: 显示智能体卡片
    
    Frontend->>Backend: Socket.IO: initialize_client
    Backend->>A2AAgent: 初始化 A2A 客户端连接
    Backend-->>Frontend: Socket.IO: client_initialized
    
    User->>Frontend: 输入消息并发送
    Frontend->>Backend: Socket.IO: send_message
    Backend->>A2AAgent: JSON-RPC 2.0: sendMessage
    A2AAgent-->>Backend: JSON-RPC 响应（任务/消息等）
    Backend->>Backend: 验证响应
    Backend-->>Frontend: Socket.IO: agent_response + debug_log
    Frontend->>Frontend: 显示消息和验证结果
    
    Note over Backend,A2AAgent: 实时双向通信
    Note over Frontend,Backend: WebSocket 实时更新

关键技术特性

1. 会话管理

每个客户端连接通过 Socket.IO 会话 ID 管理，允许多个并发调试会话而不相互干扰。

2. 全面日志记录

每个 JSON-RPC 交互都记录时间戳和验证结果，提供智能体通信的完整可追溯性。

3. 错误处理和弹性

系统优雅地处理网络错误、协议违规和智能体故障，为开发者提供有意义的反馈。

4. 实时验证

所有智能体响应都根据 A2A 规范进行实时验证，立即突出显示协议合规性问题。

如何使用 A2A Inspector

设置和安装

1. 克隆并安装依赖项：

git clone https://github.com/google-a2a/a2a-inspector.git
cd a2a-inspector
uv sync
cd frontend && npm install && cd ..

2. 启动开发环境：

# 终端 1：前端构建过程
cd frontend && npm run build -- --watch

# 终端 2：后端服务器
cd backend && uv run app.py

3. 访问Inspector： 在网络浏览器中导航到 http://127.0.0.1:5001。

调试工作流程

1. 连接到智能体：输入您的 A2A 智能体的基础 URL（例如，http://localhost:5555）

2. 检查智能体卡片：查看自动获取的智能体功能并检查验证错误

3. 开始调试：使用聊天界面发送消息并观察智能体响应

4. 监控协议合规性：检查每次消息交换的验证结果

5. 分析原始通信：使用调试控制台检查 JSON-RPC 消息

高级功能

调试控制台

可调整大小的调试控制台提供实时访问：

• 原始 JSON-RPC 请求和响应
• 验证错误详细信息
• 网络时序信息
• 消息关联 ID

验证引擎

内置验证引擎检查：

• 智能体卡片结构和必需字段
• 消息格式合规性
• JSON-RPC 2.0 协议遵循
• A2A 特定消息类型和字段

多智能体支持

Inspector可以维护与多个智能体的同时连接，每个都在单独的浏览器标签或会话中。

技术考虑和最佳实践

安全性

• 当前实现使用通配符 CORS 以简化开发
• 生产部署应将 CORS 限制为特定域
• 考虑为敏感智能体交互实现身份验证

可扩展性

• 全局状态管理适用于开发，但在生产中应替换为 Redis 或类似工具
• WebSocket 连接应在高流量场景中进行负载平衡

可扩展性

• 验证引擎是模块化的，可以扩展以满足自定义协议要求
• 前端组件设计用于轻松定制和品牌化

结论

A2A Inspector代表了使智能体间通信透明和可调试的重要进步。通过提供实时验证、全面日志记录和直观界面，它使开发者能够构建更强大和合规的 A2A 系统。

该工具的架构展示了实时网络应用程序的最佳实践，将现代前端技术与强大的后端验证相结合。随着 A2A 协议的发展，该Inspector将继续作为开发者处理智能体间通信的重要工具。

无论您是构建第一个 A2A 智能体还是调试复杂的多智能体交互，A2A Inspector都提供了确保可靠和符合规范的智能体通信所需的可见性和验证工具。

资源

• 项目仓库