WorkflowContext

CORE · interface · 类型合同

Execution facts available to every node of a running workflow.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core、@jangts/agent-core/engine、@jangts/agent-core/types、@jangts/agent-core/structs。

定义

interface WorkflowContext<Runtime>

继承或实现： OperationContext<Runtime>、NodeReportingContext、CacheContext。

泛型参数

类型参数	约束	默认类型
Runtime	—	undefined

字段结构

字段	类型	必需	说明
roundIndex	number	必需	只读。Zero-based bounded round; phases within a round do not consume another round.
report	(update: WorkflowNodeReport) => void	必需	Report progress while this node is active; Core supplies its execution identity.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of this node visit, when recording is enabled.
model	WorkflowModel	必需	只读。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>>; }	必需	只读。见类型定义及调用场景。
error	unknown	可省略	只读。Failure that led into this node, present only while entering an onErrorNodeId target.
errorEventId	string | undefined	可省略	只读。Event id of that failure, for correlation in host logs.
app	unknown extends Runtime ? Runtime : Readonly<Runtime>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
createSubFlowLogger	() => SubFlowLogger	必需	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.
cache	NodeCache	必需	只读。见类型定义及调用场景。
agentCache	NodeAgentCache | undefined	可省略	只读。见类型定义及调用场景。

成员目录

成员	用途
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.

成员详情

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.

参数	类型	传递	说明
update	WorkflowNodeReport	必需	—

update 的字段

字段	类型	必需	说明
usedModel	boolean | undefined	可省略	只读。This visit's own use only; omitted means unknown.
payload	unknown	可省略	只读。App-defined progress detail; collected only when content logging is enabled.

返回： 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.

无调用参数。

返回： SubFlowLogger。

使用示例

• Workflow：节点、路由与局部状态更新：用一份真实参与运行的节点定义，集中展示执行顺序、分支、错误去向和结束条件。

一个节点完成问候

入门 · 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());

增加校验阶段，原状态与 run 方式不变

配置 · 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' }));

相关策略源码

• 引用、可达性和有界循环校验

相关定义

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