在 TypeScript 中使用 OpenAI Agents SDK 运行 Conductor 持久化 Agent 实战指南-开发者社区

在 TypeScript 中使用 OpenAI Agents SDK 运行 Conductor 持久化 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

导读

本文面向 TypeScript / JavaScript 开发者，讲解如何将基于 OpenAI Agents SDK 编写的 Agent 接入 Conductor 的持久化执行引擎：你只需引入@io-orkes/conductor-javascript包中的AgentRuntime，替换运行入口，即可让原本无状态的框架 Agent 获得"编译为工作流图、逐步落盘、可恢复、可审计"的持久化执行能力。读完本文，你将掌握环境变量配置、Agent 定义与运行、执行结果在 Conductor UI 中的验证方法，以及框架 Agent 从开发调试到部署复用的完整路径。

1. 背景：为什么要把框架 Agent 交给 Conductor

Conductor 是一个事件驱动的 agentic 工作流引擎，为应用和 AI Agent 提供持久化、高弹性的执行环境。在 Conductor 的视角里，Agent 在底层就是一条工作流：Agent 定义（模型、指令、工具）会被编译成工作流图，每次模型调用是一个任务、每次工具调用是一个任务、它们之间的循环是工作流控制流。因此，工作流天然具备的重试、超时、人工审批、执行历史回放等能力，都会自动作用于 Agent 的每一次运行。

ui-next/src/pages/agent/guides/typescript/openai.md这篇指南演示的正是框架 Agent 路线中的 OpenAI Agents SDK 场景：保留你已用 OpenAI Agents SDK 写好的 Agent 对象，由 Conductor SDK 将其编译并执行为一条持久化的 Conductor 执行记录，而不是把 Agent 逻辑塞进一个常驻进程。相关的完整背景可参考 Agent Concepts 与 Framework Agents。

2. 安装与配置

2.1 安装依赖

npm install @io-orkes/conductor-javascript @openai/agents

@openai/agents：OpenAI 官方 Agents SDK，负责定义 Agent 本身（模型、指令、工具、循环）。
@io-orkes/conductor-javascript/agents：Conductor 官方 TypeScript / JavaScript SDK，提供AgentRuntime等与持久化执行相关的运行入口。安装与首个 Agent 的通用步骤可对照 Your First Agent 的 TypeScript 小节。

2.2 配置连接变量与模型

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_SERVER_URL`	Conductor 服务端地址	使用 Orkes Developer Edition 时设为`https://developer.orkescloud.com/api`；使用本地服务端时设为`http://localhost:8080/api`。详细连接步骤见 Connect to Conductor
`CONDUCTOR_AUTH_KEY`/`CONDUCTOR_AUTH_SECRET`	服务端访问凭证	仅当服务端启用认证时需要，可从 Developer Edition 的应用访问密钥获取
`CONDUCTOR_AGENT_LLM_MODEL`	Agent 默认模型映射	采用`provider/model`的命名格式，`openai/gpt-4o-mini`即指定 OpenAI 提供方下的 gpt-4o-mini 模型

关于模型提供方：若使用本地服务端，需要在启动服务端前导出模型提供方的 API Key（例如export OPENAI_API_KEY=<your-openai-api-key>），使服务端继承该凭据；若使用 Developer Edition，则在控制台的 AI/LLM 集成中配置提供方。模型提供方支持的完整列表可参考 LLM Orchestration。在服务端侧，模型定义经由ai模块的AIModelProvider体系解析（对应源码目录 ai/src/main/java/org/conductoross/conductor/ai/providers，其中openai子包内含OpenAI.java、OpenAIConfiguration.java等提供方实现）。

3. 编写并运行 Agent

3.1 定义 Agent 并交给 AgentRuntime 执行

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

import { Agent, setTracingDisabled } from "@openai/agents"; import { AgentRuntime } from "@io-orkes/conductor-javascript/agents"; setTracingDisabled(true); const agent = new Agent({ name: "openai_greeter", model: "gpt-4o-mini", instructions: "You are friendly and concise.", }); const runtime = new AgentRuntime(); try { const result = await runtime.run(agent, "Share a durable execution fact."); result.printResult(); } finally { await runtime.shutdown(); }

