A2A 协议详解：Agent Card 的设计与实现

CarlowZJ

于 2025-06-17 00:04:02 发布

阅读量342

点赞数 17

文章标签：算法大数据网络 A2A

本文链接：https://blog.youkuaiyun.com/csdn122345/article/details/148701926

版权

摘要

Agent Card 是 Agent2Agent (A2A) 协议中实现智能体发现与互操作性的核心组件。本文将深入剖析 Agent Card 的设计理念、关键字段及其在智能体生态系统中的作用。我们将通过详细的 JSON Schema 解析和 Python SDK 示例，帮助您理解如何精确地定义和发布智能体能力，为构建可发现、可协作的 AI 智能体奠定基础。

1. 引言：智能体的“名片”

在 A2A 协议中，智能体之间要进行通信和协作，首先需要了解彼此的存在和能力。就像现实世界中人们需要名片来介绍自己一样，A2A 智能体也拥有自己的“名片”—— Agent Card。Agent Card 是智能体自我描述的标准 JSON 对象，它包含了智能体的基本信息、所提供的技能以及通信相关的配置，是实现智能体“即插即用”的关键。

理解 Agent Card 的设计和实现，对于构建高质量、易于集成的 A2A 智能体至关重要。它不仅定义了智能体的功能边界，也为其他智能体或客户端发现和调用其服务提供了必要的信息。

2. Agent Card 核心结构与字段解析

Agent Card 是一个 JSON 对象，其结构由 A2A 协议的 JSON Schema 严格定义。以下是 Agent Card 的主要字段及其含义：

{
  "name": "string",
  "version": "string",
  "description": "string",
  "url": "string",
  "capabilities": { /* AgentCapabilities 对象 */ },
  "skills": [ /* AgentSkill 数组 */ ],
  "defaultInputModes": ["string"], // 默认支持的输入媒体类型
  "defaultOutputModes": ["string"], // 默认支持的输出媒体类型
  "provider": { /* AgentProvider 对象 */ },
  "security": [ /* 安全要求 */ ],
  "securitySchemes": { /* 安全方案定义 */ },
  "documentationUrl": "string", // 文档 URL
  "iconUrl": "string", // 图标 URL
  "supportsAuthenticatedExtendedCard": "boolean" // 是否支持认证扩展卡片
}

2.1 基础信息字段

name (字符串，必填)：智能体的可读名称，必须是唯一的，用于智能体发现。
version (字符串，必填)：智能体的版本号，格式由提供者自行决定。
description (字符串，必填)：智能体功能的详细描述，帮助用户和其他智能体理解其作用。
url (字符串，必填)：智能体服务的端点 URL，即其他智能体发送请求的地址。
documentationUrl (字符串，可选)：智能体相关文档的 URL。
iconUrl (字符串，可选)：智能体图标的 URL。

2.2 `capabilities` (AgentCapabilities) 智能体能力

capabilities 字段是一个 AgentCapabilities 对象，它定义了智能体支持的可选高级能力，而不是具体的业务技能。这包括：

streaming (布尔值)：如果为 true，表示智能体支持 SSE (Server-Sent Events) 流式通信。
pushNotifications (布尔值)：如果为 true，表示智能体可以主动向客户端推送通知。
stateTransitionHistory (布尔值)：如果为 true，表示智能体暴露任务状态变更历史记录。
extensions (AgentExtension 数组)：智能体支持的扩展列表。

示例：

"capabilities": {
  "streaming": true,
  "pushNotifications": false,
  "stateTransitionHistory": true,
  "extensions": [
    {
      "uri": "https://example.com/a2a/extensions/my-custom-ext",
      "description": "支持自定义数据压缩格式"
    }
  ]
}

2.3 `skills` (AgentSkill[]) 智能体技能

skills 字段是 Agent Card 中最核心的部分，它是一个 AgentSkill 对象的数组，每个 AgentSkill 定义了智能体提供的一项具体功能或操作。每个 AgentSkill 包含：

name (字符串，必填)：技能的唯一名称（在当前智能体范围内）。
description (字符串，必填)：技能的详细描述，说明其用途和功能。
input (Schema 对象，可选)：定义技能输入数据的 JSON Schema。这对于客户端理解如何构建请求体至关重要。
output (Schema 对象，可选)：定义技能输出数据的 JSON Schema。这帮助客户端解析响应。
parameters (Parameter[] 数组，可选)：描述技能特有的参数，可能与 input 结合使用。
security (SecurityRequirement[] 数组，可选)：调用此技能所需的安全要求。
inputModes (字符串数组，可选)：此技能支持的输入媒体类型，会覆盖 defaultInputModes。
outputModes (字符串数组，可选)：此技能支持的输出媒体类型，会覆盖 defaultOutputModes。

Agent Skill 示例：

"skills": [
  {
    "name": "summarizeText",
    "description": "总结提供的文本内容",
    "input": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "需要总结的文本"
        },
        "maxLength": {
          "type": "integer",
          "description": "最大总结长度",
          "default": 200
        }
      },
      "required": ["text"]
    },
    "output": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string",
          "description": "总结后的文本"
        }
      }
    },
    "inputModes": ["text/plain", "application/json"]
  }
]

