AgentCoreEngine

CORE · class · 运行时值

Bounded execution shared by applications; business rules are registered by each host.

Configuration is bound before a run and may be bound only once per model, tool runtime and workflow. A run resolves its signal from the engine, the request runtime and the caller, then executes either the bound workflow or a supplied step function until the round budget, cancellation or a completion stops it.

导入

TypeScriptJavaScript

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

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

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

定义

class AgentCoreEngine<Result, State, App>

泛型参数

类型参数	约束	默认类型
`Result`	—	—
`State`	—	`unknown`
`App`	—	`undefined`

构造函数

new AgentCoreEngine<Result, State = unknown, App = undefined>(settings?: AgentCoreEngineSetup<State, Result, App>): AgentCoreEngine<Result, State, App>

Build an engine and validate its wiring.

Legacy top-level names (maxSteps, exhausted, signal, diagnostics, onWorkflowEvent, observe) are rejected rather than ignored, because silently dropping them would change budgets or observation.

参数	类型	传递	说明
`settings`	`AgentCoreEngineSetup<State, Result, App>`	可省略	—

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

分支 1

字段	类型	必需	说明
`cache`	`EngineCacheOptions \| undefined`	可省略	Engine-local LRU bounds; not copied as cache data when forking.
`agentCache`	`AgentCachePort \| undefined`	可省略	Borrowed App service cache; forks must explicitly provide their own port.
`maxRounds`	`number \| undefined`	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
`execution`	`ExecutionOptions \| undefined`	可省略	Cancellation and diagnostics shared by every round.
`errors`	`{ exhausted?: () => Error; } \| undefined`	可省略	Builds the error thrown when the round budget is exhausted (defaults to a `BudgetError`).
`branch`	`AgentBranch \| undefined`	可省略	只读。见类型定义及调用场景。
`tools`	`ToolBinding \| undefined`	可省略	只读。见类型定义及调用场景。
`model`	`AgentModelBinding \| undefined`	可省略	见类型定义及调用场景。
`models`	`undefined`	可省略	见类型定义及调用场景。
`workflow`	`undefined`	可省略	见类型定义及调用场景。
`app`	`undefined`	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
`cache`	`EngineCacheOptions \| undefined`	可省略	Engine-local LRU bounds; not copied as cache data when forking.
`agentCache`	`AgentCachePort \| undefined`	可省略	Borrowed App service cache; forks must explicitly provide their own port.
`maxRounds`	`number \| undefined`	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
`execution`	`ExecutionOptions \| undefined`	可省略	Cancellation and diagnostics shared by every round.
`errors`	`{ exhausted?: () => Error; } \| undefined`	可省略	Builds the error thrown when the round budget is exhausted (defaults to a `BudgetError`).
`branch`	`AgentBranch \| undefined`	可省略	只读。见类型定义及调用场景。
`tools`	`ToolBinding \| undefined`	可省略	只读。见类型定义及调用场景。
`model`	`string \| undefined`	可省略	见类型定义及调用场景。
`models`	`Readonly<Record<string, AgentModelBinding>>`	必需	见类型定义及调用场景。
`maxModelCalls`	`number \| undefined`	可省略	见类型定义及调用场景。
`workflow`	`undefined`	可省略	见类型定义及调用场景。
`app`	`undefined`	可省略	见类型定义及调用场景。

分支 3

字段	类型	必需	说明
`cache`	`EngineCacheOptions \| undefined`	可省略	Engine-local LRU bounds; not copied as cache data when forking.
`agentCache`	`AgentCachePort \| undefined`	可省略	Borrowed App service cache; forks must explicitly provide their own port.
`maxRounds`	`number \| undefined`	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
`execution`	`ExecutionOptions \| undefined`	可省略	Cancellation and diagnostics shared by every round.
`errors`	`{ exhausted?: () => Error; } \| undefined`	可省略	Builds the error thrown when the round budget is exhausted (defaults to a `BudgetError`).
`branch`	`AgentBranch \| undefined`	可省略	只读。见类型定义及调用场景。
`tools`	`ToolBinding \| undefined`	可省略	只读。见类型定义及调用场景。
`model`	`AgentModelBinding \| undefined`	可省略	见类型定义及调用场景。
`models`	`undefined`	可省略	见类型定义及调用场景。
`workflow`	`AgentWorkflow<State, Result, App>`	必需	只读。见类型定义及调用场景。
`app`	`App \| undefined`	可省略	只读。见类型定义及调用场景。

