Conductor Python 集成 LangGraph:将 React Agent 编译为持久化工作流执行

原创2026-09-09 19:16:021,765 阅读
文章标签:后端工作流自动化流程编排微服务任务调度人工智能大模型AI AgentAgent 工作流工具调用前端消息队列

Conductor Python 集成 LangGraph:将 React Agent 编译为持久化工作流执行

LangGraph 是构建有状态、图结构 LLM Agent 的主流框架,而 Conductor 是一个事件驱动的 Agentic 工作流引擎。本指南基于仓库内的官方速查文档 ui-next/src/pages/agent/guides/python/langgraph.md,讲解如何用 conductor-python[langgraph] 扩展包把已有的 LangGraph 图交给 Conductor 的持久化运行时执行:读完本文,你将掌握安装与连接配置、用 AgentRuntime 运行 create_react_agent 构建的图、理解 LangGraph 被编译为工作流的底层机制,并能把部署后的 Agent 通过 AGENT 任务嵌入任意工作流。

1. 安装与连接配置

LangGraph 属于 Conductor 的"框架 Agent"路线:你保留 LangGraph 自己定义的 agent 对象,Conductor SDK 负责把它编译并执行为一次可观测的持久化执行。第一步是安装带 LangGraph 支持的 Python SDK:

python -m pip install 'conductor-python[langgraph]'

安装完成后,需要让运行时能够连接 Conductor 服务器并访问模型提供方。参考仓库文档 docs/quickstart/connect.md 中的连接步骤,设置以下环境变量:

export CONDUCTOR_SERVER_URL={{CONDUCTOR_SERVER_URL}}
# For authenticated Conductor servers:
# export CONDUCTOR_AUTH_KEY=<YOUR_AUTH_KEY>
# export CONDUCTOR_AUTH_SECRET=<YOUR_AUTH_SECRET>
export CONDUCTOR_AGENT_LLM_MODEL=openai/gpt-4o-mini

各变量作用如下:

  • CONDUCTOR_SERVER_URL:Conductor 服务器 API 地址。本地开发服务器一般为 http://localhost:8080/api(可参考 docs/quickstart/connect.md 的本地服务器与 Docker 启动方式),也可以指向云端 Developer Edition 的 /api 端点。
  • CONDUCTOR_AUTH_KEY / CONDUCTOR_AUTH_SECRET:访问受认证保护的 Conductor 服务器时使用(如 Developer Edition 的应用访问密钥),本地未开启认证的服务器可省略。
  • CONDUCTOR_AGENT_LLM_MODEL:Agent 运行时默认使用的模型标识,这里指定为 openai/gpt-4o-mini。

在启动服务器或 Agent 工作进程前,还需要让服务器能调用你的模型提供方:本地服务器需在启动前导出提供方 API Key(如 export OPENAI_API_KEY=<your-openai-api-key>),详见 docs/devguide/ai/llm-orchestration.md。同时,部署或调用 Conductor Agent 前需要在服务器配置中启用 AI 集成,即设置 conductor.integrations.ai.enabled=true(见 docs/devguide/ai/conductor-agents.md)。

2. 运行一个 LangGraph 图

安装并配置完成后,就可以把 LangGraph 图直接交给 Conductor 运行。仓库速查文档给出了最小可运行示例,保存为 langgraph_agent.py:

from conductor.ai.agents import AgentRuntime
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

graph = create_react_agent(
    ChatOpenAI(model="gpt-4o-mini", temperature=0),
    tools=[],
    name="langgraph_assistant",
)

with AgentRuntime() as runtime:
    result = runtime.run(graph, "What makes a workflow durable?")
    result.print_result()

代码要点:

  • create_react_agent 是 LangGraph 预构建的 ReAct 风格 Agent,这里使用 langchain_openai.ChatOpenAI 作为底层模型,temperature=0 保证输出确定性更好;tools=[] 表示本示例不挂任何工具,name 用于标识图。
  • AgentRuntime 是 Conductor 的运行时上下文,用 with 语句管理生命周期(对应 runtime.shutdown() 的释放)。
  • runtime.run(graph, ...) 接收的不是 Conductor 自己的 Agent 对象,而是原生的 LangGraph 图——这正是"框架 Agent"路线的核心:authoring 仍然属于 LangGraph,Conductor 只负责其外围的持久化执行。

运行:

python langgraph_agent.py

运行结束后,print_result() 会打印最终结果;与此同时,这次执行在 Conductor UI 中生成一条完整的、可检视的执行记录。仓库文档 docs/quickstart/first-agent.md 的"Verify and recover"一节建议:在 UI 中定位本次执行,核对终止状态,并检查任务时间线、输入与输出;如果运行无法触达模型,先确认服务器 URL 与工作进程环境中的提供方凭证,再检查失败任务。

3. 进阶:为 LangGraph Agent 挂载工具

实际 Agent 几乎都需要调用工具。仓库文档 docs/quickstart/framework-agents.md 的 LangGraph 一节给出了带自定义工具的完整示例——用 langchain_core.tools.tool 装饰一个数学计算函数,把它作为 create_react_agent 的工具传入:

import math
from conductor.ai.agents import AgentRuntime
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

@tool
def calculate(expression: str) -> str:
    """Evaluate a limited math expression."""
    return str(eval(expression, {"__builtins__": {}}, {"sqrt": math.sqrt, "pi": math.pi}))

graph = create_react_agent(
    ChatOpenAI(model="gpt-4o-mini", temperature=0), tools=[calculate], name="math_agent"
)

with AgentRuntime() as runtime:
    result = runtime.run(graph, "What is sqrt(256) + 2**10?")
    result.print_result()