逐段拆解这段代码的关键点：

setTracingDisabled(true)：关闭 OpenAI Agents SDK 自带的追踪上报，避免与 Conductor 的执行记录体系重复或冲突。
new Agent({...})：完全使用 OpenAI Agents SDK 的 Agent 构造方式定义名称、模型与指令，没有引入任何 Conductor 专有的 Agent 类型。
new AgentRuntime()：Conductor SDK 提供的运行器，是框架 Agent 与 Conductor 之间的桥接边界。
runtime.run(agent, prompt)：将框架 Agent 编译为工作流图并在 Conductor 上执行，返回一次持久化的执行结果。
runtime.shutdown()：置于finally中确保运行器资源被释放。

3.2 运行

npx tsx openai-agent.ts

tsx让 Node.js 直接运行 TypeScript 文件，无需预先编译。运行时，Conductor SDK 会把openai_greeter编译成工作流图并逐任务执行——每次 LLM 调用、每次工具调用都会成为图中一个独立任务并持久化记录。

4. 验证执行与故障排查

执行结束后，在 Conductor UI 中定位本次运行产生的执行记录：

确认其最终状态（终端状态为成功还是失败）；
检查任务时间线（task timeline）、输入与输出；
若运行无法触达模型，优先确认 worker 环境中的服务端地址与模型提供方凭据，再检查失败任务后重试。

持久化执行的意义在于：一次 Agent 运行就是一次工作流执行，每一步都被落盘保存，进程崩溃或重启后可从最后一个已完成步骤继续，而不是从头再来。这正是 Conductor "durable execution" 的核心价值，相关概念详见 Agent Concepts 中的 "Agents are workflows underneath" 一节。

5. 从单次运行到可复用部署：框架 Agent 的完整生命周期

openai-agent.ts演示的是"运行一次"的开发路径。当一个框架 Agent 趋于稳定后，还有一条从开发到部署的完整路径，在 Framework Agents 中被归纳为四个阶段：

运行（develop）：把框架 Agent 对象交给 Conductor SDK 执行，从第一次运行起即可在 UI 中看到持久化执行；
部署（release）：将编译后的 Agent 在服务端注册为命名且带版本的 Conductor Agent，此后调用方无需引入 OpenAI Agents SDK 即可调用它；
服务（operate）：Agent 的工具如果以本地函数运行，需要保持一个 worker 进程常驻来执行工具；
编排（invoke）：父工作流通过AGENT任务调用已部署的 Agent，如同调用其他持久化步骤。

父工作流中调用已部署 Agent 的任务定义形如：

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

对于仅需在现有工作流里"借"一个 Agent 完成某一步的场景，也可以在 Your First Agent 中看到不预先部署、直接用AGENT任务内联调用的写法。生产环境下的治理、评估、部署与运维考量，可继续阅读 Production Agent Architecture。

6. 源码视角：框架 Agent 是如何被"翻译"成持久化工作流的

从仓库源码可以看到，这套能力并非黑盒：

Agent 编译：agentspan模块的 compiler 目录下存在AgentCompiler、ToolCompiler、GateCompiler、GuardrailCompiler、HumanTaskBuilder、MultiAgentCompiler等编译单元，负责把不同框架形态的 Agent 定义归一化为 Conductor 工作流图；normalizer目录（如OpenAINormalizer、ClaudeAgentSdkNormalizer、LangChainNormalizer等）则负责将各框架特有的 Agent 配置标准化。
执行与编排：agentspan模块的 service 目录下的AgentDagService、AgentService、AgentEventListener等承担 Agent 的 DAG 构建、生命周期监听与运行服务。
LLM 任务输入：每次模型调用最终落到 LLM 任务，任务输入模型 LLMWorkerInput.java 中定义了llmProvider、integrationName、model、temperature、maxTokens（默认 8192）等参数，并支持按 provider 自动补充AI_MODEL集成名——这解释了为何环境变量中CONDUCTOR_AGENT_LLM_MODEL使用openai/gpt-4o-mini这类provider/model格式，SDK 会将模型请求路由到对应提供方（如 openai providers 目录中的OpenAIResponsesChatModel、OpenAICompatChatModel等模型实现）。