类型条件： AgentCoreEngineOptions & { readonly branch?: AgentBranch; readonly tools?: ToolBinding; } & { model?: AgentModelBinding; models?: never; } & { readonly workflow: AgentWorkflow<State, Result, App>; } & ([App] extends [undefined] ? { readonly app?: undefined; } : { readonly app: App; })

分支 4

字段	类型	必需	说明
`cache`	`EngineCacheOptions \| undefined`	可省略	Engine-local LRU bounds; not copied as cache data when forking.
`agentCache`	`AgentCachePort \| undefined`	可省略	Borrowed App service cache; forks must explicitly provide their own port.
`maxRounds`	`number \| undefined`	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
`execution`	`ExecutionOptions \| undefined`	可省略	Cancellation and diagnostics shared by every round.
`errors`	`{ exhausted?: () => Error; } \| undefined`	可省略	Builds the error thrown when the round budget is exhausted (defaults to a `BudgetError`).
`branch`	`AgentBranch \| undefined`	可省略	只读。见类型定义及调用场景。
`tools`	`ToolBinding \| undefined`	可省略	只读。见类型定义及调用场景。
`model`	`string \| undefined`	可省略	见类型定义及调用场景。
`models`	`Readonly<Record<string, AgentModelBinding>>`	必需	见类型定义及调用场景。
`maxModelCalls`	`number \| undefined`	可省略	见类型定义及调用场景。
`workflow`	`AgentWorkflow<State, Result, App>`	必需	只读。见类型定义及调用场景。
`app`	`App \| undefined`	可省略	只读。见类型定义及调用场景。

类型条件： AgentCoreEngineOptions & { readonly branch?: AgentBranch; readonly tools?: ToolBinding; } & { model?: string; models: Readonly<Record<string, AgentModelBinding>>; maxModelCalls?: number; } & { readonly workflow: AgentWorkflow<State, Result, App>; } & ([App] extends [undefined] ? { readonly app?: undefined; } : { readonly app: App; })

返回： AgentCoreEngine<Result, State, App>。

实例属性

字段	类型	必需	说明
`workflow`	`AgentWorkflow<State, Result, App>`	必需	只读。The bound workflow.
`branch`	`AgentBranch`	必需	只读。Identity of this engine's branch.

成员目录

成员	用途
`Workflow`	静态。Workflow catalog constructor, exposed so hosts do not import two modules.
`AttemptBudget`	静态。Attempt budget, exposed for hosts that gate their own sub-steps.
`createWorkflow`	静态。Factory for a validated workflow definition.
`bindModel`	Bind the single model this engine will use.
`bindModelRuntime`	Bind an existing request lifetime once, for App services sharing this Runner's budget. Callbacks are bound to the source runtime and the counters stay live getters, so the engine and the App observe exactly the same budget and signal.
`switchModel`	Select a configured model, or replace the single bound model's configuration.
`bindToolRuntime`	Bind the tool runtime used by workflow context.
`bindWorkflow`	Bind a workflow, narrowing the engine's state and App types. Binding changes the engine's type parameters without changing its identity, so the same instance keeps its model, tools and branch. Bind a workflow together with its App dependencies.
`checkpoint`	Take an in-memory checkpoint of host-owned data. The data is cloned on write and on every read, so neither side can mutate the other.
`exportCheckpoint`	Export a checkpoint for host-owned persistence.
`restoreCheckpoint`	Recreate a checkpoint from a persisted record. The record's branch must match this engine's branch exactly; otherwise persisted data from another branch would be adopted silently.
`fork`	Create an engine on a new branch forked at a checkpoint. The forked engine keeps the round budget, observation and configuration, receives an optional workflow extension, and gets a new branch identity whose parent ids point at this engine. Live handles are not copied: an App dependency, request runtime or tool runtime must be restored by the `resume` callback, because they cannot be serialized.
`run`	Run the loop with a step function when no workflow is bound. Run a bound workflow from an initial state.

