AgentWorkflow

CORE · class · 运行时值

Executable catalog: validate references and bounded cycles before any handler runs.

Validation happens once, at construction, so traversal can assume every target exists and every cycle is budget-bounded.

导入

TypeScript

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

JavaScript

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

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

定义

class AgentWorkflow<State, Result, Runtime>

泛型参数

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

构造函数

new AgentWorkflow<State, Result, Runtime = undefined>(definition: AgentWorkflowDefinition<State, Result, Runtime>): AgentWorkflow<State, Result, Runtime>

Build and validate a workflow.

The entry node must start a round, because otherwise a workflow could loop forever without consuming the round budget. Renamed top-level fields are rejected as well.

参数	类型	传递	说明
definition	AgentWorkflowDefinition<State, Result, Runtime>	必需	—

definition 的字段

字段	类型	必需	说明
id	string	必需	只读。Stable workflow id, also reported in every event.
chainSource	WorkflowChainSource | undefined	可省略	只读。App-owned authorized diagnostic reader; no global run storage is installed.
revision	string | undefined	可省略	只读。Definition revision; lets hosts distinguish executions of different graph versions.
nodes	readonly WorkflowNode<State, Result, Runtime>[]	必需	只读。见类型定义及调用场景。
isResult	((result: Result) => boolean) | undefined	可省略	只读。Synchronous result adjudicator; returning anything other than true is a contract error.
entryNodeId	string | undefined	可省略	只读。First node to enter; defaults to the first declared node, which must start a round.

返回： AgentWorkflow<State, Result, Runtime>。

实例属性

字段	类型	必需	说明
id	string	必需	只读。Workflow id, also used in diagnostics and error messages.
entryNodeId	string	必需	只读。First node visited; always starts a round.
revision	string | undefined	可省略	只读。Optional revision passed through to diagnostics.
isResult	((result: Result) => boolean) | undefined	可省略	只读。Optional result guard; when present it must return exactly true.
definitions	readonly Readonly<WorkflowNode<State, Result, Runtime>>[]	必需	只读。Frozen snapshot of all nodes, in registration order.

成员目录

成员	用途
add	Derive an extended workflow without mutating this catalog. Every node is copied with its callbacks rebound, so the new catalog keeps the same entry and result guard and can be composed repeatedly. Route overrides are keyed by node id and must name a node that exists after the merge.
toGraph	Export topology from the registered snapshot without executing callbacks.
toChain	Read an authorized run through the bound App source, or an explicit per-call source.
require	Look up a node that must exist.
ids	完整输入输出见下方重载。
values	完整输入输出见下方重载。
entries	完整输入输出见下方重载。
has	完整输入输出见下方重载。
get	完整输入输出见下方重载。
describe	Produce a serializable description of every node and route. Used by documentation and registration listings; it reports resolved ids and which routes are terminal or conditional, never the handler implementations.

成员详情

add

实例方法。

Derive an extended workflow without mutating this catalog.

Every node is copied with its callbacks rebound, so the new catalog keeps the same entry and result guard and can be composed repeatedly. Route overrides are keyed by node id and must name a node that exists after the merge.

add(extension: WorkflowExtension<State, Result, Runtime> | AgentWorkflow<State, Result, Runtime>, routes?: WorkflowExtension<State, Result, Runtime>["routes"]): AgentWorkflow<State, Result, Runtime>

Derive an extended workflow without mutating this catalog.

Every node is copied with its callbacks rebound, so the new catalog keeps the same entry and result guard and can be composed repeatedly. Route overrides are keyed by node id and must name a node that exists after the merge.

参数	类型	传递	说明
extension	AgentWorkflow<State, Result, Runtime> | WorkflowExtension<State, Result, Runtime>	必需	—
routes	Readonly<Record<string, readonly WorkflowRoute<State, Result, Runtime>[]>> | undefined	可省略	—

参数 extension的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

AgentWorkflow<State, Result, Runtime>

分支 2

