WorkflowContext

CORE · interface · Type contract

Execution facts available to every node of a running workflow.

Import

TypeScript

import type { WorkflowContext } from '@jangts/agent-core/engine';

JavaScript

/** @typedef {import('@jangts/agent-core/engine').WorkflowContext} WorkflowContext */

Other public entry points:@jangts/agent-core, @jangts/agent-core/engine, @jangts/agent-core/types, @jangts/agent-core/structs.

Definition

interface WorkflowContext<Runtime>

Extends or implements: OperationContext<Runtime>, NodeReportingContext, CacheContext.

Type parameters

Type parameter	Constraint	Default type
Runtime	—	undefined

Field structure

Field	Type	Required	Description
roundIndex	number	Required	Read-only. Zero-based bounded round; phases within a round do not consume another round.
report	(update: WorkflowNodeReport) => void	Required	Report progress while this node is active; Core supplies its execution identity.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of this node visit, when recording is enabled.
model	WorkflowModel	Required	Read-only. Model access limited by the workflow's configured calls and budget.
tools	{ invoke(request: Omit<import("../capabilities/tools.js").ToolInvocationRequest, "diagnostics">): Promise<import("../invocation.js").ToolResult<unknown>>; }	Required	Read-only. See the type definition and usage context.
error	unknown	Optional	Read-only. Failure that led into this node, present only while entering an onErrorNodeId target.
errorEventId	string | undefined	Optional	Read-only. Event id of that failure, for correlation in host logs.
app	unknown extends Runtime ? Runtime : Readonly<Runtime>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
createSubFlowLogger	() => SubFlowLogger	Required	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.
cache	NodeCache	Required	Read-only. See the type definition and usage context.
agentCache	NodeAgentCache | undefined	Optional	Read-only. See the type definition and usage context.

Member index

Member	Purpose
report	Report progress while this node is active; Core supplies its execution identity.
createSubFlowLogger	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

Member details

report

Report progress while this node is active; Core supplies its execution identity.

WorkflowContext.report(update: WorkflowNodeReport): void

Report progress while this node is active; Core supplies its execution identity.

Parameter	Type	Passing	Description
update	WorkflowNodeReport	Required	—

Fields of update

Field	Type	Required	Description
usedModel	boolean | undefined	Optional	Read-only. This visit's own use only; omitted means unknown.
payload	unknown	Optional	Read-only. App-defined progress detail; collected only when content logging is enabled.

Returns: void.

createSubFlowLogger

Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

WorkflowContext.createSubFlowLogger(): SubFlowLogger

Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

No call parameters.

Returns: SubFlowLogger.

Examples

• Workflow: nodes, routes, and partial state updates: Use a single node definition that actually participates in execution to show order, branches, error destinations, and end conditions together.

A single node completes the greeting

Beginner · Node.js

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';

type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({
  id: 'greeting',
  nodes: [{
    id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
    run: state => ({ answer: '你好，' + state.name }),
    routes: [route.deliver('answer')],
  }],
});
console.log(workflow.entryNodeId);
console.log(workflow.describe());

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
    id: 'greeting',
    nodes: [{
            id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
            run: state => ({ answer: '你好，' + state.name }),
            routes: [route.deliver('answer')],
        }],
});
console.log(workflow.entryNodeId);
console.log(workflow.describe());

Add a validation stage without changing state or the run call

Configuration · Node.js

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string; error?: string };
const workflow = defineWorkflow<State, string>({
  id: 'greeting',
  nodes: [
    { id: 'check', description: '检查姓名', startsRound: true,
      run: state => ({ error: state.name.trim() ? undefined : '姓名不能为空' }),
      routes: [route.toIfError('failure'), route.to('greet')] },
    { id: 'greet', description: '生成问候', provides: ['answer'],
      run: state => ({ answer: '你好，' + state.name }), routes: [route.deliver('answer')] },
    { id: 'failure', description: '返回校验提示', requires: ['error'], routes: [route.deliver('error')] },
  ],
});
console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
    id: 'greeting',
    nodes: [
        { id: 'check', description: '检查姓名', startsRound: true,
            run: state => ({ error: state.name.trim() ? undefined : '姓名不能为空' }),
            routes: [route.toIfError('failure'), route.to('greet')] },
        { id: 'greet', description: '生成问候', provides: ['answer'],
            run: state => ({ answer: '你好，' + state.name }), routes: [route.deliver('answer')] },
        { id: 'failure', description: '返回校验提示', requires: ['error'], routes: [route.deliver('error')] },
    ],
});
console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));

Related policy source

• Reference, reachability, and bounded-loop validation

Related definitions

• CacheContext
• DiagnosticContext
• NodeAgentCache
• NodeCache
• NodeReportingContext
• OperationContext
• SubFlowLog
• SubFlowLogger
• WorkflowModel
• WorkflowNodeReport