AgentCoreEngineSetup

CORE · type · Type contract

Engine construction options.

Combines round budget and error factories with exactly one model shape (a single bound model or a named catalog), an optional tool runtime, an optional branch identity, and an optional workflow together with its App dependencies.

Import

TypeScript

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

JavaScript

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

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

Definition

Type: AgentCoreEngineSetup<State, Result, App>

Type expression

type AgentCoreEngineSetup<State, Result, App = undefined> = AgentCoreEngineOptions & {
  readonly branch?: AgentBranch;
  readonly tools?: ToolBinding;
} & (
    | {
        model?: AgentModelBinding;
        models?: never;
      }
    | {
        model?: string;
        models: Readonly<Record<string, AgentModelBinding>>;
        maxModelCalls?: number;
      }
  ) &
  (
    | { workflow?: undefined; app?: never }
    | ({ readonly workflow: AgentWorkflow<State, Result, App> } & ([App] extends [undefined]
        ? { readonly app?: undefined }
        : { readonly app: App }))
  );

Type parameters

Type parameter	Constraint	Default type
State	—	—
Result	—	—
App	—	undefined

Union branch structure

Optional shapes of AgentCoreEngineSetup: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
cache	EngineCacheOptions | undefined	Optional	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	Optional	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	Optional	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	Optional	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	Optional	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	Optional	Read-only. See the type definition and usage context.
tools	ToolBinding | undefined	Optional	Read-only. See the type definition and usage context.
model	AgentModelBinding | undefined	Optional	See the type definition and usage context.
models	undefined	Optional	See the type definition and usage context.
workflow	undefined	Optional	See the type definition and usage context.
app	undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
cache	EngineCacheOptions | undefined	Optional	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	Optional	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	Optional	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	Optional	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	Optional	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	Optional	Read-only. See the type definition and usage context.
tools	ToolBinding | undefined	Optional	Read-only. See the type definition and usage context.
model	AgentModelBinding | undefined	Optional	See the type definition and usage context.
models	undefined	Optional	See the type definition and usage context.
workflow	AgentWorkflow<State, Result, App>	Required	Read-only. See the type definition and usage context.
app	App | undefined	Optional	Read-only. See the type definition and usage context.

Type condition: 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; })

Branch 3

Field	Type	Required	Description
cache	EngineCacheOptions | undefined	Optional	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	Optional	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	Optional	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	Optional	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	Optional	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	Optional	Read-only. See the type definition and usage context.
tools	ToolBinding | undefined	Optional	Read-only. See the type definition and usage context.
model	string | undefined	Optional	See the type definition and usage context.
models	Readonly<Record<string, AgentModelBinding>>	Required	See the type definition and usage context.
maxModelCalls	number | undefined	Optional	See the type definition and usage context.
workflow	undefined	Optional	See the type definition and usage context.
app	undefined	Optional	See the type definition and usage context.

Branch 4

Field	Type	Required	Description
cache	EngineCacheOptions | undefined	Optional	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	Optional	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	Optional	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	Optional	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	Optional	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	Optional	Read-only. See the type definition and usage context.
tools	ToolBinding | undefined	Optional	Read-only. See the type definition and usage context.
model	string | undefined	Optional	See the type definition and usage context.
models	Readonly<Record<string, AgentModelBinding>>	Required	See the type definition and usage context.
maxModelCalls	number | undefined	Optional	See the type definition and usage context.
workflow	AgentWorkflow<State, Result, App>	Required	Read-only. See the type definition and usage context.
app	App | undefined	Optional	Read-only. See the type definition and usage context.

Type condition: 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; })

Examples

• Agent: run first, then bind tools and dependencies step by step: The Engine executes a bounded loop; after a Workflow is bound, each run only receives the data that changed in state.

A single ordinary step is enough to run

Beginner · Node.js

TypeScript

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

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

JavaScript

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

Add an explicit Workflow and still call run

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

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

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

Related policy source

• Execution implementation of the bounded loop, commit, and cancellation

Related definitions

• AgentBranch
• AgentCachePort
• AgentCoreEngineOptions
• AgentModelBinding
• AgentWorkflow
• EngineCacheOptions
• ErasedTool
• ExecutionOptions
• ModelRunnerSettings
• ToolRegistry