企业官网建设流程全解析

Conductor × LangChain TypeScript 实战：把现有 AgentExecutor 桥接为持久化、可观测的 Agentic 工作流

【免费下载链接】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 开源项目中的 LangChain 桥接能力（TypeScript / JavaScript 版本），讲解如何将你应用里已经用 LangChain 构建好的AgentExecutor原样交给 Conductor SDK，由AgentRuntime编译并执行成一份持久的、可在 UI 中回溯审计的 Conductor 工作流执行记录。读完本文，你将掌握 LangChain Agent 的安装与连接配置、AgentRuntime.run的完整调用方式、内省歧义时的createAgentExecutor兜底方案，以及把该 Agent 进一步deploy为可复用的AGENT任务供上层工作流调用的全链路能力。

为什么要把 LangChain Agent 交给 Conductor

Conductor 是一个事件驱动的 agentic 工作流引擎，为应用和 AI Agent 提供持久化、高韧性的执行能力。LangChain（及其AgentExecutor）负责的是"模型决定下一步做什么"的推理循环，而 Conductor 负责的是"这个循环每一步都被可靠记录、可恢复、可审计"的编排底座。

从 Agent 概念文档 可以看到核心设计：Agent 底层就是工作流。当你把 LangChain 的 executor 交给 Conductor 后，SDK 会把它编译成一个普通的工作流图（workflow graph），图中每一次模型调用是一个任务（task）、每一次工具调用是一个任务，模型与工具之间的循环则是工作流控制流。正因为一次 Agent 运行就是一次工作流执行，工作流的既有能力全部继承过来：

• 每一步（turn）都被持久化，进程崩溃或重启后可从最后一个已完成步骤恢复；
• 重试与超时遵循既有任务策略；
• 运行全程留有完整历史，可在 Conductor UI 中检查、回溯；
• 可以在任意一步插入人工审批（human task）。

1. 安装与配置

LangChain 桥接需要安装 Conductor 的 TypeScript SDK 以及 LangChain 核心包和模型提供方包（以下命令与配置均来自本仓库的 TypeScript LangChain 指南）：

npm install @io-orkes/conductor-javascript @langchain/core @langchain/openai export CONDUCTOR_SERVER_URL={{CONDUCTOR_SERVER_URL}} # 如果连接的是需要认证的 Conductor 服务器： # export CONDUCTOR_AUTH_KEY=<YOUR_AUTH_KEY> # export CONDUCTOR_AUTH_SECRET=<YOUR_AUTH_SECRET> export CONDUCTOR_AGENT_LLM_MODEL=openai/gpt-4o-mini

几个关键环境变量的作用：

补充两点实操注意事项：

• 在 连接到 Conductor 中完成连接配置后，应确保 Conductor 服务器能调用你的模型提供方：Developer Edition 上需要把提供方添加为 AI/LLM 集成；本地服务器则需在启动前导出提供方 API Key（支持的提供方列表可参见 LLM 编排文档 中的表格）。
• 模型凭据应放在 agent worker 所在的环境变量或密钥系统里，不要写进工作流输入。

2. 把 executor 交给 Conductor：AgentRuntime.run

核心代码非常短——你不需要重写 LangChain Agent，只要把应用里已经存在的AgentExecutor原样交给AgentRuntime：

import { AgentRuntime } from "@io-orkes/conductor-javascript/agents"; // 保留你应用已经创建好的 AgentExecutor。 const executor = existingLangChainAgentExecutor; const runtime = new AgentRuntime(); try { const result = await runtime.run(executor, "Summarize the latest release."); result.printResult(); } finally { await runtime.shutdown(); }

要点拆解：

