​
defineExecutor

workflow.defineExecutor<Input, Output>() 定义平台如何运行一个 workflow。App、CLI、server、Webhook 和外部 API 最终都会通过 executor 把输入参数转换为 workflow input。

​
签名

workflow.defineExecutor<Input, Output>(
  definition: WorkflowExecutorDefinition<Input, Output>,
): WorkflowExecutorDefinition<Input, Output>

​
参数

参数类型说明
definitionWorkflowExecutorDefinition<Input, Output>平台发现和执行 workflow 的入口配置。

​
WorkflowExecutorDefinition 字段

字段类型说明
workflowWorkflowDefinition<Input, Output>executor 负责运行的 workflow。必填。
createInput(context) => Input把 args、环境、会话 ID 等转成业务输入。必填。
createContext(context) => Partial<WorkflowContext>增补 providers、metadata、nodeHooks 等。KV、conversation、files 由 runtime 注入。
requiredProvidersExecutorProviderName[]声明必需 provider；当前内置名称只有 "llm"。
paramsWorkflowParamDefinition[]声明结构化参数，供 App、server web、embed 和文档使用。
toolsWorkflowToolPermissionDefinition[]声明 workflow 可调用的工具权限元数据，供 runtime、App 和 server embed 解析启用/自动批准策略。
conversationWorkflowConversationDefinition开启会话模式。
tokenUsageWorkflowTokenUsageDefinition开启 token 用量统计，并控制前端是否展示用量 badge。
registryWorkflowNodeRegistryEntry[]注册可单独调试的节点。

​
WorkflowExecutorContext

字段类型说明
workflowNamestring当前 workflow 名称。
workflowDirstring当前 workflow 目录。
argsstring[]原始 CLI 风格参数。
envNodeJS.ProcessEnv环境变量集合。
abortSignalAbortSignal中断信号；App/server 取消运行时会传递到 workflow 和支持 signal 的 SDK/provider 调用。
conversationIdstring | undefined会话 ID。
toolPermissionPoliciesWorkflowToolPermissionPolicyMap | undefined宿主传入的工具策略覆盖值。workflow 通常不直接读取该字段，而是使用 context.toolPermissions 或 workflow.createToolApprovalGate()。

​
WorkflowParamDefinition

字段类型说明
namestring参数名。必填。
flagstring长参数，例如 --message。
shortFlagstring短参数，例如 -m。
typeWorkflowParamType参数类型。必填。
requiredboolean是否必填。
descriptionstring参数说明。
defaultValuestring默认值。
multipleboolean是否允许多个值。
control"text" | "textarea" | "radio" | "select" | "checkboxes"App/server Run workspace 的表单控件提示；长文本参数可使用 textarea。
panel"main" | "auxiliary"表单展示区域；auxiliary 参数默认收进二级输入面板。
options{ value, label?, description? }[]枚举选项；有选项时表单会渲染单选、下拉或多选控件。
acceptstring[]文件类型限制。
format"json"file param 使用 JSON 引用格式。

​
WorkflowNodeRegistryEntry

字段类型说明
namestringregistry 中的调试节点名。必填。
nodeNodeDefinition | StreamNodeDefinition实际执行的节点对象。必填。
metadataWorkflowNodeMetadataInput覆盖节点展示元信息。
streamboolean标记节点是否按流式节点执行。
createInput(context) => Input单节点调试时的输入构造函数。

​
执行流程

阶段说明
平台调用 executorruntime 根据 args、env、workflowName、conversationId 创建 WorkflowExecutorContext。
createInput将 WorkflowExecutorContext 转换成 workflow 的业务输入。
createContext可选地补充 provider、metadata 和 hooks。
workflow run使用 Input 和 WorkflowContext 执行业务流程。
开启 conversation.enabled 后，workflow 代码可以调用 context.conversation.setTitle(title) 给 App 或 server embed 提供可读会话标题。该调用只建议 UI 更新标题，不提供锁定能力；标题锁定是 App/server embed 的本地交互状态。会话未开启时 setTitle 是 no-op，不会影响执行流。 如果 conversation workflow 想复用 App、server embed 和公开 embed 的共享默认输入框，可以在 conversation 下声明： 
conversation: {
  enabled: true,
  inputQueue: {
    enabled: true,
  },
  defaultInput: {
    enabled: true,
    attachments: {
      images: true,
      files: true,
    },
  },
},
defaultInput 只是宿主 UI 协议，不会自动改写 WorkflowContext。workflow 仍需在 createInput({ args }) 中显式读取固定参数名：
  • 文本：--message
  • 图片附件：--images
  • 普通文件附件：--files
