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），僅供參考 ADK-Python Agent Registry 實戰指南：用 Google Cloud Agent Registry 發現 Agent、MCP Server 與模型端點
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），僅供參考