成员详情

`Workflow`

静态成员。

Workflow catalog constructor, exposed so hosts do not import two modules.

new AgentCoreEngine.Workflow<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>。

`AttemptBudget`

静态成员。

Attempt budget, exposed for hosts that gate their own sub-steps.

new AgentCoreEngine.AttemptBudget(limit: number): AttemptBudget

参数	类型	传递	说明
`limit`	`number`	必需	—

返回： AttemptBudget。

`createWorkflow`

静态成员。

Factory for a validated workflow definition.

AgentCoreEngine.createWorkflow<State, Result, Runtime = undefined>(definition: AgentWorkflowDefinition<State, Result, Runtime>): AgentWorkflow<State, Result, Runtime>

Build a validated workflow from a definition.

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

参数	类型	传递	说明
`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>。

`bindModel`

实例方法。

Bind the single model this engine will use.

bindModel(options: AgentModelBinding): AgentCoreEngine<Result, State, App>

Bind the single model this engine will use.

参数	类型	传递	说明
`options`	`AgentModelBinding`	必需	—

options 的字段

字段	类型	必需	说明
`provider`	`ChatProvider`	必需	见类型定义及调用场景。
`execution`	`undefined`	可省略	见类型定义及调用场景。
`transports`	`readonly ModelTransportDefinition<unknown>[] \| undefined`	可省略	见类型定义及调用场景。
`sink`	`{ output?: ModelRunnerPorts["onOutput"]; } \| undefined`	可省略	见类型定义及调用场景。
`errors`	`{ inputBudget?: ModelRunnerPorts["inputBudgetError"]; outputBudget?: ModelRunnerPorts["outputBudgetError"]; } \| undefined`	可省略	见类型定义及调用场景。
`children`	`ModelChildPolicy \| undefined`	可省略	只读。见类型定义及调用场景。
`maxInputChars`	`number \| undefined`	可省略	Character budget for the assembled input.
`maxSchemaChars`	`number \| undefined`	可省略	Character allowance for registered capability schemas.
`tokenBudget`	`ModelTokenBudget \| undefined`	可省略	见类型定义及调用场景。
`maxOutputTokens`	`number \| undefined`	可省略	Default output reservation; invoke can override it for one call.
`maxCalls`	`number \| undefined`	可省略	Calls allowed for the whole request, including descendant runners' reservations.
`callTimeoutMs`	`number \| undefined`	可省略	Deadline for one provider call, in milliseconds.
`maxOutputChars`	`number \| undefined`	可省略	Cap on streamed output characters; exceeding it fails the call.
`usage`	`boolean \| undefined`	可省略	Request and record provider usage for each call.
`signal`	`undefined`	可省略	见类型定义及调用场景。

返回： AgentCoreEngine<Result, State, App>。

`bindModelRuntime`

实例方法。

Bind an existing request lifetime once, for App services sharing this Runner's budget.

Callbacks are bound to the source runtime and the counters stay live getters, so the engine and the App observe exactly the same budget and signal.

bindModelRuntime(source: AgentModelRuntime): AgentCoreEngine<Result, State, App>

Bind an existing request lifetime once, for App services sharing this Runner's budget.

Callbacks are bound to the source runtime and the counters stay live getters, so the engine and the App observe exactly the same budget and signal.

参数	类型	传递	说明
`source`	`AgentModelRuntime`	必需	—

source 的字段

字段	类型	必需	说明
`invoke`	{ (request: string): Promise<ModelResult<string>>; <Result>(request: ModelCallRequest<never> & { readonly prepared: PreparedModelCall<Result>; }): Promise<ModelResult<Result>>; (request: ModelCallRequest<never>): Promise<ModelResult<string>>; <Result>(request: ModelCallRequest<ModelTransportDefinition<Result>> & { transport: ModelTransportDefinition<Result>; }): Promise<ModelResult<Result>>; <const Id extends string>(request: ModelCallRequest<Id> & { readonly transport: Id; }): Promise<ModelResult<RegisteredTransportOutput<readonly ModelTransportDefinition<unknown>[], Id>>>; (request: ModelCallRequest<string \| ModelTransportDefinition<unknown>>): Promise<ModelResult<unknown>>; }	必需	Invoke one model call. Named and shorthand input share the same lifecycle: validation, measurement, budget charge, streaming, commit. A caller-supplied signal only shortens the call lifetime. Invoke a prepared call whose settings cannot be replaced. Invoke with the default transport and a plain-text result. Invoke with a transport instance supplied at the call site. Invoke with a transport id registered on this runner. Invoke without narrowing the transport type.
`prepare`	{ (request?: import("../structs/model/runtime.js").ModelPrepareRequest<never>): import("../structs/model/runtime.js").PreparedModelCall<string>; <Result>(request: ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }): PreparedModelCall<Result>; <const Id extends string>(request: ModelPrepareRequest<Id> & { readonly transport: Id; }): PreparedModelCall<RegisteredTransportOutput<readonly ModelTransportDefinition<unknown>[], Id>>; (request: import("../structs/model/runtime.js").ModelPrepareRequest<string \| ModelTransportDefinition>): import("../structs/model/runtime.js").PreparedModelCall; }	必需	Prepare a call and measure it before invocation. A prepared call is single-use and bound to the stage, output tokens and transport it was measured with; `invoke` rejects any attempt to replace those settings. Prepare a call for a transport instance supplied at the call site. Prepare a call for a transport id, typed by the runner's registered transports. Prepare a call without narrowing the transport type.
`execution`	`ExecutionContext`	必需	只读。见类型定义及调用场景。
`remainingCalls`	`number`	必需	只读。Calls still available to this runner after the parent's reserve is applied.
`callCount`	`number`	必需	只读。Completed calls observed by this runner only.
`totalCallCount`	`number`	必需	只读。Includes descendant attempts; local callCount and journal remain isolated.

返回： AgentCoreEngine<Result, State, App>。

`switchModel`

实例方法。

Select a configured model, or replace the single bound model's configuration.

switchModel(options: AgentModelBinding | string): AgentCoreEngine<Result, State, App>

Select a configured model, or replace the single bound model's configuration.

参数	类型	传递	说明
`options`	`string \| AgentModelBinding`	必需	—

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

分支 1

string

分支 2

字段	类型	必需	说明
`provider`	`ChatProvider`	必需	见类型定义及调用场景。
`execution`	`undefined`	可省略	见类型定义及调用场景。
`transports`	`readonly ModelTransportDefinition<unknown>[] \| undefined`	可省略	见类型定义及调用场景。
`sink`	`{ output?: ModelRunnerPorts["onOutput"]; } \| undefined`	可省略	见类型定义及调用场景。
`errors`	`{ inputBudget?: ModelRunnerPorts["inputBudgetError"]; outputBudget?: ModelRunnerPorts["outputBudgetError"]; } \| undefined`	可省略	见类型定义及调用场景。
`children`	`ModelChildPolicy \| undefined`	可省略	只读。见类型定义及调用场景。
`maxInputChars`	`number \| undefined`	可省略	Character budget for the assembled input.
`maxSchemaChars`	`number \| undefined`	可省略	Character allowance for registered capability schemas.
`tokenBudget`	`ModelTokenBudget \| undefined`	可省略	见类型定义及调用场景。
`maxOutputTokens`	`number \| undefined`	可省略	Default output reservation; invoke can override it for one call.
`maxCalls`	`number \| undefined`	可省略	Calls allowed for the whole request, including descendant runners' reservations.
`callTimeoutMs`	`number \| undefined`	可省略	Deadline for one provider call, in milliseconds.
`maxOutputChars`	`number \| undefined`	可省略	Cap on streamed output characters; exceeding it fails the call.
`usage`	`boolean \| undefined`	可省略	Request and record provider usage for each call.
`signal`	`undefined`	可省略	见类型定义及调用场景。

返回： AgentCoreEngine<Result, State, App>。

`bindToolRuntime`

实例方法。

Bind the tool runtime used by workflow context.

bindToolRuntime(tools: ToolBinding): AgentCoreEngine<Result, State, App>

Bind the tool runtime used by workflow context.

参数	类型	传递	说明
`tools`	`ToolBinding`	必需	—

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

分支 1

字段	类型	必需	说明
`invoke`	`InvokeTool`	必需	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
`invokeAsync`	`(request: ToolInvocationRequest) => Promise<ToolResult<unknown>>`	必需	Invoke a registered tool and await its result.

返回： AgentCoreEngine<Result, State, App>。

`bindWorkflow`

实例方法。

Bind a workflow, narrowing the engine's state and App types.

Binding changes the engine's type parameters without changing its identity, so the same instance keeps its model, tools and branch. Bind a workflow together with its App dependencies.

bindWorkflow<NextState>(workflow: AgentWorkflow<NextState, Result, undefined>): AgentCoreEngine<Result, NextState, undefined>

Bind a workflow, narrowing the engine's state and App types.

Binding changes the engine's type parameters without changing its identity, so the same instance keeps its model, tools and branch.

类型参数	约束	默认类型
`NextState`	—	—

参数	类型	传递	说明
`workflow`	`AgentWorkflow<NextState, Result, undefined>`	必需	—

返回： AgentCoreEngine<Result, NextState, undefined>。

bindWorkflow<NextState, NextApp>(workflow: AgentWorkflow<NextState, Result, NextApp>, app: NextApp): AgentCoreEngine<Result, NextState, NextApp>

Bind a workflow together with its App dependencies.

类型参数	约束	默认类型
`NextState`	—	—
`NextApp`	—	—

参数	类型	传递	说明
`workflow`	`AgentWorkflow<NextState, Result, NextApp>`	必需	—
`app`	`NextApp`	必需	—

返回： AgentCoreEngine<Result, NextState, NextApp>。

`checkpoint`

实例方法。

Take an in-memory checkpoint of host-owned data.

The data is cloned on write and on every read, so neither side can mutate the other.

checkpoint<Data>(data: Data): AgentCheckpoint<Data>

Take an in-memory checkpoint of host-owned data.

The data is cloned on write and on every read, so neither side can mutate the other.

类型参数	约束	默认类型
`Data`	—	—

参数	类型	传递	说明
`data`	`Data`	必需	—

返回： AgentCheckpoint<Data>。

返回值结构

字段	类型	必需	说明
`id`	`string`	必需	只读。Checkpoint identifier, unique within the engine.
`source`	`AgentBranch`	必需	只读。Branch the checkpoint was taken on.
`read`	`() => Data`	必需	见类型定义及调用场景。

`exportCheckpoint`

实例方法。

Export a checkpoint for host-owned persistence.

exportCheckpoint<Data>(checkpoint: AgentCheckpoint<Data>): AgentCheckpointRecord<Data>

Export a checkpoint for host-owned persistence.

类型参数	约束	默认类型
`Data`	—	—

参数	类型	传递	说明
`checkpoint`	`AgentCheckpoint<Data>`	必需	—

checkpoint 的字段

字段	类型	必需	说明
`id`	`string`	必需	只读。Checkpoint identifier, unique within the engine.
`source`	`AgentBranch`	必需	只读。Branch the checkpoint was taken on.
`read`	`() => Data`	必需	见类型定义及调用场景。

返回： AgentCheckpointRecord<Data>。

返回值结构

字段	类型	必需	说明
`id`	`string`	必需	只读。Checkpoint identifier, preserved across export and restore.
`source`	`AgentBranch`	必需	只读。Validated branch identity captured at checkpoint time.
`data`	`Data`	必需	只读。Detached data payload; serializable by the host.

`restoreCheckpoint`

实例方法。

Recreate a checkpoint from a persisted record.

The record's branch must match this engine's branch exactly; otherwise persisted data from another branch would be adopted silently.

restoreCheckpoint<Data>(record: AgentCheckpointRecord<Data>): AgentCheckpoint<Data>

Recreate a checkpoint from a persisted record.

The record's branch must match this engine's branch exactly; otherwise persisted data from another branch would be adopted silently.

类型参数	约束	默认类型
`Data`	—	—

参数	类型	传递	说明
`record`	`AgentCheckpointRecord<Data>`	必需	—

record 的字段

字段	类型	必需	说明
`id`	`string`	必需	只读。Checkpoint identifier, preserved across export and restore.
`source`	`AgentBranch`	必需	只读。Validated branch identity captured at checkpoint time.
`data`	`Data`	必需	只读。Detached data payload; serializable by the host.

返回： AgentCheckpoint<Data>。

返回值结构

字段	类型	必需	说明
`id`	`string`	必需	只读。Checkpoint identifier, unique within the engine.
`source`	`AgentBranch`	必需	只读。Branch the checkpoint was taken on.
`read`	`() => Data`	必需	见类型定义及调用场景。

`fork`

实例方法。

Create an engine on a new branch forked at a checkpoint.

The forked engine keeps the round budget, observation and configuration, receives an optional workflow extension, and gets a new branch identity whose parent ids point at this engine. Live handles are not copied: an App dependency, request runtime or tool runtime must be restored by the resume callback, because they cannot be serialized.

fork<Data>({ at, workflow, routes, resume, }: { at: AgentCheckpoint<Data>; workflow?: AgentWorkflow<State, Result, App> | WorkflowExtension<State, Result, App>; routes?: WorkflowExtension<State, Result, App>["routes"]; resume?: (checkpoint: Data) => { app?: App; tools?: ToolBinding; model?: AgentModelRuntime; agentCache?: AgentCachePort; }; }): AgentCoreEngine<Result, State, App>

Create an engine on a new branch forked at a checkpoint.

类型参数	约束	默认类型
`Data`	—	—

参数	类型	传递	说明
`__0`	`{ at: AgentCheckpoint<Data>; workflow?: AgentWorkflow<State, Result, App> \| WorkflowExtension<State, Result, App>; routes?: WorkflowExtension<State, Result, App>["routes"]; resume?: (checkpoint: Data) => { app?: App; tools?: ToolBinding; model?: AgentModelRuntime; agentCache?: AgentCachePort; }; }`	必需	—

__0 的字段

字段	类型	必需	说明
`at`	`AgentCheckpoint<Data>`	必需	见类型定义及调用场景。
`workflow`	`AgentWorkflow<State, Result, App> \| WorkflowExtension<State, Result, App> \| undefined`	可省略	见类型定义及调用场景。
`routes`	`Readonly<Record<string, readonly WorkflowRoute<State, Result, App>[]>> \| undefined`	可省略	见类型定义及调用场景。
`resume`	`((checkpoint: Data) => { app?: App; tools?: ToolBinding; model?: AgentModelRuntime; agentCache?: AgentCachePort; }) \| undefined`	可省略	见类型定义及调用场景。

返回： AgentCoreEngine<Result, State, App>。

`run`

实例方法。

Run the loop with a step function when no workflow is bound. Run a bound workflow from an initial state.

run(step: CoreStep<Result>, options?: { signal?: AbortSignal; modelId?: never; }): Promise<Result>

Run the loop with a step function when no workflow is bound.

参数	类型	传递	说明
`step`	`CoreStep<Result>`	必需	—
`options`	`{ signal?: AbortSignal; modelId?: never; } \| undefined`	可省略	—

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

分支 1

undefined

分支 2

字段	类型	必需	说明
`signal`	`AbortSignal \| undefined`	可省略	见类型定义及调用场景。
`modelId`	`undefined`	可省略	见类型定义及调用场景。

返回： Promise<Result>。

等待后的值： Awaited<Result>。

run(state: State, options?: { signal?: AbortSignal; modelId?: string; }): Promise<Result>

Run a bound workflow from an initial state.

参数	类型	传递	说明
`state`	`State`	必需	—
`options`	`{ signal?: AbortSignal; modelId?: string; } \| undefined`	可省略	—

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

分支 1

undefined

分支 2

字段	类型	必需	说明
`signal`	`AbortSignal \| undefined`	可省略	见类型定义及调用场景。
`modelId`	`string \| undefined`	可省略	见类型定义及调用场景。

返回： Promise<Result>。

等待后的值： Awaited<Result>。

使用示例

Agent：先运行，再逐步绑定 Tool 与依赖：Engine 执行有界循环；绑定 Workflow 后，每次只传状态中变化的数据。
复用基础 Workflow 与 Agent 分支：add 保留旧 Workflow，生成组合后的新 Workflow；fork 继承已有绑定及分支来源。
一次绑定，单次多模型与跨次切换：构造时提供稳定模型配置；请求用配置 ID 选择，不反复注入 Provider。
真实工具调用与请求内运行时：Core 注册并执行真实工具，返回带 invocation 的回执；业务授权由 App 注册的实现拥有。

一个普通步骤即可运行

入门 · Node.js

TypeScriptJavaScript

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

const agent = new AgentCoreEngine<string>();
const answer = await agent.run(() => ({ type: 'complete', value: '你好，Core' }));
console.log(answer);

import { AgentCoreEngine } from '@jangts/agent-core/engine';
const agent = new AgentCoreEngine();
const answer = await agent.run(() => ({ type: 'complete', value: '你好，Core' }));
console.log(answer);

增加显式 Workflow，仍然调用 run

配置 · Node.js

TypeScriptJavaScript

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')],
  }],
});

const agent = new AgentCoreEngine({ workflow });
console.log(await agent.run({ name: 'Ivan' }));
console.log(await agent.run({ name: '访客' }));

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')],
        }],
});
const agent = new AgentCoreEngine({ workflow });
console.log(await agent.run({ name: 'Ivan' }));
console.log(await agent.run({ name: '访客' }));

依赖稍后就绪时绑定一次

扩展 · Node.js

没有重新传 Workflow。传入的信号与实例信号合并；取消不会让迟到结果成为成功提交。

TypeScriptJavaScript

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')],
  }],
});

const agent = new AgentCoreEngine<string>({ maxRounds: 2 }).bindWorkflow(workflow);
const controller = new AbortController();
console.log(await agent.run({ name: 'Ivan' }, { signal: controller.signal }));

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')],
        }],
});
const agent = new AgentCoreEngine({ maxRounds: 2 }).bindWorkflow(workflow);
const controller = new AbortController();
console.log(await agent.run({ name: 'Ivan' }, { signal: controller.signal }));

AgentCoreEngine

AgentWorkflow

AttemptBudget

route

AgentCachePort

AgentCheckpoint

AgentModelRuntime

ExecutionObserver

NodeAgentCache

NodeCache

WorkflowContext

WorkflowModel

AgentCoreEngine

导入

定义

泛型参数

构造函数

实例属性

成员目录

成员详情

`Workflow`

`AttemptBudget`

`createWorkflow`

`bindModel`

`bindModelRuntime`

`switchModel`

`bindToolRuntime`

`bindWorkflow`

`checkpoint`

`exportCheckpoint`

`restoreCheckpoint`

`fork`

`run`

使用示例

一个普通步骤即可运行

增加显式 Workflow，仍然调用 run

依赖稍后就绪时绑定一次

相关策略源码

相关定义

AgentCoreEngine

AgentWorkflow

AttemptBudget

route

AgentCachePort

AgentCheckpoint

AgentModelRuntime

ExecutionObserver

NodeAgentCache

NodeCache

WorkflowContext

WorkflowModel

AgentCoreEngine ​

导入 ​

定义 ​

泛型参数 ​

构造函数 ​

实例属性 ​

成员目录 ​

成员详情 ​

Workflow ​

AttemptBudget ​

createWorkflow ​

bindModel ​

bindModelRuntime ​

switchModel ​

bindToolRuntime ​

bindWorkflow ​

checkpoint ​

exportCheckpoint ​

restoreCheckpoint ​

fork ​

run ​

使用示例 ​

一个普通步骤即可运行 ​

增加显式 Workflow，仍然调用 run ​

依赖稍后就绪时绑定一次 ​

相关策略源码 ​

相关定义 ​

AgentCoreEngine

导入

定义

泛型参数

构造函数

实例属性

成员目录

成员详情

`Workflow`

`AttemptBudget`

`createWorkflow`

`bindModel`

`bindModelRuntime`

`switchModel`

`bindToolRuntime`

`bindWorkflow`

`checkpoint`

`exportCheckpoint`

`restoreCheckpoint`

`fork`

`run`

使用示例

一个普通步骤即可运行

增加显式 Workflow，仍然调用 run

依赖稍后就绪时绑定一次

相关策略源码

相关定义