Core API Overview

The Core API section documents the workflow.* runtime API available directly to business workflows. Its boundary is src/runtime-api.ts in the Core repository: platforms, CLI, Desktop, and Server inject these methods into globalThis.workflow, so a business workflow does not import them from "workflow-code".

Entry boundary

Entrance	Description
workflow.*	Global API used by business workflows, sourced from src/runtime-api.ts in the Core repository.
workflow-code package entry	Utility entry used by CLI, Desktop, Server, tests, and advanced hosts, sourced from src/index.ts in the Core repository.

Runtime API index

API	Description
defineWorkflow	Defines a workflow and its main execution function.
defineEntrypoint	Defines an independently runnable Workflow entrypoint, including its parameters, tools, and registry.
defineExecutor	Defines a Workflow project's entrypoints or a Conversation project's single execution configuration.
parseConversationDefaultInputArgs	Parses the serialized --message, --images, and --files values from the default conversation input.
createInputNode	Creates an input-parsing node.
createFileInputNode	Creates a file-input node and resolves a file parameter reference to a file object.
createUserInputNode	Create a human input node that can be persisted, pausing workflow to waiting_for_input.
createToolApprovalGate	Create tool approval wrappers; combine executor tools registry entries and context.toolPermissions reuse user-input to wait for/resume protocol approval tool calls.
createLLMNode	Create a non-streaming LLM call node.
createLLMStreamNode	Create a streaming LLM call node.
createLLMProviderFromEnv	Create a LLM provider from the workflow runtime environment variable.
getServerLLMCredentials	Obtain the server AI configuration available for the current logon account and create a proxy provider that does not expose the upstream key.
createLLMProviderRef	Creates a provider reference that can be deferred resolved.
createOutputNode	Creating a synchronous or streaming output node;createOutputItem, createOutputPayload, addOutputItem, and createOutputItemChunk are also described on this page.
createDetailsOutputNode	A convenient output node for creating independent, foldable output items.
createTimerNode / endTimer	Create a business timing node and write a timing card at the explicit end or workflow end.
createQuestionClassifierNode	Create a problem classification node based on LLM.
runNode	Execute the normal node and trigger the node to execute the hook.
runStreamNode	Execute the streaming node, collect chunks, and produce finalize results.
runIf	Execute the if / else-if / else branch and write the branch selection to the run report and Diagram.
runFor	Execute a traceable for loop and let Diagram display the loop body with the loop container.
runWhile	Execute the traceable while loop and let Diagram display the loop body with the loop container.
runWorkflow	Call another workflow in the current context, multiplexing KV, session, provider, token usage, and trace.
Knowledge Documents	Manage project Markdown Knowledge documents through an explicit local or server storage context.
getEnv	Reads a non-empty variable in the current runtime environment.
getRuntimePlatform / isCli / isWeb / isDesktop	Determine whether the execution host for the current workflow is CLI, Desktop, or server web.
getRuntimeLocale	Reads the Simplified Chinese or English language selected by the current host for localized visible output.
getLLMProvider	Resolves LLM provider by context, node name, and provider source.
WorkflowError	Standard workflow error type.

Core Run Object

Most API runs around input, context, node, and payload.

Object	Type	Description
input	Input or node Output	The input data for the current workflow or node.
context	WorkflowContext / NodeContext	Contains provider, storage, conversation, files, metadata, hooks, and abortSignal.
payload	WorkflowPayload subtype	Node payload should inherit WorkflowPayload, errCode: 0, errMessage: "" on success.
provider	LLMProviderSource / LLMProvider	The LLM node parses the actual provider by provider source.

NodeContext Core Fields

Field	Type	Description
providers	ProviderRegistry	LLM provider the registry and binding tables.
storage	WorkflowStorageContext	Explicit local and server locations, each with three-scope kv and persistentValue. The project dataStorage.mode strictly limits accessible locations. Core 0.2 no longer provides top-level context.kv or context.persistentValue.
conversation	WorkflowConversationContext	Session state read/write entry. setTitle can safely suggest UI title; other reads and writes will throw errors when the session is not enabled.
tokenUsage	WorkflowTokenUsageContext	Token-usage reporting context. When disabled, report() is a no-op; when enabled, it writes KV, run reports, and runtime events.
userInput	WorkflowUserInputContext | undefined	Wait/resume entry for user input and tool approval. CLI, Desktop, server runner will be injected according to the host capacity.
files	WorkflowFileStore | undefined	File reference resolution entry;createFile generates a server-backed run file.
metadata	object | undefined	Current execution meta information, such as workflow, runId, conversationId;Workflow run also contains entrypointId and entrypointTitle.
nodeHooks	NodeExecutionHooks | undefined	Node start, chunk, complete, and other event callbacks.
timers	WorkflowTimerContext | undefined	Business timing node context;createTimerNode start timing,endTimer end timing.
toolPermissions	WorkflowToolPermissionContext | undefined	The tool permission context for the current run. Parses by executor tools default and host override values for createToolApprovalGate() or custom tool call logic to determine enablement, automatic approval, and manual approval.
abortSignal	AbortSignal | undefined	Interrupt execution and provider calls.

Payload Constraint

Field	Description
errCode	Business error code. The success value is 0.
errMessage	The error description. Uniform empty string on success.