2.4 `defaultInputModes` 和 `defaultOutputModes`

这两个字段是字符串数组，分别定义了智能体默认支持的输入和输出媒体类型（MIME 类型），例如 "text/plain", "application/json", "image/png" 等。这些是智能体在不指定特定技能模式时的通用约定。

2.5 `security` 和 `securitySchemes` 安全配置

securitySchemes (SecurityScheme 对象映射，可选)：定义了智能体支持的各种安全方案，如 API Key 认证、OAuth2 等。每个方案都有一个唯一的名称和具体的配置。
security (SecurityRequirement[] 数组，可选)：列出了与智能体通信所需的全局安全要求。每个要求引用 securitySchemes 中定义的方案。

安全配置示例：

"securitySchemes": {
  "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "用于认证的 API Key"
  }
},
"security": [
  {
    "ApiKeyAuth": []
  }
]

3. Agent Card 的作用与生命周期

3.1 智能体发现流程

Agent Card 在 A2A 协议中扮演着“注册表”的角色。当一个智能体启动时，它会向 A2A 注册中心发布自己的 Agent Card。其他智能体或客户端可以通过查询注册中心来发现可用的智能体，并获取它们的 Agent Card。

智能体发现流程图：

3.2 Agent Card 的更新与维护

当智能体的能力发生变化（例如，新增技能、修改端点、版本升级）时，需要及时更新其 Agent Card。这确保了整个 A2A 生态系统中的信息一致性。

4. 使用 A2A Python SDK 管理 Agent Card

A2A Python SDK 封装了 Agent Card 的构建和注册过程，使得开发者无需直接手动创建复杂的 JSON 对象。

4.1 定义智能体并自动生成 Agent Card

当您使用 a2a.Agent 类初始化一个智能体时，SDK 会根据您提供的参数（name, version, capabilities 等）自动构建内部的 Agent Card 表示。

# agent_card_example.py

import asyncio
from a2a import Agent
import logging

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

async def main():
    # 创建一个具有多项技能的智能体
    # SDK 会根据这些参数在内部构建 Agent Card
    my_complex_agent = Agent(
        name="DataProcessorAgent",
        version="2.0.0",
        description="一个用于处理和分析数据的智能体，支持文本总结和图像识别。",
        url="http://localhost:8000/a2a", # 智能体服务的实际运行地址
        capabilities={"streaming": True, "pushNotifications": False},
        skills=[
            {
                "name": "summarizeText",
                "description": "总结提供的文本内容",
                "input": {
                    "type": "object",
                    "properties": {
                        "text": {"type": "string", "description": "需要总结的文本"}
                    },
                    "required": ["text"]
                },
                "output": {
                    "type": "object",
                    "properties": {
                        "summary": {"type": "string", "description": "总结后的文本"}
                    }
                }
            },
            {
                "name": "recognizeImage",
                "description": "识别图像中的对象",
                "input": {
                    "type": "object",
                    "properties": {
                        "imageUrl": {"type": "string", "description": "图像的 URL"}
                    },
                    "required": ["imageUrl"]
                },
                "output": {
                    "type": "object",
                    "properties": {
                        "objects": {
                            "type": "array",
                            "items": {"type": "string"},
                            "description": "识别出的对象列表"
                        }
                    }
                }
            }
        ]
    )

    logger.info("智能体初始化成功，内部 Agent Card 已生成。")
    # 在实际注册之前，您可以打印出 SDK 生成的 Agent Card (仅供调试)
    # 注意：SDK 内部管理此对象，通常您不需要直接操作它。
    # print(my_complex_agent.agent_card.to_json())

    # 注册智能体，发布其 Agent Card 到注册中心
    # 这一步将使其可被其他智能体发现和调用
    try:
        await my_complex_agent.register()
        logger.info(f"智能体 '{my_complex_agent.name}' 及其 Agent Card 注册成功。")
    except Exception as e:
        logger.error(f"智能体注册失败: {e}")
        return
    
    logger.info("智能体正在运行，等待任务...")
    await my_complex_agent.start()

if __name__ == "__main__":
    asyncio.run(main())

4.2 智能体发现和调用中的 Agent Card

当您使用 client_agent.execute_task(target_agent="TargetAgentName", ...) 时，A2A Python SDK 会在内部执行以下步骤：

查询 Agent Card： SDK 会向 A2A 注册中心查询 TargetAgentName 对应的 Agent Card。
解析 Agent Card：获取目标智能体的 url 和特定 task_type 对应的 AgentSkill 定义。
构造请求：根据 AgentSkill 中定义的 input schema，验证并构造 JSON-RPC 请求体。
发送请求：向 Agent Card 中指定的 url 发送请求。

整个过程对开发者是透明的，大大简化了智能体间通信的复杂性。Agent Card 确保了通信双方对请求和响应格式的共识。

5. 最佳实践与注意事项

5.1 准确和完整的描述

清晰的 description：为智能体和每个技能提供准确、简洁、易懂的描述，这对于其他智能体（包括人类用户）理解其功能至关重要。
精确的 input 和 output Schema：使用 JSON Schema 详细定义技能的输入和输出格式，包括字段类型、是否必填、枚举值等。这有助于客户端正确构造请求和解析响应，减少集成错误。