推荐直接使用 runtime helper： 
createInput({ args }) {
  const defaults = workflow.parseConversationDefaultInputArgs(args);
  return {
    message: defaults.message,
    images: defaults.images,
    files: defaults.files,
  };
}
第一阶段里，--images / --files 都复用现有 file reference 协议，可以是 managed file JSON refs，也可以是本地 path。宿主负责把粘贴/拖拽/上传的 File 先转成 managed refs，再写回这些固定参数。 如果还声明了 conversation.inputQueue: { enabled: true }，App 和 server/web embed 会在当前会话运行中允许继续提交新输入。新增输入不会立刻执行，而是进入共享输入队列：
  • 队列只在 App 和 Web 宿主中生效，CLI 不使用这个能力。
  • 宿主会持久化等待中的输入；App 重启或 embed 刷新后，队列仍保留。
  • 恢复后的队列不会自动续跑，用户需要先手动发送一条新输入，后续排队项才会按顺序继续执行。
  • 当前 run 完成、失败或取消后，宿主会清理该会话的 active 运行标记；后续新输入恢复为普通发送，不会继续误入等待队列。
  • 队列项支持引导、编辑、删除和拖动排序；引导会先中断当前运行，再立即执行目标队列项。
开启 tokenUsage.enabled 后，runtime 会把 token 用量写入 KV，并把本次 run 聚合写入运行 report。聚合包含 inputTokens、outputTokens、totalTokens、reasoningTokens、cachedInputTokens、cacheCreationTokens 和 calls。display 省略时默认等于 enabled，App 和 server embed 只在 display === true 且有数据时展示 badge；badge 默认显示总量，hover/focus 展示 Input、Output、Cache 明细，其中 Cache 为 cachedInputTokens + cacheCreationTokens。

​
工具权限

tools 用于注册 workflow 业务工具的默认权限。每个工具包含稳定 name，以及可选 label、description、enabled 和 autoApprove。enabled 默认 true，autoApprove 默认 false。App 和 server embed 可以在运行前缓存用户选择并传入覆盖值；runtime 只接受已注册工具的 enabled/autoApprove 覆盖，未知工具会被忽略。 workflow 代码可以使用 workflow.createToolApprovalGate() 包装工具函数。工具未注册时会以 input_validation 失败；工具被禁用时会以 tool_permission_denied 拒绝；工具启用但未自动批准时，会复用 workflow.createUserInputNode(...) 的等待/恢复协议生成 tool-approval 请求，批准后继续同一个 run，拒绝后返回 tool_permission_denied。

​
示例

export const executor = workflow.defineExecutor<Input, Output>({
  workflow: exampleWorkflow,
  tokenUsage: {
    enabled: true,
    display: true,
  },
  tools: [
    {
      name: "search",
      label: "Search",
      description: "调用外部搜索工具。",
      enabled: true,
      autoApprove: false,
    },
  ],
  params: [
    {
      name: "message",
      flag: "--message",
      type: "string",
      required: true,
      control: "textarea",
      description: "输入文本。",
    },
    {
      name: "mode",
      flag: "--mode",
      type: "string",
      defaultValue: "live",
      control: "radio",
      panel: "auxiliary",
      options: [
        { value: "disabled", label: "Disabled" },
        { value: "live", label: "Live" },
      ],
    },
  ],
  createInput({ args }) {
    return { message: readMessage(args) };
  },
});

​
注意事项

规则说明
createInput 是必填没有它，平台不知道如何把外部输入变成 workflow input。
params 不等于实际解析逻辑params 用于 UI/结构化展示，真正转换仍由 createInput 完成。
tools 必须静态声明App/server embed 只能展示静态分析到的工具；工具名必须稳定，宿主覆盖只对注册项生效。
tokenUsage.enabled 默认关闭未配置时不会写 KV，也不会展示用量。关闭时 context.tokenUsage.report() 是 no-op。
registry 用于单节点调试没有注册的节点不能通过 debug API 单独运行。