在 Conductor 中运行 TypeScript LangGraph Agent安装、配置与持久化执行原理【免费下载链接】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导读本文基于 Conductor 开源仓库中的 TypeScript Agent 指南讲解如何把用 LangGraphlangchain/langgraph构建的 agent 图通过io-orkes/conductor-javascript的AgentRuntime交给 Conductor 的持久化durable执行引擎运行。读完本文你将掌握 TypeScript 环境下 LangGraph agent 的依赖安装、环境变量配置、一行式运行以及服务端把 LangGraph 图编译为 Conductor 工作流的底层实现原理。背景为什么要把 LangGraph Agent 交给 Conductor 运行LangGraph 擅长表达节点node、边edge与条件分支conditional edge构成的 agent 状态图Conductor 则是一个事件驱动的 agentic workflow 引擎提供 durable、高韧性的执行语义。两者的结合方式是保留你用 LangGraph 定义好的 agent 对象不变由 Conductor SDK 将其编译并作为一次可观测、可恢复的 Conductor 执行来运行。这样 LLM 推理由你的图负责而进度持久化、任务重试、超时与检查等工作交给 Conductor参见框架 Agent 快速入门。仓库中ui-next的 Agent 指南清单 将本页注册为 TypeScript 语言下的langgraph指南与 Python、JavaLangGraph4j等版本并列说明这是一条官方维护的标准接入路径。1. 前置条件先让 Agent Runtime 能连上 Conductor运行 LangGraph agent 前需要先确保 Agent Runtime 可以访问一个 Conductor 服务器并让服务器能调用你的模型供应商Developer Edition在 Integrations 中添加 AI/LLM 集成对应官方 连接 Conductor 指南中的说明本地服务器在启动服务器前导出模型供应商密钥例如export OPENAI_API_KEYyour-openai-api-key再执行conductor server start参考 连接 Conductor 与 first-ai-agent。连接参数通过环境变量注入具体见第 3 节。2. 安装依赖在你的 TypeScript 项目中安装 Conductor JavaScript SDK 与 LangGraph/LangChain 相关包npm install io-orkes/conductor-javascript langchain/langgraph langchain/openai langchain/core各包职责包作用io-orkes/conductor-javascriptConductor 官方 JS/TS SDK提供AgentRuntime导入路径io-orkes/conductor-javascript/agentslangchain/langgraph提供createReactAgent等预置 agent 图构建能力langchain/openai提供ChatOpenAI模型客户端用于构建 LLM 节点langchain/coreLangChain 核心工具与接口tool装饰器等仓库中 Python 版 langgraph 指南 使用conductor-python[langgraph]与本页的 TypeScript 接入方式一一对应可互为参考。3. 配置环境变量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_MODELopenai/gpt-4o-mini环境变量必填说明CONDUCTOR_SERVER_URL是Conductor 服务器 API 地址。占位符{{CONDUCTOR_SERVER_URL}}需替换为实际地址本地服务器为http://localhost:8080/api参考 连接 Conductor云端为对应实例的/api端点CONDUCTOR_AUTH_KEY/CONDUCTOR_AUTH_SECRET认证服务器必填访问密钥对开启认证的服务器如 Developer Edition必须配置否则AgentRuntime无法通过鉴权CONDUCTOR_AGENT_LLM_MODEL是指定 Agent 使用的服务端 LLM 模型格式为provider/model例如openai/gpt-4o-mini其他 Provider 同理如 Google 系可用google_gemini/gemini-2.5-flash参见仓库内其他指南CONDUCTOR_AGENT_LLM_MODEL是 Agent SDK 在 Python/Java/TypeScript/C# 全语言通用的约定变量参见 agent-tool-calling 中的环境变量对照表。4. 运行 LangGraph 图将以下代码保存为langgraph-agent.tsimport { createReactAgent } from langchain/langgraph/prebuilt; import { ChatOpenAI } from langchain/openai; import { AgentRuntime } from io-orkes/conductor-javascript/agents; const graph createReactAgent({ llm: new ChatOpenAI({ model: gpt-4o-mini, temperature: 0 }), tools: [], name: langgraph_assistant, }); const runtime new AgentRuntime(); try { const result await runtime.run(graph, What makes execution durable?); result.printResult(); } finally { await runtime.shutdown(); }用tsx直接运行无需预先编译 TSnpx tsx langgraph-agent.ts代码要点逐行解读createReactAgent来自langchain/langgraph/prebuiltLangGraph 官方预置的 ReAct 风格 agent 图。三个入参分别对应llm传入ChatOpenAI实例。model与第 3 节的CONDUCTOR_AGENT_LLM_MODEL保持一致temperature: 0让输出更确定适合工具调用场景toolsagent 可调用的工具数组。此处为空数组表示纯 LLM 问答需要工具时可把用langchain/core的tool()装饰的函数传入仓库 Python 版示例即演示了带calculate工具的写法见 python/langgraph.mdname图的名称会作为 Conductor 侧 Agent 的标识名。new AgentRuntime()创建运行时实例。它负责把 graph 对象序列化并上传到 Conductor 服务器执行runtime.run(graph, prompt)同步运行图并等待最终结果。await后拿到result对象result.printResult()把 agent 的最终文本输出打印到终端try ... finally { runtime.shutdown() }与 Python 版with AgentRuntime() as runtime:见 framework-agents 中 LangChain/LangGraph 示例对应确保进程结束前优雅释放运行时资源。运行后你不仅能在终端看到结果还能在 Conductor UI 中找到这次执行的可视化记录——每一步的输入输出、重试次数与状态都是可检查的独立持久化记录。5. 底层原理LangGraph 图如何被编译为 Conductor 执行AgentRuntime.run(graph, ...)之所以能直接跑 LangGraph是因为 Conductor 服务端有一个名为agentspan的模块负责把 agent 的原始配置raw config归一化normalize为统一的AgentConfig再编译成 Conductor 工作流。核心实现位于 LangGraphNormalizer.java。该类的frameworkId()返回langgraph注册为 LangGraph 框架的归一化器。它根据原始配置的形态走三条路径见 normalize 方法路径触发条件编译结果Full extraction全量提取原始配置含model与带_worker_ref标记的tools且不含_worker_name、_graph与 OpenAI agent 一致AI_MODEL任务 每个工具一个SIMPLE任务LLM 调用在服务端执行Graph-structure图结构原始配置含_graph包含nodes、edges、conditional_edges每个节点注册为一个SIMPLE任务 worker边决定工作流结构模型仅用于可观测性Passthrough直通原始配置含_worker_name自定义StateGraph整个图作为一个SIMPLE任务运行本地执行图逻辑Graph-structure 路径的关键细节对于图结构模式normalizeGraphStructure见 LangGraphNormalizer.java归一化器会识别并处理多种特殊节点与元数据LLM 节点_llm_node: true注册_llm_prep_ref与_llm_finish_ref两个 prep/finish workerLLM 任务本身由 compiler 构建子图节点_subgraph_node: true注册 prep/finish worker并递归归一化内嵌子图配置存入_subgraph_configs同时把子图的 worker 提升为父图工具人工节点_human_node: true不注册 worker直接映射为 Conductor 的HUMAN系统任务条件边路由conditional_edges中的_router_ref注册为路由 worker元数据透传_reducers影响 FORK_JOIN 状态合并、_retry_policies映射为 Conductor 任务重试配置、_recursion_limit映射为 DO_WHILE 迭代上限都会写入AgentConfig的 metadata供 compiler 使用。这些行为都有对应的单元测试背书见 LangGraphNormalizerTest.java例如normalizeProducesPassthroughConfig验证直通路径生成单个 workernormalizeGraphStructureWithNodesAndEdges验证节点 worker 注册与_graph_structure元数据normalizeGraphStructureWithLlmNode验证 LLM prep/finish 注册normalizeGraphStructureConditionalEdgeMerging验证同源多条条件边可合并而不报错。6. 验证与排错按照 框架 Agent 快速入门 中 Verify and recover 的建议验证结果对比终端打印的printResult()输出与 Conductor UI 中的执行记录两者应一致排查常见失败运行时是否可达——检查CONDUCTOR_SERVER_URL是否正确本地为http://localhost:8080/api依赖是否齐全——确认io-orkes/conductor-javascript、langchain/langgraph等已安装模型凭证——服务器侧是否配置了 OpenAI/对应 Provider 的密钥失败后的处理在 UI 中定位失败的 task 后再决定是否重试。切勿对可能已产生外部副作用如发消息、扣费的 agent 行为盲目重试需先明确其幂等性与恢复策略。7. 从交互运行走向生产runtime.run(...)适合交互式开发与验证。要让 LangGraph agent 被其他工作流复用可改用deployserve模式deploy注册 agent 图而不执行serve保持所需 worker 常驻Python 版示例见 first-ai-agent。之后便可在任意 Conductor 工作流中通过AGENT任务按名称调用它并借助HUMAN审批门、SWITCH路由、FORK_JOIN并行、调度与取消传播等能力组合出完整的 agentic workflow graph见 first-ai-agent。若想深入理解持久化执行到底意味着什么——这也是本页示例 prompt 所问的问题——可阅读 durable-execution.md每次执行的 workflow 定义快照、工作流状态、每个 task 的执行记录与队列状态都会被持久化到配置的存储Redis、PostgreSQL、MySQL 或 Cassandra任务采用至少一次投递语义worker 崩溃、网络分区或服务器重启后都能从最后持久化状态恢复从而保证 agent 执行不丢进度。【免费下载链接】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），仅供参考