第十章 智能体通信协议 知识树

一、MCP协议（Model Context Protocol）

核心定位

智能体与工具的标准化通信协议，统一外部服务访问接口，支持上下文共享，适配多传输方式

核心组件（hello_agents/protocols/mcp/）

1. MCPClient（client.py）- 客户端实现

核心功能函数

• __init__：初始化客户端，支持Memory/Stdio/HTTP/SSE/StreamableHTTP五种传输方式
• list_tools：获取服务器所有可用工具描述（名称/参数/描述）
• call_tool：调用指定工具，传入标准化参数，返回执行结果
• list_resources：列出服务器提供的资源（被动数据）
• read_resource：读取指定资源内容
• list_prompts：列出预定义提示模板
• get_prompt：获取指定提示模板并填充参数

关键实现细节

• 异步/同步双API支持，优先异步处理并发请求
• 传输层无关设计，通过transport_type适配不同通信方式
• 自动处理参数类型转换、错误捕获与重试机制

2. MCPServer（server.py）- 服务器实现

核心功能函数

• __init__：初始化服务器，定义名称/描述等元数据
• add_tool：注册工具函数，自动解析参数 schema
• run：启动服务器，监听对应传输方式的请求
• _handle_request：统一请求处理入口，分发工具调用/资源访问请求

关键实现细节

• 基于FastMCP 2.0封装，兼容MCP协议标准
• 支持工具/资源/提示模板三类核心能力注册
• 自动生成工具描述与输入schema，无需手动编写

3. MCPTool（hello_agents/tools/builtin/protocol_tools.py）- 工具封装

核心功能函数

• __init__：接收server_command或传输配置，初始化MCPClient
• run：统一入口，支持list_tools/call_tool/list_resources等操作
• _auto_expand_tools：自动展开MCP服务器工具为独立工具，支持Agent直接调用

关键实现细节

• 工具自动展开机制，前缀拼接避免命名冲突（如fs_read_file）
• 内置演示服务器（Memory传输），支持快速测试
• 兼容社区MCP服务器，通过npx命令一键启动

典型使用流程函数调用链

1. 初始化客户端：MCPClient(server_command=["npx", "server-filesystem", "."])
2. 发现工具：await client.list_tools()
3. 调用工具：await client.call_tool("read_file", {"path": "README.md"})
4. 结果处理：自动解析返回结果，适配Agent上下文

二、A2A协议（Agent-to-Agent Protocol）

核心定位

智能体间点对点协作协议，支持任务协商、技能调用，实现对等通信与协作

核心组件（hello_agents/protocols/a2a/）

1. A2AServer（implementation.py）- 服务端实现

核心功能函数

• __init__：初始化智能体服务，定义名称/描述/能力清单
• skill：装饰器，注册技能函数（如计算/研究/撰写）
• run：启动服务，监听指定端口的A2A请求
• _handle_skill_call：解析技能调用请求，执行对应函数并返回结果

关键实现细节

• 支持任务生命周期管理（创建/协商/执行/完成/失败）
• 技能函数自动解析输入参数，支持复杂参数结构
• 基于a2a-sdk封装，兼容A2A协议标准

2. A2AClient（implementation.py）- 客户端实现

核心功能函数

• __init__：初始化客户端，指定目标智能体服务URL
• execute_skill：调用目标智能体的指定技能，传入任务参数
• negotiate：发起任务协商请求，支持提案/反提案流程

关键实现细节

• 遵循A2A请求生命周期（代理发现→身份验证→消息发送→响应接收）
• 支持任务委托、进度跟踪与异常处理
• 对等通信设计，客户端可同时作为服务端提供技能

3. A2ATool（hello_agents/tools/builtin/protocol_tools.py）- 工具封装

核心功能函数

• __init__：绑定目标智能体URL，定义工具名称/描述
• run：统一调用入口，分发技能执行/协商请求

关键实现细节

• 适配Agent工具系统，支持自动技能发现与调用
• 封装网络请求细节，简化智能体间协作调用

三、ANP协议（Agent Network Protocol）

核心定位

大规模智能体网络基础设施协议，提供服务发现、路由与负载均衡，支持去中心化协作

核心组件（hello_agents/protocols/anp/）

1. ANPDiscovery - 服务发现中心

核心功能函数

• __init__：初始化发现中心，维护服务注册表
• register_service：注册智能体服务（ID/类型/能力/端点/元数据）
• discover_services：按服务类型/能力筛选可用智能体
• get_service_by_id：通过服务ID获取具体服务信息

关键实现细节

• 基于语义描述建立服务索引，支持模糊匹配
• 元数据支持负载/版本/资源配置等筛选维度

2. ANPNetwork - 网络拓扑管理

核心功能函数

• __init__：初始化网络，指定网络ID
• add_node：添加智能体节点（服务ID+端点）
• connect_nodes：建立节点间连接，基于能力匹配构建拓扑
• get_network_stats：获取网络节点数/连接数等统计信息
• route_task：基于负载/能力/网络延迟智能路由任务

关键实现细节

• 支持星型/网状/分层等多种拓扑结构
• 路由算法融合任务类型、节点负载、网络状态多因素

3. ANPTool（hello_agents/tools/builtin/protocol_tools.py）- 工具封装

核心功能函数

• __init__：关联服务发现中心，定义工具名称
• run：统一入口，支持服务注册/发现/路由操作

关键实现细节

• 适配Agent工具调用流程，简化网络级服务交互
• 内置负载均衡逻辑，自动选择最优服务节点

四、自定义MCP服务器实现（实战）

核心开发流程函数

1. MCPServer.__init__：创建服务器实例，定义元数据
2. 工具函数定义：实现具体业务逻辑（如天气查询/数据处理）
3. add_tool：注册工具函数到服务器
4. run：启动服务器，监听请求

示例：天气查询MCP服务器

# 核心函数实现
def get_weather(city: str) -> str:
    """获取指定城市天气"""
    weather_data = get_weather_data(city)  # 调用外部天气API
    return json.dumps(weather_data, ensure_ascii=False)

# 服务器注册与启动
weather_server = MCPServer(name="weather-server", description="天气查询服务")
weather_server.add_tool(get_weather)
weather_server.add_tool(list_supported_cities)  # 辅助工具
if __name__ == "__main__":
    weather_server.run()

发布与部署

• 支持Smithery平台发布，配置smithery.yaml/pyproject.toml文件
• 提供Dockerfile封装，支持容器化部署
• 发布后可通过smithery install一键安装使用

五、三大协议工具整合（hello_agents/tools/builtin/protocol_tools.py）

统一工具接口

1. 核心共性函数

• __init__：接收协议配置（服务器命令/URL/发现中心等）
• run：统一操作入口，按action分发请求（call_tool/list_tools/discover等）

2. 集成关键逻辑

• 自动适配Agent工具注册表，支持add_tool直接添加
• 工具描述自动生成，无需手动编写函数schema
• 错误统一处理，返回Agent可解析的标准化结果