企业官网建设流程全解析

在 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 指南，讲解如何把用 LangGraph（@langchain/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、Java（LangGraph4j）等版本并列，说明这是一条官方维护的标准接入路径。

1. 前置条件：先让 Agent Runtime 能连上 Conductor

运行 LangGraph agent 前，需要先确保 Agent Runtime 可以访问一个 Conductor 服务器，并让服务器能调用你的模型供应商：

• Developer Edition：在 Integrations 中添加 AI/LLM 集成（对应官方 连接 Conductor 指南中的说明）；
• 本地服务器：在启动服务器前导出模型供应商密钥，例如export OPENAI_API_KEY=<your-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

各包职责：

仓库中 Python 版 langgraph 指南 使用conductor-python[langgraph]，与本页的 TypeScript 接入方式一一对应，可互为参考。

3. 配置环境变量

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_AGENT_LLM_MODEL是 Agent SDK 在 Python/Java/TypeScript/C# 全语言通用的约定变量（参见 agent-tool-calling 中的环境变量对照表）。

4. 运行 LangGraph 图

将以下代码保存为langgraph-agent.ts：

import { 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直接运行（无需预先编译 TS）：

npx tsx langgraph-agent.ts

代码要点逐行解读

• createReactAgent（来自@langchain/langgraph/prebuilt）：LangGraph 官方预置的 ReAct 风格 agent 图。三个入参分别对应：
  • llm：传入ChatOpenAI实例。model与第 3 节的CONDUCTOR_AGENT_LLM_MODEL保持一致；temperature: 0让输出更确定，适合工具调用场景；
  • tools：agent 可调用的工具数组。此处为空数组，表示纯 LLM 问答；需要工具时，可把用@langchain/core的tool()装饰的函数传入（仓库 Python 版示例即演示了带calculate工具的写法，见 python/langgraph.md）；
  • name：图的名称，会作为 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 方法）：

Graph-structure 路径的关键细节

对于图结构模式（normalizeGraphStructure，见 LangGraphNormalizer.java），归一化器会识别并处理多种特殊节点与元数据：

• LLM 节点（_llm_node: true）：注册_llm_prep_ref与_llm_finish_ref两个 prep/finish worker，LLM 任务本身由 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验证直通路径生成单个 worker，normalizeGraphStructureWithNodesAndEdges验证节点 worker 注册与_graph_structure元数据，normalizeGraphStructureWithLlmNode验证 LLM prep/finish 注册，normalizeGraphStructureConditionalEdgeMerging验证同源多条条件边可合并而不报错。

6. 验证与排错

按照 框架 Agent 快速入门 中 "Verify and recover" 的建议：

1. 验证结果：对比终端打印的printResult()输出与 Conductor UI 中的执行记录，两者应一致；
2. 排查常见失败：
   • 运行时是否可达——检查CONDUCTOR_SERVER_URL是否正确（本地为http://localhost:8080/api）；
   • 依赖是否齐全——确认@io-orkes/conductor-javascript、@langchain/langgraph等已安装；
   • 模型凭证——服务器侧是否配置了 OpenAI/对应 Provider 的密钥；
3. 失败后的处理：在 UI 中定位失败的 task 后再决定是否重试。切勿对可能已产生外部副作用（如发消息、扣费）的 agent 行为盲目重试，需先明确其幂等性与恢复策略。

7. 从交互运行走向生产

runtime.run(...)适合交互式开发与验证。要让 LangGraph agent 被其他工作流复用，可改用deploy+serve模式：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