​
runWorkflow

workflow.runWorkflow() 用于在一个 workflow 内调用另一个已 import 的 WorkflowDefinition<Input, Output>。它复用父级 WorkflowContext，适合把通用 workflow 当作另一个 workflow 的方法来组合。

​
签名

workflow.runWorkflow<Input, Output>(
  workflow: WorkflowDefinition<Input, Output>,
  input: Input,
  context: WorkflowContext,
  options?: {
    name?: string;
    metadata?: Partial<WorkflowNodeMetadata>;
    conversationMode?: "shared" | "shared-readonly";
    kvMode?: "shared" | "isolated";
    outputVisibility?: "visible" | "hidden";
    emitNode?: boolean;
    maxDepth?: number;
    onOutputChunk?: (chunk: unknown, event: NodeExecutionHookChunkEvent) => void | Promise<void>;
    onOutput?: (output: Output, event?: NodeExecutionHookFinishEvent) => void | Promise<void>;
  },
): Promise<Output>

​
参数

参数类型说明
workflowWorkflowDefinition<Input, Output>要复用的子 workflow。
inputInput传给子 workflow 的输入。
contextWorkflowContext父 workflow 当前上下文。
options.namestring父 trace 中显示的子 workflow 调用标题。
options.metadataPartial<WorkflowNodeMetadata>覆盖 trace 节点元信息，默认 type 为 workflow。
options.conversationMode"shared" | "shared-readonly"子 workflow 如何使用父会话。默认 shared。
options.kvMode"shared" | "isolated"子 workflow 如何使用父 KV。默认 shared；isolated 会给 workflow/conversation KV key 加子 workflow 前缀。
options.outputVisibility"visible" | "hidden"子 workflow output 是否进入父级可见 outputs。默认 visible。
options.emitNodeboolean是否在父 trace 中增加 run-workflow 包裹节点。默认 true；顶层 executor 入口不走该插桩路径。
options.maxDepthnumber嵌套 runWorkflow 最大深度。默认 16，用于防止递归或环路调用。
options.onOutputChunk(chunk, event) => void接收子 workflow output stream chunks，可在父级 output node 中原样转发。
options.onOutput(output, event?) => void接收子 workflow 非流式 output；如果子 workflow 没有 output node，则接收它的最终返回值。

​
上下文复用

子 workflow 默认使用同一个 kv、conversation、tokenUsage、files、providers、abortSignal 和 nodeHooks。它不会创建独立 run report；runWorkflow 调用本身和子节点事件都会进入父 workflow trace。普通顶层执行入口 safeRunWorkflow 直接调用 workflow.run(input, context)，不会额外生成 run-workflow 包裹节点，因此静态结构和运行时 report 不会在根部多出一个合成节点。 conversationMode: "shared-readonly" 会让子 workflow 读取父会话快照，但 appendMessage、setValue 和 setTitle 不会写回父会话。推荐由父 workflow 统一追加 user/assistant transcript 和设置标题，避免父子 workflow 重复写入消息。 conversationMode 只控制 context.conversation。如果子 workflow 会写自己的 context.kv.workflow 或 context.kv.conversation 状态，推荐同时传入 kvMode: "isolated"，让子 workflow 的 KV key 写到以子 workflow 名称为前缀的隔离命名空间；context.kv global scope 仍然共享。

​
追踪与输出

runtime 默认会在父 trace 中增加一个 run-workflow 包裹节点，name / metadata 只用于覆盖这个节点的展示标题和元信息。完成事件的 executionInfo 包含： 
{
  "workflowName": "openai-agents",
  "conversationMode": "shared-readonly",
  "kvMode": "isolated",
  "outputVisibility": "hidden",
  "outputBridge": true
}
默认 runWorkflow(child, input, context) 和 runWorkflow(child, input, context, { name }) 都保持 conversationMode: "shared" 与 outputVisibility: "visible"。只给 trace 增加显示名不会改变会话写入或输出可见性。需要父级统一管理会话和输出时，应显式传入 conversationMode: "shared-readonly" 和 outputVisibility: "hidden"。 当父 workflow 想“原封不动展示被调用 workflow”的输出时，把 runWorkflow 放在父级 output node 的 stream 中，并传入 onOutputChunk / onOutput： 子 workflow 支持流式输出时，onOutputChunk 会在子 output node 每次产生 chunk 时同步触发；子 workflow 只有非流式 output node 时，onOutput 会在 output 完成后触发；如果子 workflow 没有 output node 但直接返回 payload，onOutput 会在子 workflow 返回后收到该返回值。 onOutputChunk / onOutput 属于执行语义的一部分。如果 handler 抛错，runWorkflow 会尽早失败并停止继续桥接后续 output；错误 metadata 中会带 outputBridgeFailed: true。 静态结构分析会把 workflow.runWorkflow(childWorkflow, input, context, options) 识别为 run-workflow 执行节点。动态拼装 workflow 引用仍可运行，但 Diagram 只能显示表达式形式的子 workflow 引用。

​
示例

import { openaiAgentsWorkflow } from "../openai-agents/index";

const agentOutput = await workflow.runWorkflow(
  openaiAgentsWorkflow,
  {
    message: input.query,
    defaultTools: false,
    memoryTools: false,
    testTool: false,
    writeConversation: false,
    writeAgentState: false,
    customTools: deltaforceTools,
  },
  context,
  {
    name: "OpenAI Agents core",
    conversationMode: "shared-readonly",
    kvMode: "isolated",
    outputVisibility: "hidden",
  },
);

return workflow.runNode(parentOutputNode, {
  query: input.query,
  answer: agentOutput.items[0]?.content,
}, context);
流式桥接示例： 
const outputNode = workflow.createOutputNode({
  name: "output",
  async *stream(input, context) {
    // createAsyncQueue 是示意 helper，需要在 workflow 中自行实现，
    // 或替换成项目已有的 async iterable/queue 工具。
    const queue = createAsyncQueue();

    const childRun = workflow.runWorkflow(childWorkflow, input, context, {
      conversationMode: "shared-readonly",
      kvMode: "isolated",
      outputVisibility: "hidden",
      onOutputChunk(chunk) {
        queue.push(chunk);
      },
      onOutput(output) {
        queue.push(output);
      },
    }).finally(() => queue.end());

    yield* queue;
    await childRun;
  },
  format(stream) {
    return workflow.createOutputPayload({ items: stream.items });
  },
});

​
错误

情况错误类型说明
子 workflow 抛错workflow_execution原错误会被包装，并在 metadata 中保留子 workflow 名称。
执行前已中断execution_aborted来自父级 context.abortSignal。
嵌套过深workflow_execution超过 maxDepth 时中止，避免递归或环路调用导致栈溢出。
输出桥接 handler 抛错stream_interrupted 或 workflow_executionmetadata.outputBridgeFailed 为 true，cause 中保留 handler 错误。