• AgentRuntime从@io-orkes/conductor-javascript/agents导入，它与 原生 Agent 快速入门 中创建new Agent({...})的对象共用同一套运行时，区别只在于这里传入的是框架对象而非 SDK 的Agent。
• runtime.run(executor, prompt)是"编译并执行一次"的快捷路径：SDK 将 LangChain 的 executor 内省为工作流图，在 Conductor 上执行，返回的结果对象提供printResult()打印最终文本。
• try/finally中调用await runtime.shutdown()，确保进程结束时优雅关闭运行时轮询，不留下悬挂资源。
• 桥接的另一层含义在 框架 Agent 参考文档 中有明确表述：SDK 是边界——LangChain 仍然是你的创作表面（authoring surface），Conductor 在其外围提供持久化执行；从第一个 run 开始，这次持久化执行就能在 UI 中看到。

3. 内省有歧义时：createAgentExecutor

runtime.run依赖 SDK 对 LangChain executor 的自动内省（introspection）来识别其模型、工具与循环结构。当自动内省产生歧义（例如 executor 结构不符合默认推断）时，指南给出的兜底方案是：在构造 executor 时改用@io-orkes/conductor-javascript/agents/langchain导出的createAgentExecutor：

import { createAgentExecutor } from "@io-orkes/conductor-javascript/agents/langchain"; // 用 createAgentExecutor 显式构造，使 SDK 能准确识别其结构， // 再交给 AgentRuntime.run(...) const executor = createAgentExecutor(/* ... */); const runtime = new AgentRuntime(); try { const result = await runtime.run(executor, "Summarize the latest release."); result.printResult(); } finally { await runtime.shutdown(); }

这相当于为 SDK 提供一个带明确类型的桥接构造器，替代对任意 executor 对象的启发式推断，从而消除歧义。这也是 LangChain 桥接专属的入口：Python SDK 侧的对应写法见 框架 Agent 快速入门 中的create_agent("openai:gpt-4o-mini", tools=[...])，两者思路一致——先用框架自己的构造 API 建好 agent，再交给 Conductor 运行时。

4. 从框架对象到工作流步骤：run / plan / deploy / serve 生命周期

指南中的run只是整个生命周期的一环。Conductor Agent 文档 Conductor Agents 给出了五个阶段，SDK 动词与代码一一对应：

1. Create：在代码中定义 Agent——可以直接用 SDK 的Agent类，也可以用 LangChain 等受支持框架的对象；
2. Plan：检查该 Agent 将被编译成的工作流图，适合开发期与 CI 中在部署前先行审视；
3. Deploy：把编译后的 Agent 注册到服务器，成为带名称和版本的 Conductor Agent，此后调用方无需再引入 LangChain 及其依赖即可调用；
4. Serve：启动执行 Agent 工具的 worker 进程（框架需要时）；serve()会阻塞，因此生产环境中它属于独立的常驻 worker 进程，而deploy()放在 CI/CD 中执行；
5. Run：执行 Agent——开发期run一步完成编译与执行；生产期由工作流通过AGENT任务按名称调用已部署版本。

Python SDK 用 LangChain 同时演示四个调用的代码可参见 框架 Agent 参考文档，TypeScript SDK 提供的语义一致（run/plan/deploy/serve）。

5. 部署后在工作流中以 AGENT 任务复用

一旦 Agent 通过deploy注册为已部署的 Conductor Agent，上层工作流就能用一个AGENT任务像调用普通步骤一样调用它。注意agentType选择的是执行模式而非创作框架：

• agentType: "a2a"（默认）：调用远程 A2A 端点；
• agentType: "conductor"：按name运行已部署的 Conductor Agent——LangChain 等框架只是 SDK 的创作路径，不是 agentType 取值。

仓库中的框架无关示例 ai/examples/31-conductor-agent-basic.json 给出了完整定义：

{ "name": "conductor_agent_basic", "version": 1, "schemaVersion": 2, "description": "Framework-agnostic Conductor Agents recipe: an AGENT task invokes the deployed 'planner' agent to completion and surfaces its text, output, and state.", "tasks": [ { "name": "run_agent", "taskReferenceName": "run_agent_ref", "type": "AGENT", "inputParameters": { "agentType": "conductor", "name": "planner", "prompt": "${workflow.input.prompt}" } } ], "outputParameters": { "text": "${run_agent_ref.output.text}", "output": "${run_agent_ref.output.output}", "state": "${run_agent_ref.output.state}" } }

