WorkflowModel

CORE · interface · Type contract

Model and tool access for one workflow invocation.

Every call is charged to the workflow's shared budget. Overloads select the transport: a prepared call, the default plain-text transport, or one registered transport with its typed result.

Import

TypeScript

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

JavaScript

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

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

Definition

interface WorkflowModel

Field structure

Field	Type	Required	Description
invoke	{ <Result>(request: WorkflowModelRequest<never> & { readonly prepared: import("../model/runtime.js").PreparedModelCall<Result>; }): Promise<import("../invocation.js").ModelResult<Result>>; (request: WorkflowModelRequest<never>): Promise<import("../invocation.js").ModelResult<string>>; <Result>(request: WorkflowModelRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }): Promise<import("../invocation.js").ModelResult<Result>>; (request: WorkflowModelRequest<string | ModelTransportDefinition>): Promise<import("../invocation.js").ModelResult<unknown>>; }	Required	See the type definition and usage context.
prepare	{ (request?: import("../model/runtime.js").ModelPrepareRequest<never> & { readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall<string>; <Result>(request: import("../model/runtime.js").ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall<Result>; (request: import("../model/runtime.js").ModelPrepareRequest<string | ModelTransportDefinition> & { readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall; }	Required	See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available to this workflow after ancestor reservations.
callCount	number	Required	Read-only. Calls completed by this workflow's own runner.
totalCallCount	number	Required	Read-only. Calls consumed across this workflow and its descendants.

Member index

Member	Purpose
invoke	See the overload below for full inputs and outputs.
prepare	See the overload below for full inputs and outputs.

Member details

invoke

WorkflowModel.invoke<Result>(request: WorkflowModelRequest<never> & { readonly prepared: import("../model/runtime.js").PreparedModelCall<Result>; }): Promise<import("../invocation.js").ModelResult<Result>>

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	WorkflowModelRequest<never> & { readonly prepared: import("../model/runtime.js").PreparedModelCall<Result>; }	Required	—

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

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	Required	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	Required	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ModelResult<Result>>.

Awaited value: ModelResult<Result>.

Return value structure

Field	Type	Required	Description
value	Result	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

WorkflowModel.invoke(request: WorkflowModelRequest<never>): Promise<import("../invocation.js").ModelResult<string>>

Parameter	Type	Passing	Description
request	WorkflowModelRequest<never>	Required	—

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

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ModelResult<string>>.

Awaited value: ModelResult<string>.

Return value structure

Field	Type	Required	Description
value	string	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

WorkflowModel.invoke<Result>(request: WorkflowModelRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }): Promise<import("../invocation.js").ModelResult<Result>>

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	WorkflowModelRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }	Required	—

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

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ModelResult<Result>>.

Awaited value: ModelResult<Result>.

Return value structure

Field	Type	Required	Description
value	Result	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

WorkflowModel.invoke(request: WorkflowModelRequest<string | ModelTransportDefinition>): Promise<import("../invocation.js").ModelResult<unknown>>

Parameter	Type	Passing	Description
request	WorkflowModelRequest<string | ModelTransportDefinition<unknown>>	Required	—

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

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	string | ModelTransportDefinition<unknown> | undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	string | ModelTransportDefinition<unknown> | undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ModelResult<unknown>>.

Awaited value: ModelResult<unknown>.

Return value structure

Field	Type	Required	Description
value	unknown	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

prepare

WorkflowModel.prepare(request?: import("../model/runtime.js").ModelPrepareRequest<never> & { readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall<string>

Parameter	Type	Passing	Description
request	(ModelPrepareRequest<never> & { readonly modelId?: string; }) | undefined	Optional	—

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

Branch 1

undefined

Branch 2

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<string>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<string>	Required	See the type definition and usage context.

WorkflowModel.prepare<Result>(request: import("../model/runtime.js").ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall<Result>

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; readonly modelId?: string; }	Required	—

Fields of request

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<Result>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<Result>	Required	See the type definition and usage context.

WorkflowModel.prepare(request: import("../model/runtime.js").ModelPrepareRequest<string | ModelTransportDefinition> & { readonly modelId?: string; }): import("../model/runtime.js").PreparedModelCall

Parameter	Type	Passing	Description
request	ModelPrepareRequest<string | ModelTransportDefinition<unknown>> & { readonly modelId?: string; }	Required	—

Fields of request

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	string | ModelTransportDefinition<unknown> | undefined	Optional	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
modelId	string | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<unknown>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<unknown>	Required	See the type definition and usage context.

Examples

• Actual request measurement and same-call preparation snapshot: Use prepare only when context must be handled ahead of time; multiple measurements and the final send reuse the same transport preparation.
• Bind once, multiple models per run, and switching across runs: Provide stable model configuration at construction; requests select by configuration ID instead of injecting a Provider repeatedly.

Ordinary calls still only use invoke

Beginner · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
  async *stream(messages: readonly { content: string }[]) {
    yield '收到：' + messages.at(-1)!.content;
  },
};
const runner = new ModelRunner({ provider });
console.log((await runner.invoke('你好')).value);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const runner = new ModelRunner({ provider });
console.log((await runner.invoke('你好')).value);

Prepare once only when measurement is needed

Configuration · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
  async *stream(messages: readonly { content: string }[]) {
    yield '收到：' + messages.at(-1)!.content;
  },
};
const runner = new ModelRunner({ provider, maxInputChars: 1000 });
const prepared = runner.prepare({ stageId: 'reply', maxOutputTokens: 400 });
const input = '你好，解释这次服务状态';
console.log(prepared.measure(input));
const result = await runner.invoke({ input, prepared });
console.log(result.value);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const runner = new ModelRunner({ provider, maxInputChars: 1000 });
const prepared = runner.prepare({ stageId: 'reply', maxOutputTokens: 400 });
const input = '你好，解释这次服务状态';
console.log(prepared.measure(input));
const result = await runner.invoke({ input, prepared });
console.log(result.value);

Related policy source

• Same-call preparation and real input measurement

Related definitions

• ModelCallRecord
• ModelPrepareRequest
• ModelResult
• ModelTransportDefinition
• PreparedModelCall