字段	类型	必需	说明
nodes	readonly WorkflowNode<State, Result, Runtime>[]	必需	只读。Nodes appended to the definition; ids must not collide with existing nodes.
routes	Readonly<Record<string, readonly WorkflowRoute<State, Result, Runtime>[]>> | undefined	可省略	只读。Replacement route lists keyed by node id; other nodes keep their declared routes.
revision	string | undefined	可省略	只读。Extension revision, recorded so mixed definitions remain auditable.

返回： AgentWorkflow<State, Result, Runtime>。

toGraph

实例方法。

Export topology from the registered snapshot without executing callbacks.

toGraph(): WorkflowGraph

Export topology from the registered snapshot without executing callbacks.

无调用参数。

返回： WorkflowGraph。

返回值结构

字段	类型	必需	说明
schemaVersion	1	必需	只读。见类型定义及调用场景。
workflowId	string	必需	只读。见类型定义及调用场景。
revision	string | undefined	可省略	只读。见类型定义及调用场景。
entryNodeId	string	必需	只读。见类型定义及调用场景。
nodes	readonly WorkflowGraphNode[]	必需	只读。见类型定义及调用场景。
edges	readonly WorkflowGraphEdge[]	必需	只读。见类型定义及调用场景。

toChain

实例方法。

Read an authorized run through the bound App source, or an explicit per-call source.

toChain(runId: string, source?: WorkflowChainSource | undefined): Promise<WorkflowChain>

Read an authorized run through the bound App source, or an explicit per-call source.

参数	类型	传递	说明
runId	string	必需	—
source	WorkflowChainSource | undefined	可省略	—

返回： Promise<WorkflowChain>。

等待后的值： WorkflowChain。

返回值结构

字段	类型	必需	说明
schemaVersion	1	必需	只读。见类型定义及调用场景。
workflowId	string	必需	只读。见类型定义及调用场景。
runId	string	必需	只读。见类型定义及调用场景。
nodes	readonly WorkflowChainNode[]	必需	只读。见类型定义及调用场景。
transitions	readonly WorkflowChainTransition[]	必需	只读。见类型定义及调用场景。
coverage	WorkflowChainCoverage	必需	只读。见类型定义及调用场景。

require

实例方法。

Look up a node that must exist.

require(id: string): WorkflowNode<State, Result, Runtime>

Look up a node that must exist.

参数	类型	传递	说明
id	string	必需	—

返回： WorkflowNode<State, Result, Runtime>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Stable node id referenced by routes and error handling.
description	string	必需	只读。Required explanation of what the node does; also used in diagnostics.
name	string | undefined	可省略	只读。Display name; defaults to id when omitted.
report	((update: void | Readonly<Partial<State>>, context: NodeReportingContext) => WorkflowNodeReport) | undefined	可省略	只读。Optional application-reported detail, collected only when content logging is enabled.
startsRound	boolean | undefined	可省略	只读。Reserves a fresh round on entry. Use it for steps that may legitimately repeat; entering such a node when the round budget is exhausted fails with the configured exhausted error.
onErrorNodeId	string | undefined	可省略	只读。Node entered when run/provides/route fails; contract errors always propagate instead.
onErrorRouteId	string | undefined	可省略	只读。Route id reported with the recovery transition.
requires	readonly (keyof State & string)[] | undefined	可省略	只读。State keys that must be present before this node runs; enforced by the engine.
provides	readonly (keyof State & string)[] | undefined	可省略	只读。State keys this node is expected to produce; validated after run.
routes	readonly WorkflowRoute<State, Result, Runtime>[]	必需	只读。Candidate successors, evaluated in order. A getter must be pure; registration reads it once.
run	((state: Readonly<State>, context: WorkflowContext<Runtime>) => void | Partial<State> | Promise<void | Partial<State>>) | undefined	可省略	只读。Return only changed fields. Core commits them after cancellation and output checks.

ids

实例方法。

ids(): readonly string[]

无调用参数。

返回： readonly string[]。

values

实例方法。

values(): MapIterator<WorkflowNode<State, Result, Runtime>>

无调用参数。

返回： MapIterator<WorkflowNode<State, Result, Runtime>>。

entries

实例方法。

entries(): MapIterator<[string, WorkflowNode<State, Result, Runtime>]>

无调用参数。

返回： MapIterator<[string, WorkflowNode<State, Result, Runtime>]>。

has