AGENT任务参数说明（详见 Conductor Agents 文档）：

• name与prompt：首次调用必填；name指定已部署 Agent，prompt传入用户输入；
• version：可选，固定已部署 Agent 版本，省略则使用最新版；
• sessionId、runId、context、media、model、timeoutSeconds、idempotencyKey：按需提供；未提供幂等键时运行时自动生成重启稳定的幂等键；
• maxDurationSeconds：整次运行的时长上限，默认 86400 秒；maxPollFailures：连续瞬时轮询失败上限，默认 30；两者超限都会终结性失败任务并尽力取消子执行。

AGENT任务的输出契约包含executionId、agentName、state、text，运行完成时还有结构化output。state归一为 A2A 生命周期取值：working/input-required/completed/failed/canceled，对应到任务状态分别为IN_PROGRESS（按pollIntervalSeconds默认 5 秒再次轮询）、COMPLETED（等待人工或工具输入，输出含waiting: true与可能的pendingTool）、COMPLETED、FAILED、CANCELED。

6. 服务端要求与运行态轮询机制

在部署或调用 Conductor Agent 之前，服务器需要开启 AI 集成开关（来自 Conductor Agents 文档）：

conductor.integrations.ai.enabled=true

当该属性为 false 或缺省时，已部署 Agent 的控制面以及agentType: "conductor"执行模式不可用。

从服务端源码可以印证AGENT任务的运行态行为。在 ConductorAgentDelegate.java 中：

• 默认轮询间隔DEFAULT_POLL_SECONDS = 5，默认整次运行时长上限DEFAULT_MAX_DURATION_SECONDS = 24 * 60 * 60（即 86400 秒），默认连续轮询失败上限DEFAULT_MAX_POLL_FAILURES = 30；
• 执行逻辑是"首次调用即 start/resume，之后每次调用查询状态"的短调用模型：首次无executionId时调用startOrResume启动运行，之后通过conductorAgentClient.getAgentStatus(executionId)轮询状态；超出maxDurationSeconds仍未到达终态时，会尽力取消运行并返回终结性失败（"AGENT exceeded max duration ... without the agent reaching a terminal state"）。

这也解释了为什么 LangChain 指南中要显式调用runtime.shutdown()——本地运行是一次性 run，而服务端轮询由AGENT任务按 5 秒间隔驱动，两者配合构成了完整的持久化执行闭环。

7. 验证、恢复与生产化路径

• 验证：在 Conductor UI 中找到run创建的执行记录，核对终态、任务时间线、输入与输出；若运行无法触达模型，先确认 worker 环境中的服务器 URL 与模型提供方凭据，再检查执行记录中失败的任务后重试。
• 恢复：不要贸然重试可能已产生外部副作用（side effect）的 Agent 动作，在明确其幂等性与恢复策略之前，先结合执行历史判断。
• 生产化：沿 Conductor Agents 的 guardrails（确定性正则守卫或 LLM 守卫）与 evals（对工具选择、参数、切换、守卫事件、turn 数、终态的断言）路径补齐治理；多 Agent 并行、人工介入续跑（WAITING→HUMAN→ 用executionId恢复）等完整配方可参考仓库中的 31-conductor-agent-basic.json、32-conductor-agent-human-in-loop.json、33-conductor-agent-multi-agent.json 与 34-conductor-agent-cancel.json。

8. 关联文档与延伸阅读

• TypeScript 侧完整的 Agent 指南入口：ui-next/src/pages/agent/guides/typescript/langchain.md，以及同目录下的 openai.md、langgraph.md、native.md；
• 跨语言快速入门：Bring Your Framework Agent 与 Your First Agent；
• 概念与参考：Agent Concepts、Conductor Agents、Framework Agents、Production Agent Architecture。

一句话总结：LangChain 负责思考，Conductor 负责记忆与韧性——用AgentRuntime.run把现有 executor 跑起来，用createAgentExecutor解决内省歧义，再用deploy+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