3. 智能体技能与智能体卡片

在A2A智能体能够执行任何操作之前，它需要定义自己_能够_做什么（技能）以及其他智能体或客户端如何了解这些能力（智能体卡片）。

本章我们将使用helloworld示例来深入理解这些概念。

🎯 智能体技能（Agent Skills）

智能体技能描述了智能体可以执行的特定能力或功能。它是告诉客户端智能体擅长什么类型任务的构建块。

技能核心属性

AgentSkill对象包含以下关键属性：

属性	类型	描述	示例
`id`	string	技能的唯一标识符	`"hello_world"`
`name`	string	人类可读的技能名称	`"返回Hello World"`
`description`	string	技能功能的详细说明	`"一个简单的问候技能"`
`tags`	list	用于分类和发现的关键词	`["greeting", "basic"]`
`examples`	list	示例提示或用例	`["说hello", "打招呼"]`
`inputModes`	list	支持的输入媒体类型	`["text/plain"]`
`outputModes`	list	支持的输出媒体类型	`["text/plain"]`

技能定义示例

以下是一个简单的Hello World技能定义：

from a2a.types import AgentSkill

hello_world_skill = AgentSkill(
    id="hello_world",
    name="返回Hello World",
    description="一个简单的问候技能，返回Hello World消息",
    tags=["greeting", "basic", "demo"],
    examples=[
        "说hello",
        "打个招呼",
        "问候一下"
    ],
    inputModes=["text/plain"],
    outputModes=["text/plain"]
)

高级技能示例

更复杂的技能可能支持多种输入输出格式：

advanced_skill = AgentSkill(
    id="data_processor",
    name="数据处理器",
    description="处理和分析各种格式的数据",
    tags=["data", "analysis", "processing"],
    examples=[
        "分析这个CSV文件",
        "处理JSON数据",
        "生成数据报告"
    ],
    inputModes=[
        "text/plain", 
        "application/json", 
        "text/csv"
    ],
    outputModes=[
        "application/json", 
        "text/html", 
        "image/png"
    ]
)

📋 智能体卡片（Agent Card）

智能体卡片是A2A服务器提供的JSON文档，通常在.well-known/agent-card.json端点可用。它就像智能体的数字名片。

卡片核心属性

AgentCard对象包含以下关键信息：

属性	类型	描述
`name`	string	智能体名称
`description`	string	智能体描述
`version`	string	版本信息
`url`	string	A2A服务端点URL
`capabilities`	object	支持的A2A功能特性
`defaultInputModes`	list	默认输入媒体类型
`defaultOutputModes`	list	默认输出媒体类型
`skills`	list	智能体提供的技能列表
`securitySchemes`	object	身份验证配置

基础卡片示例

from a2a.types import AgentCard

agent_card = AgentCard(
    name="Hello World智能体",
    description="一个简单的演示智能体，用于学习A2A协议基础",
    version="1.0.0",
    url="http://localhost:9999/",
    
    # 支持的A2A功能特性
    capabilities={
        "streaming": True,           # 支持流式传输
        "pushNotifications": False   # 不支持推送通知
    },
    
    # 默认媒体类型
    defaultInputModes=["text/plain"],
    defaultOutputModes=["text/plain"],
    
    # 智能体技能列表
    skills=[hello_world_skill],
    
    # 身份验证配置（公开访问）
    securitySchemes={
        "public": {
            "type": "public",
            "description": "无需身份验证的公开访问"
        }
    }
)

企业级卡片示例

enterprise_agent_card = AgentCard(
    name="企业数据分析智能体",
    description="专业的企业数据分析和报告生成智能体",
    version="2.1.3",
    url="https://api.example.com/a2a/",
    
    capabilities={
        "streaming": True,
        "pushNotifications": True,
        "longRunningOperations": True
    },
    
    defaultInputModes=["text/plain", "application/json"],
    defaultOutputModes=["application/json", "text/html"],
    
    skills=[
        data_analysis_skill,
        report_generation_skill,
        chart_creation_skill
    ],
    
    # OAuth2身份验证
    securitySchemes={
        "oauth2": {
            "type": "oauth2",
            "flows": {
                "clientCredentials": {
                    "tokenUrl": "https://auth.example.com/token",
                    "scopes": {
                        "read": "读取数据权限",
                        "write": "写入数据权限"
                    }
                }
            }
        }
    }
)

🔍 技能发现机制

客户端发现流程

获取智能体卡片

import requests

# 获取智能体卡片
response = requests.get("http://localhost:9999/.well-known/agent-card.json")
agent_card = response.json()

解析技能信息

# 列出所有可用技能
for skill in agent_card["skills"]:
    print(f"技能: {skill['name']}")
    print(f"描述: {skill['description']}")
    print(f"标签: {skill['tags']}")
    print("---")

选择合适技能

# 根据标签查找技能
def find_skills_by_tag(skills, tag):
    return [skill for skill in skills if tag in skill.get("tags", [])]

greeting_skills = find_skills_by_tag(agent_card["skills"], "greeting")

🛠️ 实践练习

练习1：创建自定义技能

创建一个计算器技能：

calculator_skill = AgentSkill(
    id="calculator",
    name="数学计算器",
    description="执行基础数学运算",
    tags=["math", "calculation", "utility"],
    examples=[
        "计算 2 + 3",
        "求 10 的平方根",
        "解方程 x^2 + 2x + 1 = 0"
    ],
    inputModes=["text/plain"],
    outputModes=["text/plain", "application/json"]
)

练习2：设计智能体卡片

为您的智能体创建完整的卡片：

my_agent_card = AgentCard(
    name="我的第一个A2A智能体",
    description="学习A2A协议的实践项目",
    version="0.1.0",
    url="http://localhost:8000/",
    
    capabilities={
        "streaming": False,
        "pushNotifications": False
    },
    
    defaultInputModes=["text/plain"],
    defaultOutputModes=["text/plain"],
    
    skills=[
        hello_world_skill,
        calculator_skill
    ],
    
    securitySchemes={
        "public": {
            "type": "public"
        }
    }
)

📊 最佳实践

技能设计原则

单一职责 - 每个技能专注于一个特定功能
清晰描述 - 使用明确、易懂的名称和描述
丰富示例 - 提供多样化的使用示例
合适标签 - 使用有意义的标签便于发现

卡片设计原则

完整信息 - 包含所有必要的连接和认证信息
版本管理 - 正确标记版本号，便于兼容性管理
能力声明 - 准确声明支持的A2A特性
安全配置 - 根据需求配置适当的身份验证

🎯 关键要点

智能体技能定义了智能体的具体能力
智能体卡片是智能体的公开身份和能力声明
媒体类型决定了输入输出的数据格式
标签系统便于技能的分类和发现
安全配置控制智能体的访问权限

理解智能体卡片至关重要，因为它是客户端发现智能体并学习如何与其交互的方式。

下一步：智能体执行器 - 我们将学习如何实现智能体的核心执行逻辑。

💡 提示：在设计智能体技能时，思考用户的实际需求和使用场景。好的技能设计是成功的A2A智能体的基础！

2. 环境搭建