实例方法。

has(id: string): boolean

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

get

实例方法。

get(id: string): WorkflowNode<State, Result, Runtime> | undefined

参数	类型	传递	说明
id	string	必需	—

返回： WorkflowNode<State, Result, Runtime> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string	必需	只读。Stable node id referenced by routes and error handling.
description	string	必需	只读。Required explanation of what the node does; also used in diagnostics.
name	string | undefined	可省略	只读。Display name; defaults to id when omitted.
report	((update: void | Readonly<Partial<State>>, context: NodeReportingContext) => WorkflowNodeReport) | undefined	可省略	只读。Optional application-reported detail, collected only when content logging is enabled.
startsRound	boolean | undefined	可省略	只读。Reserves a fresh round on entry. Use it for steps that may legitimately repeat; entering such a node when the round budget is exhausted fails with the configured exhausted error.
onErrorNodeId	string | undefined	可省略	只读。Node entered when run/provides/route fails; contract errors always propagate instead.
onErrorRouteId	string | undefined	可省略	只读。Route id reported with the recovery transition.
requires	readonly (keyof State & string)[] | undefined	可省略	只读。State keys that must be present before this node runs; enforced by the engine.
provides	readonly (keyof State & string)[] | undefined	可省略	只读。State keys this node is expected to produce; validated after run.
routes	readonly WorkflowRoute<State, Result, Runtime>[]	必需	只读。Candidate successors, evaluated in order. A getter must be pure; registration reads it once.
run	((state: Readonly<State>, context: WorkflowContext<Runtime>) => void | Partial<State> | Promise<void | Partial<State>>) | undefined	可省略	只读。Return only changed fields. Core commits them after cancellation and output checks.

describe

实例方法。

Produce a serializable description of every node and route.

Used by documentation and registration listings; it reports resolved ids and which routes are terminal or conditional, never the handler implementations.

describe(): { startsRound: boolean; onErrorNodeId: string | undefined; requires: readonly (keyof State & string)[]; provides: readonly (keyof State & string)[]; routes: { targetNodeId: string | undefined; terminal: boolean; conditional: boolean; conditionId?: string | undefined; description?: string | undefined; id?: string | undefined; }[]; name?: string | undefined; id: string; description: string; }[]

Produce a serializable description of every node and route.

Used by documentation and registration listings; it reports resolved ids and which routes are terminal or conditional, never the handler implementations.

无调用参数。

返回： { startsRound: boolean; onErrorNodeId: string \| undefined; requires: readonly (keyof State & string)[]; provides: readonly (keyof State & string)[]; routes: { targetNodeId: string \| undefined; terminal: boolean; conditional: boolean; conditionId?: string \| undefined; description?: string \| undefined; id?: string \| undefined; }[]; name?: string \| undefined; id: string; description: string; }[]。

使用示例

• Workflow：节点、路由与局部状态更新：用一份真实参与运行的节点定义，集中展示执行顺序、分支、错误去向和结束条件。
• 复用基础 Workflow 与 Agent 分支：add 保留旧 Workflow，生成组合后的新 Workflow；fork 继承已有绑定及分支来源。

一个节点完成问候

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

同一节点合同可由类实现

扩展 · Node.js

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
class GreetingNode {
  readonly id = 'greet';
  readonly description = '根据姓名生成问候';
  readonly startsRound = true;
  readonly routes = [route.deliver('answer')];
  #prefix = '你好，';
  run(state: Readonly<State>) { return { answer: this.#prefix + state.name }; }
}
const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: [new GreetingNode()] });
console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
class GreetingNode {
    id = 'greet';
    description = '根据姓名生成问候';
    startsRound = true;
    routes = [route.deliver('answer')];
    #prefix = '你好，';
    run(state) { return { answer: this.#prefix + state.name }; }
}
const workflow = defineWorkflow({ id: 'greeting', nodes: [new GreetingNode()] });
console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));

相关策略源码

• 有界循环、提交与取消的执行实现
• 引用、可达性和有界循环校验

相关定义

• AgentWorkflowDefinition
• WorkflowChain
• WorkflowChainSource
• WorkflowExtension
• WorkflowGraph
• WorkflowNode