使用 Conductor 运行 Google ADK 智能体Python 快速入门与底层实现解析【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor本指南讲解如何将用 Google Agent Development KitGoogle ADK编写的智能体Agent接入 Conductor 的 Agent 运行时AgentRuntime使其以工作流的形式获得可观测、可恢复的持久化执行能力。读完本文你将掌握conductor-python[adk]的安装配置、环境变量设置、Python 端完整运行示例并理解服务端如何通过GoogleADKNormalizer把 ADK 智能体配置编译为 Conductor 的AgentConfig与可执行工作流。本文以 python/google-adk.md 为骨架展开并补充仓库内 Java、TypeScript、C# 三种语言的等价指南以及服务端规范化的源码实现与测试证据。Google ADK 智能体为什么需要 ConductorGoogle ADK 提供了一套声明式智能体定义方式Agent(name, model, instruction, ...)让开发者可以快速搭建单智能体或多智能体应用。但它本身不负责编排的持久化一旦进程中断、网络抖动或下游任务失败运行中的智能体会话就可能丢失进度。Conductor 是一个事件驱动的智能体工作流引擎event-driven agentic workflow engine为应用与 AI 智能体提供耐用durable、高弹性的执行环境。把 ADK 智能体交给 Conductor 后编译为工作流Conductor SDK 会把框架智能体对象编译成可执行的工作流定义每个 LLM 调用、工具调用都成为工作流中的任务节点可观测每次执行都会在 Conductor UI 中留下完整、可检查的执行记录可恢复任务失败、超时可以按照定义好的策略重试或回滚执行状态持久化保存。快速入门文档 framework-agents.md 明确指出你保留框架定义的智能体对象由 Conductor SDK 将其编译并作为耐用的、可检查的 Conductor 执行运行。本文档对应的 Python 指南正是这条路径在 Google ADK 上的具体落地。前置条件在运行任何 ADK 智能体之前需要先完成两件事连接 Conductor 服务完成 Connect to Conductor 中的步骤确保运行时可以访问你的 Conductor 服务器。典型配置是export CONDUCTOR_SERVER_URLhttp://localhost:8080/api本地开发也可以直接用 Docker 启动官方镜像Java 21docker run --rm -p 8080:8080 conductoross/conductor:latest配置模型提供方ADK 示例默认使用 Gemini 模型因此服务器需要能够调用 Google Gemini。在本地服务器上需要在启动前导出对应的 provider API key可参考 llm-orchestration.md 中列出的受支持 LLM 提供方若使用 Developer Edition则在集成Integrations中添加 AI/LLM 集成。第一步安装 SDKPython 使用带adk扩展的安装方式一条命令同时安装 Conductor 客户端与 Google ADK 支持python -m pip install conductor-python[adk]第二步配置环境变量export CONDUCTOR_SERVER_URL{{CONDUCTOR_SERVER_URL}} # For authenticated Conductor servers: # export CONDUCTOR_AUTH_KEYYOUR_AUTH_KEY # export CONDUCTOR_AUTH_SECRETYOUR_AUTH_SECRET export CONDUCTOR_AGENT_LLM_MODELgoogle_gemini/gemini-2.0-flash各变量的作用环境变量说明CONDUCTOR_SERVER_URLConductor 服务器 API 地址必填CONDUCTOR_AUTH_KEY/CONDUCTOR_AUTH_SECRET访问受认证服务器如 Developer Edition时的凭证可选CONDUCTOR_AGENT_LLM_MODEL智能体使用的默认 LLM 模型采用provider/model格式ADK 指南中为google_gemini/gemini-2.0-flash注意模型名的写法这里带上了google_gemini/前缀与 ADK 智能体定义里裸写的gemini-2.0-flash不同。原因是 Conductor 使用统一的provider/model命名空间来路由到不同模型提供方这与 java/google-adk.md、typescript/google-adk.md 中的环境变量设置保持一致TypeScript 指南使用google_gemini/gemini-2.5-flash。第三步编写并运行 ADK 智能体保存为adk_agent.pyfrom conductor.ai.agents import AgentRuntime from google.adk.agents import Agent agent Agent( nameadk_greeter, modelgemini-2.0-flash, instructionYou are friendly and concise., ) with AgentRuntime() as runtime: result runtime.run(agent, Say hello and share an ML fact.) result.print_result()运行python adk_agent.py代码要点agent是完全标准的 Google ADK 智能体定义没有任何 Conductor 专属字段AgentRuntime是 Conductor 提供的运行时入口with语句负责其生命周期管理runtime.run(agent, ...)接收 ADK 智能体对象与用户输入返回执行结果result.print_result()打印最终输出。运行之后可以回到 Conductor UI 查看本次执行的完整记录。若执行失败framework-agents.md 给出的排查顺序是先检查运行时服务器 URL、框架包版本与模型提供方凭证再定位失败的任务并重试。底层原理服务端的 GoogleADKNormalizerADK 智能体之所以能被 Conductor 执行关键在服务端有一个专门针对 Google ADK 的配置规范化器GoogleADKNormalizer见 agentspan/.../normalizer/GoogleADKNormalizer.java。它把 SDK 上传的 ADK 原始配置raw config转换为 Conductor 的统一内部表示AgentConfig其frameworkId()返回google_adk。从源码注释与实现可以总结出它与 OpenAI 风格配置的三个关键差异instruction单数ADK 使用单数instruction而 OpenAI 风格使用复数instructions规范化器先读instruction缺失时回退到instructions同时支持global_instruction前缀拼接GoogleADKNormalizer.java。sub_agents替代handoffsADK 通过sub_agents声明子智能体。规范化器根据_type字段映射执行策略SequentialAgent→SEQUENTIAL、ParallelAgent→PARALLEL、其他默认HANDOFF转交LoopAgent则映射为SEQUENTIAL并取max_iterations作为maxTurnsGoogleADKNormalizer.java。模型名自动加前缀如gemini-2.0-flash会被自动补全为google_gemini/gemini-2.0-flashensureProvider方法若模型名本身已含/如openai/gpt-4o则原样保留GoogleADKNormalizer.java。此外它还处理了以下几类 ADK 特性帮助你理解 ADK 智能体的哪些能力可以迁移到 Conductor工具toolsFunctionTool映射为worker类型的工具AgentTool会把内嵌子智能体包装成可调用的工具GoogleSearchTool不会生成空的 HTTP 任务而是记录为_builtin_web_search元数据由AgentCompiler映射为LLM_CHAT_COMPLETE任务的webSearch标志GoogleADKNormalizer.javaCodeExecutionTool开启代码执行配置。回调callbacksbefore_model_callback、after_model_callback、before_tool_callback等字段中带_worker_ref的会转换为CallbackConfig位置 任务名从而在工作流中插入对应的 worker 任务。守卫guardrailsguardrails、input_guardrails、output_guardrails会被转换为GuardrailConfig列表保证 ADK 侧通过AdkBridge.agentBuilder(...).guardrails(...)附加的安全钩子能编译进工作流。规划器与思考配置ADK 的planner字段映射为enablePlanning先规划后执行generate_content_config中的temperature、max_output_tokens、thinking_config分别映射为对应的模型参数。模型覆盖环境变量AGENT_DEFAULT_MODEL可以全局覆盖 ADK 智能体里声明的模型格式同样是provider/model如openai/gpt-4o-mini、anthropic/claude-sonnet-4-20250514这在无法使用 Gemini 时尤其有用GoogleADKNormalizer.java。测试用例进一步印证了这些行为见 agentspan/.../GoogleADKNormalizerTest.javagoogleSearchToolUsesProviderNativeSearchInsteadOfAnEmptyHttpTask声明GoogleSearchTool后规范化结果中不会出现带google_search的 HTTP 任务而是设置webSearchtrue的LLM_CHAT_COMPLETE任务googleSearchToolRejectsProvidersWithoutNativeWebSearch对ollama/llama3这类不支持原生联网搜索的模型编译会抛出IllegalArgumentException提示需要 OpenAI 或 Anthropic 模型transferDefaultsToNoSynthesisSoTheSubAgentRemainsTheFinalSpeaker与transferCanOptIntoSynthesis默认情况下子智能体转交后即作为最终发言者不生成_final汇总任务只有配置synthesizetrue时才生成父智能体的汇总任务。其他语言的等价指南本文档所在的指南体系覆盖四种语言注册表见 ui-next/src/pages/agent/guides/manifest.ts其中 Google ADK 在 Python、TypeScript、Java、.NET 下均有对应指南语言指南文件关键依赖 / 入口Pythonpython/google-adk.mdconductor-python[adk]conductor.ai.agents.AgentRuntimeTypeScripttypescript/google-adk.mdio-orkes/conductor-javascriptgoogle/adkAgentRuntime需显式shutdown()Javajava/google-adk.mdorg.conductoross:conductor-aicom.google.adk:google-adk:1.3.0通过AdkBridge.toAgentspan(adkAgent)桥接.NETdotnet/google-adk.mdconductor-ai-google-adk包GoogleADKAgent.Builder()各语言的运行语义一致定义 ADK 智能体 → 构造 AgentRuntime →run(agent, prompt)→ 打印结果。其中 Java 版显式展示了桥接层AdkBridge.toAgentspan(adkAgent)这与服务端GoogleADKNormalizer负责的规范化工作形成客户端序列化 → 服务端规范化的完整链路。进阶案例ADK 智能体接入工作流仓库的 Cookbook 提供了一个完整的生产化示例google-adk-order-triage.md见 docs/devguide/ai/cookbook/google-adk-order-triage.md。它演示了用 Google ADK 编写一个订单异常分流智能体不执行任何变更操作、只给出处置建议再通过 Conductor 工作流调用它。ADK 侧使用 MCP 工具获取证据from conductor.ai.agents import AgentRuntime from google.adk.agents import Agent from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams agent Agent( nameadk_order_exception_triage, modelopenai/gpt-4o, instructionUse MCP evidence to recommend a disposition; never execute it., tools[McpToolset(connection_paramsStreamableHTTPConnectionParams(urlhttp://127.0.0.1:3001/mcp))], ) with AgentRuntime() as runtime: runtime.run(agent, Order O-42 arrived damaged.)部署脚本 deploy_local_cookbook_agents.py 负责把该智能体部署到本地并保持工具 worker 运行python3 deploy_local_cookbook_agents.py deploy python3 deploy_local_cookbook_agents.py serve随后注册并启动工作流定义 google-adk-order-triage.jsonconductor workflow create google-adk-order-triage.json conductor workflow start -w google_adk_order_exception_triage --sync -i {orderId:O-42,exception:Package damaged in transit.}工作流定义中的AGENT任务展示了 ADK 智能体的调用方式google-adk-order-triage.json{ name: triage_order_exception, taskReferenceName: triage_order_exception, type: AGENT, inputParameters: { agentType: conductor, name: adk_order_exception_triage, prompt: Order ${workflow.input.orderId}; exception: ${workflow.input.exception}. Recommend a disposition only. } }该示例还给出了几条生产要点任务里的agentType是conductor而不是adk因为真正运行它的是 Conductor 运行时使用的模型必须是服务器实际配置过的模型若配置了 Gemini则用gemini-2.0-flash应限制工具访问范围与迭代预算分流智能体只给出建议、不执行处置实际动作应走审批流对账请使用订单 ID 异常事件 ID的组合键。验证与故障排查每次执行后建议做三件事核对输出result.print_result()打印的最终结果是否合理在 UI 中定位执行在 Conductor UI 找到本次执行查看 LLM 任务、工具调用任务的输入输出与状态流转失败时按序排查依次检查CONDUCTOR_SERVER_URL是否正确可达、conductor-python[adk]与google-adk包版本是否匹配、CONDUCTOR_AGENT_LLM_MODEL指向的模型是否已在服务器侧配置凭证。另外如果模型调用涉及外部副作用如已发起外部请求在明确其幂等性与恢复策略之前不要盲目重试智能体动作。小结从本文档出发可以看到一条清晰的路径ADK 负责智能体定义Conductor 负责耐用执行。Python 端只需安装conductor-python[adk]、配置三个环境变量、用AgentRuntime包住标准 ADK 智能体即可。底层由服务端GoogleADKNormalizer完成从 ADK 配置到AgentConfig、再到可执行工作流的编译工具、子智能体、守卫、回调等能力均有对应映射并通过GoogleADKNormalizerTest覆盖验证。若需进一步深入可继续阅读 conductor-agents.md 与 agent-framework-recipes.md。【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考