Conductor Python 集成 LangGraph:将 React Agent 编译为持久化工作流执行
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"一节,无论哪种框架:
- 核对打印的最终结果,并在 Conductor UI 中找到对应的执行记录;
- 失败时依次排查:运行时服务器 URL、框架包是否正确安装、模型提供方凭证是否可用;
- 定位到失败任务后再重试;在未明确某个 Agent 动作的幂等性与恢复策略之前,不要重试可能已产生外部副作用(side effect)的动作——这正是把 Agent 交给持久化执行引擎的收益之一:每一步有记录、可恢复,恢复边界清晰可查。
7. 继续深入
- 完整的框架 Agent 速查(OpenAI Agents、LangChain、LangGraph、Google ADK):docs/quickstart/framework-agents.md
- 框架 Agent 参考页(支持矩阵与维护示例):docs/devguide/ai/agent-framework-recipes.md
- 已部署 Agent 的运行时行为(调用、等待、恢复、取消、输出契约):docs/devguide/ai/conductor-agents.md
- Agent 概念(编译为工作流图、
AGENT任务、三种编写方式):docs/devguide/concepts/agents.md - LangGraph 规范化源码实现:agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/LangGraphNormalizer.java