ADK-Python Agent Registry 实战指南用 Google Cloud Agent Registry 发现 Agent、MCP Server 与模型端点【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本文基于 ADK-Pythongoogle-adk开源仓库中的官方示例完整讲解如何通过AgentRegistry客户端在 Google Cloud Agent Registry 服务中发现已注册的 A2A Agent、MCP Server 与模型端点并将它们解析为可直接使用的 ADK 组件RemoteA2aAgent、McpToolset、模型名进而组装出具备动态发现能力的 Agent。读完本文你将掌握 Agent Registry 的完整配置、命令行操作与核心 API 用法并理解其底层认证、传输协议解析与资源解析原理。什么是 Agent Registry 集成Google Cloud Agent Registry 是一个集中式的 Agent 注册中心用于登记 A2A Agent、MCP Server 以及模型 Endpoint。ADK-Python 在google.adk.integrations.agent_registry模块中提供了面向 ADK 集成的高层客户端AgentRegistry与普通 REST 客户端不同它除了暴露服务的查询方法外还提供get_mcp_toolset、get_remote_a2a_agent等辅助方法——这些方法会自动解析连接细节并处理认证直接产出开箱即用的 ADK 组件见 agent_registry.py 的类文档。官方示例位于 contributing/samples/integrations/agent_registry_agent/核心脚本为 agent.py配套的 README.md 说明了完整配置与运行方式。环境准备与前置条件运行该示例前需要完成三步准备对应原文档 Setup 章节配置 Google Cloud 凭证确保本机已有有效的 Google Cloud 应用默认凭证例如执行gcloud auth application-default login。AgentRegistry客户端在初始化时会调用google.auth.default()获取默认凭证若缺失会抛出RuntimeError见 agent_registry.py。设置环境变量export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal # or your specific regionGOOGLE_CLOUD_LOCATION默认值为global也可以指定具体区域如us-central1。示例脚本通过os.environ.get读取这两个变量并据此构造注册表的基础路径projects/{project_id}/locations/{location}见 agent.py。获取资源完整名称Agent、MCP Server、Endpoint 都以其完整资源名如projects/.../agents/my-agent为标识。可以运行一次示例脚本列出全部资源也可以用gcloud命令直接查询# For agents gcloud alpha agent-registry agents list --project$GOOGLE_CLOUD_PROJECT --location$GOOGLE_CLOUD_LOCATION # For MCP servers gcloud alpha agent-registry mcp-servers list --project$GOOGLE_CLOUD_PROJECT --location$GOOGLE_CLOUD_LOCATION拿到资源名后将 agent.py 末尾被注释的示例块取消注释并用资源名的最后一段替换其中的AGENT_NAME、MCP_SERVER_NAME和ENDPOINT_NAME。例如资源名为projects/.../agents/my-agent则使用my-agent。运行示例发现已注册的资源环境就绪后直接运行示例脚本python3 agent.py脚本会依次打印三类发现结果见 agent.py项目/区域下注册的所有 Agent含displayName与name所有 MCP Server含displayName与name所有 Endpoint含displayName与name关键词搜索 Workspace 命中的 Agent关键词搜索 agentregistry 命中的 MCP Server。值得说明的是原文档只列出了 Agent 与 MCP Server 的列举而示例脚本还额外调用了list_endpoints()枚举模型端点这是组装模型配置时同样重要的一环。AgentRegistry 核心 API 全景示例使用的核心 API 在AgentRegistry类中均有完整实现见 agent_registry.py按资源类型可归纳如下列举类方法方法作用关键实现list_agents(filter_str, page_size, page_token)获取已注册 A2A Agent 列表GETagents见 agent_registry.pylist_mcp_servers(filter_str, page_size, page_token)获取已注册 MCP Server 列表GETmcpServers见 agent_registry.pylist_endpoints(filter_str, page_size, page_token)获取已注册 Endpoint 列表GETendpoints见 agent_registry.py三个方法均支持filter、pageSize、pageToken参数返回Dict[str, Any]列表字段分别为agents、mcpServers、endpoints。搜索类方法方法作用关键实现search_agents(search_string, search_type, filter_str, order_by, page_size, page_token)搜索已注册 A2A AgentPOSTagents:searchsearch_mcp_servers(search_string, search_type, filter_str, order_by, page_size, page_token)搜索已注册 MCP ServerPOSTmcpServers:search搜索请求体支持searchString、searchType可选值为KEYWORD或SEMANTIC、filter、orderBy、pageSize、pageToken统一由内部_search辅助方法组装并发起 POST 请求见 agent_registry.py。获取类方法get_agent_info(name)获取单个 A2A Agent 的详细元数据get_mcp_server(name)获取单个 MCP Server 的详细元数据get_endpoint(name)获取单个 Endpoint 的详细元数据。从注册表解析 ADK 组件这是AgentRegistry与普通 REST 客户端最大的区别——它将注册表条目直接解析为 ADK 可用的组件对应原文档 How it Works 中被注释示例的三种用法。1. 解析远程 A2A Agent 为子代理remote_agent registry.get_remote_a2a_agent( fprojects/{project_id}/locations/{location}/agents/AGENT_NAME )get_remote_a2a_agent(agent_name)返回RemoteA2aAgent实例见 agent_registry.py。其解析逻辑为若注册条目携带A2A_AGENT_CARD类型的card.content则直接解析该 Agent Card 构造RemoteA2aAgent否则从displayName、description、version、skills等信息构建 Agent Card其中连接 URI 通过_get_connection_uri按A2A_AGENT协议类型提取若未显式传入auth_scheme会自动通过_resolve_auth_provider_scheme依据 IAM bindings 解析出GcpAuthProviderSchemeAgent 名称会经_clean_name清洗为合法的 Python 标识符非字母数字字符统一替换为下划线。2. 解析 MCP Server 为工具集mcp_toolset registry.get_mcp_toolset( fprojects/{project_id}/locations/{location}/mcpServers/MCP_SERVER_NAME )get_mcp_toolset(mcp_server_name)返回McpToolset实例见 agent_registry.py。其解析逻辑为优先尝试JSONRPC传输绑定其次回退到HTTP_JSON_TRANSPORT_MAPPING同时支持HTTP_JSON、JSONRPC、GRPC三种映射构造StreamableHTTPConnectionParams(urlendpoint_uri)作为连接参数若端点指向 Google API 且未配置 auth scheme/credential会自动附加 Bearer 认证头_is_google_api校验https://*.googleapis.com返回的是AgentRegistrySingleMcpToolset子类它会为每个工具注入gcp.mcp.server.destination.id自定义元数据该键会被google.adk.telemetry.tracing用于在execute_toolspan 上标记 MCP 目的地见 agent_registry.py便于链路追踪与按 MCP Server 维度聚合遥测。3. 解析模型端点model_name registry.get_model_name( fprojects/{project_id}/locations/{location}/endpoints/ENDPOINT_NAME )get_model_name(endpoint_name)返回形如projects/adk12345/locations/us-central1/publishers/google/models/gemini-2.5-flash的模型资源名见 agent_registry.py。其实现会从 Endpoint 的连接 URI 中剥离末尾的:方法名后缀并提取projects/...前缀作为模型名。组装完整的发现式 Agent将上述组件组合起来即可得到一个基于注册表动态发现的根 Agent对应 agent.py 末尾的完整示例from google.adk.agents.llm_agent import LlmAgent from google.adk.integrations.agent_registry import AgentRegistry from google.adk.models.google_llm import Gemini # 1. 初始化注册表客户端 registry AgentRegistry(project_idproject_id, locationlocation) # 2. 解析组件将下面的资源名替换为 list 方法打印出的真实资源名 remote_agent registry.get_remote_a2a_agent( fprojects/{project_id}/locations/{location}/agents/AGENT_NAME ) mcp_toolset registry.get_mcp_toolset( fprojects/{project_id}/locations/{location}/mcpServers/MCP_SERVER_NAME ) model_name registry.get_model_name( fprojects/{project_id}/locations/{location}/endpoints/ENDPOINT_NAME ) # 3. 用解析出的模型名初始化模型 gemini_model Gemini(modelmodel_name) # 4. 组装根 Agent root_agent LlmAgent( modelgemini_model, namediscovery_agent, instructionYou have access to tools and sub-agents discovered via Registry., tools[mcp_toolset], sub_agents[remote_agent], )该 Agent 运行时MCP Server 的工具会以tools形式注入注册表中的远程 A2A Agent 可作为子代理被调度模型则来自注册表中登记的 Endpoint——实现了注册表一处登记Agent 各处动态装配的编排模式。底层实现要点认证与 mTLSAgentRegistry初始化时会创建一次requests_auth.AuthorizedSession基于google.auth.default()的应用默认凭证并在每次内部 API 调用时通过merge_tracking_headers附加x-goog-user-project配额项目头见 agent_registry.py。mTLS 端点选择由_should_use_mtls_endpoint决定可通过环境变量GOOGLE_API_USE_MTLS_ENDPOINTauto/always/never与GOOGLE_API_USE_CLIENT_CERTIFICATE控制默认基地址为https://agentregistry.googleapis.com/v1mTLS 模式切换为https://agentregistry.mtls.googleapis.com/v1见 agent_registry.py。依赖说明AgentRegistry的导入依赖a2a-sdk包用于RemoteA2aAgent、AgentSkill与 Agent Card 的构建/解析未安装时会抛出提示pip install google-adk[a2a]的ImportError见 agent_registry.py。测试佐证仓库提供了覆盖上述行为的完整单元测试 test_agent_registry.py共 1104 行验证了get_mcp_toolset注入目的地 ID、auth provider bindings 解析、传输协议选择兼容 A2A 0.3.x 与 1.x 两种 Agent Card 结构等行为。此外test_samples.py 将integrations/agent_registry_agent标记为离线加载跳过项原因是calls Agent Registry API at import——即该示例在模块导入阶段就会访问真实的 Agent Registry API因此必须在配置好 Google Cloud 凭证的网络环境中运行。使用注意事项资源名必须是完整名称get_remote_a2a_agent、get_mcp_toolset、get_model_name等方法的参数是完整资源名如projects/{project}/locations/{location}/agents/{agent}而不是my-agent这样的短名短名仅用于替换示例脚本末尾注释块中的占位符。搜索类型可选search_agents/search_mcp_servers的search_type支持KEYWORD与SEMANTIC默认不指定时由服务端决定。区域选择影响可见资源GOOGLE_CLOUD_LOCATION决定查询范围global适用于全局资源区域资源需指定对应区域。离线路演不可行由于导入即发起网络请求该示例无法离线加载运行前务必确认网络与凭证可用参见 test_samples.py 的跳过说明。延伸阅读示例脚本全文contributing/samples/integrations/agent_registry_agent/agent.py客户端源码src/google/adk/integrations/agent_registry/agent_registry.py单元测试tests/unittests/integrations/agent_registry/test_agent_registry.py远程 A2A Agent 相关指南docs/guides/agents/remote_a2a_agent/【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考