adk-python ManagedAgent 实战自定义托管 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本篇围绕 custom_agent 示例 讲解 ADK Python 中ManagedAgent的控制面生命周期如何通过 genai 客户端创建一个人格与服务器端工具已烘焙进去的、持久化命名的自定义托管 Agent 资源再用adk run/adk web驱动它完成多轮对话最后将其删除。读完本文你能完整掌握托管 Agent 的创建参数、运行方式、异步就绪问题处理以及api_client数据面/控制面复用的底层原理。一、示例定位内联配置 vs 自定义资源ManagedAgent支持两种配置方式选择边界必须清晰内联配置不需要创建资源ManagedAgent直接接受instruction...作为人格persona也接受tools[google_search]作为服务器端工具。分别参见 system_instruction 示例 与 basic 示例。自定义资源本示例当你需要一个人格与服务器端工具固化进资源、并且可以被其他应用和其他会话通过 id 复用的可复用、服务器托管 Agent 时才需要通过控制面创建一个具名的 Agent 资源。本示例 agent.py 驱动的就是这条完整生命周期用--create预置资源复用ManagedAgent已经持有的 genai 客户端root_agent.api_client它同时暴露 interactions 与 agent create/delete 两个平面然后用adk web/adk run驱动root_agent最后用--delete删除。完整的后端选择、鉴权与凭据准备参见 ManagedAgent 官方指南。二、前置条件必须使用 GEAP / Vertex 后端自定义 Agent 的创建只能走GEAP / Vertex 后端globallocationGemini API 后端无法创建 Agent 资源。这一点在源码中被硬性执行_managed_agent.py 中把_MANAGED_AGENT_LOCATION global写死为常量因为 Managed Agents API 只在global位置提供服务地域端点会拒绝这些调用例如抛出 Resource setup has just started_validate_client_location 对注入的企业Vertex客户端做位置校验若客户端的location不是global直接抛出ValueError避免以静默失败的方式浪费排障时间单元测试 test_managed_agent.pytest_lazy_client_enterprise_uses_global_location验证了企业模式下惰性创建的客户端确实带enterpriseTrue, locationglobal。因此运行本示例前需要按指南配置 Google Cloud 凭据例如gcloud auth application-default login并启用企业后端GOOGLE_GENAI_USE_ENTERPRISE或旧式的GOOGLE_GENAI_USE_VERTEXAI。三、示例代码全解析示例的核心结构非常精简全文如下取自 contributing/samples/managed_agent/custom_agent/agent.pyimport argparse from dotenv import load_dotenv from google.adk.agents import ManagedAgent load_dotenv() _AGENT_ID adk-custom-search-agent _SYSTEM_INSTRUCTION ( You are a concise research assistant. Use Google Search to ground every answer in current sources, cite the sources you used, and keep answers to a few sentences. ) root_agent ManagedAgent( namecustom_managed_agent, agent_id_AGENT_ID, environment{type: remote}, ) def main() - None: Create or delete the custom managed-agent resource. parser argparse.ArgumentParser( descriptionCreate or delete the custom managed agent for this sample. ) parser.add_argument( --create, actionstore_true, helpCreate the custom managed agent. ) parser.add_argument( --delete, actionstore_true, helpDelete the custom managed agent. ) args parser.parse_args() if not (args.create or args.delete): parser.print_help() return # ManagedAgents genai client also exposes agent create/delete. client root_agent.api_client if args.create: client.agents.create( id_AGENT_ID, base_agentantigravity-preview-05-2026, system_instruction_SYSTEM_INSTRUCTION, tools[{type: google_search}], ) print(fCreated {_AGENT_ID}.) if args.delete: client.agents.delete(id_AGENT_ID) print(fDeleted {_AGENT_ID}.)代码里有三个关键点root_agent只声明、不携带人格ManagedAgent(name..., agent_id_AGENT_ID, environment{type: remote})中没有内联instruction或tools——因为人格_SYSTEM_INSTRUCTION和google_search工具是在创建资源时固化的见client.agents.create(...)运行时通过agent_id连接即自动获得这些能力。agent_id是资源句柄adk-custom-search-agent就是创建出来的具名资源 id创建成功后任何应用只要把ManagedAgent(agent_idadk-custom-search-agent)指向它就能共享同一份人格与工具配置。创建在基座 Agent 之上扩展base_agentantigravity-preview-05-2026表示在 Google 一方托管的 Antigravity 基座 Agent 上叠加自定义system_instruction与tools[{type: google_search}]而不是从零开始。四、三步运行生命周期# 1. 创建自定义 Agent只需一次。 python contributing/samples/managed_agent/custom_agent/agent.py --create # 2. 与它对话。预置可能需要几分钟项目里第一个 Agent 会更久 # 所以 --create 之后稍等片刻再发起第一轮对话。 adk run contributing/samples/managed_agent/custom_agent # 或者adk web # 3. 用完后删除。 python contributing/samples/managed_agent/custom_agent/agent.py --delete异步创建是必须理解的细节--create在 Agent 完全就绪之前就返回了。如果第一轮对话报出 not found / being created 类错误等几秒后重试即可——这不是配置错误而是资源仍在预置中。官方指南也明确说明自定义 Agent 的system_instruction和 tools 在创建时就已固定创建过程是异步的the agent takes a short while to become ready参见 ManagedAgent 指南。五、api_client一个客户端横跨数据面与控制面复用ManagedAgent已持有的 genai 客户端来创建/删除资源是本示例最值得借鉴的技巧。其底层实现在 ManagedAgent.api_client它是一个惰性属性构造时可以不传客户端首次访问时按环境变量解析后端——若GOOGLE_GENAI_USE_ENTERPRISE或旧式GOOGLE_GENAI_USE_VERTEXAI启用则以enterpriseTrue, locationglobal构造google.genai.Client否则构造开发者 API 客户端该 genai 客户端既暴露interactions数据面即 Agent 对话时调用的interactions.create又暴露agents.create/agents.delete控制面即 Agent 资源本身的增删因此示例里client root_agent.api_client之后直接client.agents.create(...)即可不需要另行配置第二个客户端若你在构造时显式注入了api_clientADK 会先做global位置校验企业客户端并原样返回注入的客户端、不会向调用方的客户端附加额外的http_options——这一点由 test_injected_client_is_not_tagged 等测试固化。六、运行时状态恢复为什么多轮对话能接得上示例中environment{type: remote}为每个 interaction 提供一个远程沙箱此项是可选的——basic 示例同样使用而工具不需要沙箱的示例可以省略对照 remote_mcp 示例。多轮对话能够连续的关键在于 ADK 本地的最小状态设计源码位于 ManagedAgent._run_async_impl每轮开始时_find_previous_interaction_state定义于 interactions_processor.py扫描该 Agent 在当前分支上的历史会话事件恢复出最近的previous_interaction_id与沙箱environment_id恢复到的previous_interaction_id会作为create_kwargs传给 interactions 请求environment则优先取上轮恢复的沙箱 idprev_environment_id or self.environment从而让对话历史和沙箱在同一环境里延续一切请求均以backgroundTrue 流式方式发出Managed Agents API 的工作流要求响应事件实时流回 ADKRunner。这意味着本地 ADK 会话只持久化两个 id真正的对话源source of truth在服务端ADK 从不把历史轮次重新发给后端。示例中Summarize that in one sentence这类追问能成功正是这条恢复链在起作用。七、示例输入与交互流图回答基于实时搜索具体文本会有波动。推荐的验证输入What are the most significant AI announcements this week?创建出的 Agent 人格concise cite the sources会让它简洁作答并引用来源搜索由服务器端google_search完成Summarize that in one sentence.复用恢复出的 interaction 的追问轮多轮链式调用。整体交互流与 README 中的 Graph 一致八、How To 要点速查要点做法定义自定义 Agent向client.agents.create(...)传入system_instruction人格与服务器端tools此处为{type: google_search}基于antigravity-preview-05-2026基座 Agent 扩展复用 ManagedAgent 客户端root_agent.api_client即ManagedAgent已持有的 genai 客户端其agents.create/agents.delete覆盖控制面预置沙箱ManagedAgent(environment{type: remote})为每个 interaction 提供远程沙箱——可选且沙箱 id 会被自动恢复复用运行--create预置、--delete删除中间阶段root_agent就是普通的BaseAgentadk web/adk run或Runner均可驱动九、适用前提与限制结合 ManagedAgent 指南 与 源码实现使用该能力前需注意位置锁定仅 GEAPManaged Agents API 目前仅从global位置提供服务使用地域端点的企业客户端会在构造时抛出ValueError仅支持服务器端工具客户端执行的工具Python 函数、callable和裸 MCP 配置不被支持传入会抛NotImplementedError见 _resolve_backend_tools 的校验分支仅流式交互Agent 原生以streamTrue创建 background interaction 并消费流尚不支持非流式轮询执行创建异步--create返回后资源可能仍在预置首轮流失败时应按not found / being created语义稍候重试。配套的相关示例同属 managed_agent 目录basic、code_execution、system_instruction、remote_mcp、single_turn可对照理解内联配置与自定义资源两条路径的差异。【免费下载链接】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），仅供参考