与第 2 节最小示例相比,变化只有一个:tools=[calculate]。运行时同样通过 AgentRuntime 提交,Conductor 会把"模型调用工具→拿到结果→继续下一轮"的循环完整落为工作流中的任务序列。这个示例刻意使用 {"__builtins__": {}} 限制 eval 的命名空间,只暴露 sqrt 与 pi,体现的是对工具代码安全性的基本约束,并非建议在生产中直接 eval 任意表达式。

4. 底层原理:LangGraph 图如何被编译为工作流

"框架 Agent 能变成持久化执行"并非魔法。在仓库的 agentspan 模块中,LangGraphNormalizer(见 agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/LangGraphNormalizer.java)负责把 LangGraph 的序列化配置(rawConfig)规范化为统一的 AgentConfig。从源码注释与实现看,它支持三条序列化路径:

  • 完整提取(Full extraction):rawConfig 中带 model 与带 _worker_ref 标记的 tools,规范化结果与 OpenAI 路线一致——生成一个 AI_MODEL 任务加每个工具一个 SIMPLE 任务;model、temperature、max_tokens 等参数被映射到 AgentConfig 对应字段,工具被映射为 ToolConfig(toolType: "worker")。
  • 图结构(Graph-structure):rawConfig 带 _graph 键,包含节点(nodes)与边(edges/conditional_edges)。每个节点变成一个 SIMPLE 任务 worker,边定义工作流结构;其中 _llm_node 节点会额外注册 prep/finish worker 并由编译器构建 LLM 任务,_subgraph_node 会递归规范化子图配置并注册子图 worker,_human_node 则直接映射为 Conductor 的 HUMAN 系统任务(无需 worker)。模型名保留用于可观测性。
  • 透传(Passthrough):rawConfig 带 _worker_name(自定义 StateGraph),整个图在单个 SIMPLE 任务中运行。

也就是说,LangGraph 图的节点、边、条件分支会被翻译成 Conductor 的工作流结构,模型调用与工具调用分别成为工作流任务。这与 docs/devguide/concepts/agents.md 中"Agents are workflows underneath"的说明一致:一次 Agent 运行就是一次工作流执行,每一轮对话都被持久化,崩溃或重启可从最后一个已完成步骤继续,重试与超时遵循同样的策略,且每次运行都留下完整可回放的历史。对应测试用例可参考 agentspan/src/test/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/LangGraphNormalizerTest.java。

5. 生命周期:从 run 到 deploy、serve、AGENT 任务

docs/devguide/ai/agent-framework-recipes.md 总结了框架 Agent 的四个阶段,在 Python SDK 中它们是对同一个 AgentRuntime 的四个调用:

from conductor.ai.agents import AgentRuntime
from langchain.agents import create_agent

agent = create_agent("openai:gpt-4o-mini", tools=[],
                     system_prompt="You are a helpful assistant.")

with AgentRuntime() as runtime:
    runtime.run(agent, "Is the token set?")  # develop: compile and execute once
    runtime.plan(agent)                      # CI: inspect the compiled graph
    runtime.deploy(agent)                    # release: register without executing
    runtime.serve(agent)                     # operate: run tool workers and block
  • run:开发期使用,编译并立即执行一次,第一次运行即可在 UI 看到执行记录;
  • plan:只检查编译后的工作流图,适合开发期与 CI 中部署前的预检;
  • deploy:把编译后的 Agent 以带版本号的名称注册到服务器,此后调用方无需引入 LangGraph 及其依赖即可调用;
  • serve:阻塞式运行工具 worker 进程,用于生产环境持续执行 Agent 的工具。

serve() 会阻塞,因此生产环境应把它放在独立的长生命周期 worker 进程中,而 deploy() 放在 CI/CD 流程里。Agent 部署后,父工作流通过 AGENT 任务按名称调用它(见 docs/devguide/ai/conductor-agents.md):

{
  "name": "run_agent",
  "taskReferenceName": "run_agent_ref",
  "type": "AGENT",
  "inputParameters": {
    "agentType": "conductor",
    "name": "<deployed-agent-name>",
    "prompt": "${workflow.input.prompt}",
    "pollIntervalSeconds": 5
  }
}

需要注意:agentType 选择的是执行模式而非 authoring 框架——agentType: "conductor" 表示运行按 name 选中的已部署 Conductor Agent,而 LangGraph 只是 SDK 侧的编写路径,不是 agentType 的取值。AGENT 任务会写入 executionId、agentName、state、text 及完成后的结构化 output;state 采用归一化的 A2A 生命周期值(working、input-required、completed、failed、canceled)。当 Agent 等待外部输入时,任务状态映射为 COMPLETED 并携带 waiting: true,工作流可借助 HUMAN 任务收集答复后,用 executionId + prompt 再次发起 AGENT 任务恢复同一运行(参见 docs/devguide/ai/conductor-agents.md 的 resume 示例)。仓库 ai/examples 目录下的 31-conductor-agent-basic.json 至 34-conductor-agent-cancel.json 分别演示了已部署 Agent 作为工作流一步、WAITING→HUMAN→按 executionId 恢复、并行多 Agent 以及取消传播等契约。

6. 验证与排错要点

参考 docs/quickstart/framework-agents.md 的"Verify and recover"一节,无论哪种框架:

  1. 核对打印的最终结果,并在 Conductor UI 中找到对应的执行记录;
  2. 失败时依次排查:运行时服务器 URL、框架包是否正确安装、模型提供方凭证是否可用;
  3. 定位到失败任务后再重试;在未明确某个 Agent 动作的幂等性与恢复策略之前,不要重试可能已产生外部副作用(side effect)的动作——这正是把 Agent 交给持久化执行引擎的收益之一:每一步有记录、可恢复,恢复边界清晰可查。

7. 继续深入

登录后查看全文
conductor