ModelRunner

CORE · class · 运行时值

Execute registered model stages under one request's budgets and lifetime.

Invariants: at most one call is in flight per runner; callCount and journal are local to the runner while totalCallCount includes descendants; every call is charged to the shared budget before I/O and every failure is annotated with its stage before it propagates. No business prompts, domain stages or provider SDKs are built into this runner.

导入

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';

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

定义

class ModelRunner<TransportId, Transports>

泛型参数

类型参数	约束	默认类型
TransportId	string	string
Transports	readonly ModelTransportDefinition[]	readonly ModelTransportDefinition[]

构造函数

new ModelRunner<TransportId extends string = string, const Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition<unknown>[]>(options: ModelRunnerOptions<Transports>): ModelRunner<TransportId, Transports>

Build a runner from App options, or adopt an already compiled binding.

Compiling here rather than per call is what makes configuration immutable for the runner's lifetime. The text transport is always registered first, then App transports in declaration order.

参数	类型	传递	说明
options	ModelRunnerOptions<Transports>	必需	—

options 的字段

字段	类型	必需	说明
provider	ChatProvider	必需	见类型定义及调用场景。
execution	ExecutionOptions | undefined	可省略	见类型定义及调用场景。
transports	Transports | 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.

返回： ModelRunner<TransportId, Transports>。

实例属性

字段	类型	必需	说明
journal	ContextJournal	必需	只读。Record of parsed results for this runner; descendants keep their own journals.
callCount	number	必需	只读。Completed calls observed by this runner only.
lastCall	Readonly<ModelCallTrace> | undefined	必需	只读。Detached copy of the most recent call trace, or undefined before the first call.
signal	AbortSignal	必需	只读。见类型定义及调用场景。
execution	ExecutionContext	必需	只读。见类型定义及调用场景。
childLimits	Readonly<Required<ModelChildPolicy>>	必需	只读。Limits shared by every runner of one request; children only read them.
totalCallCount	number	必需	只读。Includes descendant attempts; local callCount and journal remain isolated.
remainingCalls	number	必需	只读。Calls still available to this runner after the parent's reserve is applied.

成员目录

成员	用途
createChild	Create a fresh runner for a nested stage. The child never inherits conversation, journal or sinks: only the provider, fixed limits, the parent budget and the child's own lifetime. All ancestors keep their budgets, and the child is charged through them, so nested work cannot overspend.
prepare	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.
invoke	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.

成员详情

createChild

实例方法。

Create a fresh runner for a nested stage.

The child never inherits conversation, journal or sinks: only the provider, fixed limits, the parent budget and the child's own lifetime. All ancestors keep their budgets, and the child is charged through them, so nested work cannot overspend.

createChild(options: import("../structs/model/runtime.js").ModelChildOptions): ModelRunner

Create a fresh runner for a nested stage.

The child never inherits conversation, journal or sinks: only the provider, fixed limits, the parent budget and the child's own lifetime. All ancestors keep their budgets, and the child is charged through them, so nested work cannot overspend.

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

options 的字段

字段	类型	必需	说明
id	string	必需	只读。Child stage id, reported in traces and events.
maxCalls	number	必需	只读。Calls the child may use from the shared request budget.
reserveCalls	number	必需	只读。Calls kept for the parent; the child cannot spend them.
timeoutMs	number	必需	只读。Deadline for the child's own calls, in milliseconds.
transports	readonly ModelTransportDefinition<unknown>[] | undefined	可省略	只读。Additional transports visible to the child.
diagnostics	DiagnosticContext | undefined	可省略	只读。见类型定义及调用场景。
signal	AbortSignal | undefined	可省略	只读。Extra cancellation; can only shorten the parent's lifetime.

返回： ModelRunner<string, readonly ModelTransportDefinition<unknown>[]>。

prepare

实例方法。

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.

prepare(request?: import("../structs/model/runtime.js").ModelPrepareRequest<never>): import("../structs/model/runtime.js").PreparedModelCall<string>

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.

参数	类型	传递	说明
request	ModelPrepareRequest<never> | undefined	可省略	—

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

分支 1

undefined

分支 2

字段	类型	必需	说明
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。

返回： PreparedModelCall<string>。

返回值结构

字段	类型	必需	说明
modelId	string | undefined	可省略	只读。Model binding the call was prepared with.
stageId	string	必需	只读。见类型定义及调用场景。
transportId	string	必需	只读。见类型定义及调用场景。
maxOutputTokens	number	必需	只读。见类型定义及调用场景。
remainingCalls	number	必需	只读。Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	必需	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	必需	只读。见类型定义及调用场景。
schemaChars	number	必需	只读。见类型定义及调用场景。
instruction	string | undefined	可省略	只读。见类型定义及调用场景。
createResponse	() => ModelResponseCollector<string>	必需	见类型定义及调用场景。

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

Prepare a call for a transport instance supplied at the call site.

类型参数	约束	默认类型
Result	—	—

参数	类型	传递	说明
request	ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }	必需	—

request 的字段

字段	类型	必需	说明
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	ModelTransportDefinition<Result>	必需	只读。见类型定义及调用场景。
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。

返回： PreparedModelCall<Result>。

返回值结构

字段	类型	必需	说明
modelId	string | undefined	可省略	只读。Model binding the call was prepared with.
stageId	string	必需	只读。见类型定义及调用场景。
transportId	string	必需	只读。见类型定义及调用场景。
maxOutputTokens	number	必需	只读。见类型定义及调用场景。
remainingCalls	number	必需	只读。Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	必需	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	必需	只读。见类型定义及调用场景。
schemaChars	number	必需	只读。见类型定义及调用场景。
instruction	string | undefined	可省略	只读。见类型定义及调用场景。
createResponse	() => ModelResponseCollector<Result>	必需	见类型定义及调用场景。

prepare<const Id extends string>(request: import("../structs/model/runtime.js").ModelPrepareRequest<Id> & { readonly transport: Id; }): import("../structs/model/runtime.js").PreparedModelCall<import("../structs/model/runtime.js").RegisteredTransportOutput<Transports, Id>>

Prepare a call for a transport id, typed by the runner's registered transports.

类型参数	约束	默认类型
Id	string	—

参数	类型	传递	说明
request	ModelPrepareRequest<Id> & { readonly transport: Id; }	必需	—

request 的字段

字段	类型	必需	说明
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	Id	必需	只读。见类型定义及调用场景。
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。

返回： PreparedModelCall<RegisteredTransportOutput<Transports, Id>>。

返回值结构

字段	类型	必需	说明
modelId	string | undefined	可省略	只读。Model binding the call was prepared with.
stageId	string	必需	只读。见类型定义及调用场景。
transportId	string	必需	只读。见类型定义及调用场景。
maxOutputTokens	number	必需	只读。见类型定义及调用场景。
remainingCalls	number	必需	只读。Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	必需	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	必需	只读。见类型定义及调用场景。
schemaChars	number	必需	只读。见类型定义及调用场景。
instruction	string | undefined	可省略	只读。见类型定义及调用场景。
createResponse	() => ModelResponseCollector<RegisteredTransportOutput<Transports, Id>>	必需	见类型定义及调用场景。

prepare(request: import("../structs/model/runtime.js").ModelPrepareRequest<string | ModelTransportDefinition>): import("../structs/model/runtime.js").PreparedModelCall

Prepare a call without narrowing the transport type.

参数	类型	传递	说明
request	ModelPrepareRequest<string | ModelTransportDefinition<unknown>>	必需	—

request 的字段

字段	类型	必需	说明
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	string | ModelTransportDefinition<unknown> | undefined	可省略	只读。见类型定义及调用场景。
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。

返回： PreparedModelCall<unknown>。

返回值结构

字段	类型	必需	说明
modelId	string | undefined	可省略	只读。Model binding the call was prepared with.
stageId	string	必需	只读。见类型定义及调用场景。
transportId	string	必需	只读。见类型定义及调用场景。
maxOutputTokens	number	必需	只读。见类型定义及调用场景。
remainingCalls	number	必需	只读。Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	必需	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	必需	只读。见类型定义及调用场景。
schemaChars	number	必需	只读。见类型定义及调用场景。
instruction	string | undefined	可省略	只读。见类型定义及调用场景。
createResponse	() => ModelResponseCollector<unknown>	必需	见类型定义及调用场景。

invoke

实例方法。

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.

invoke(request: string): Promise<ModelResult<string>>

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.

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

返回： Promise<ModelResult<string>>。

等待后的值： ModelResult<string>。

返回值结构

字段	类型	必需	说明
value	string	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

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

Invoke a prepared call whose settings cannot be replaced.

类型参数	约束	默认类型
Result	—	—

参数	类型	传递	说明
request	ModelCallRequest<never> & { readonly prepared: import("../structs/model/runtime.js").PreparedModelCall<Result>; }	必需	—

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

分支 1

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	必需	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	必需	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。

返回： Promise<ModelResult<Result>>。

等待后的值： ModelResult<Result>。

返回值结构

字段	类型	必需	说明
value	Result	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

invoke(request: ModelCallRequest<never>): Promise<ModelResult<string>>

Invoke with the default transport and a plain-text result.

参数	类型	传递	说明
request	ModelCallRequest<never>	必需	—

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

分支 1

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。

返回： Promise<ModelResult<string>>。

等待后的值： ModelResult<string>。

返回值结构

字段	类型	必需	说明
value	string	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

invoke<Result>(request: ModelCallRequest<ModelTransportDefinition<Result>> & { transport: ModelTransportDefinition<Result>; }): Promise<ModelResult<Result>>

Invoke with a transport instance supplied at the call site.

类型参数	约束	默认类型
Result	—	—

参数	类型	传递	说明
request	ModelCallRequest<ModelTransportDefinition<Result>> & { transport: ModelTransportDefinition<Result>; }	必需	—

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

分支 1

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	ModelTransportDefinition<Result>	必需	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	ModelTransportDefinition<Result>	必需	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。

返回： Promise<ModelResult<Result>>。

等待后的值： ModelResult<Result>。

返回值结构

字段	类型	必需	说明
value	Result	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

invoke<const Id extends string>(request: ModelCallRequest<Id> & { readonly transport: Id; }): Promise<ModelResult<import("../structs/model/runtime.js").RegisteredTransportOutput<Transports, Id>>>

Invoke with a transport id registered on this runner.

类型参数	约束	默认类型
Id	string	—

参数	类型	传递	说明
request	ModelCallRequest<Id> & { readonly transport: Id; }	必需	—

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

分支 1

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	Id	必需	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	Id	必需	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。

返回： Promise<ModelResult<RegisteredTransportOutput<Transports, Id>>>。

等待后的值： ModelResult<RegisteredTransportOutput<Transports, Id>>。

返回值结构

字段	类型	必需	说明
value	RegisteredTransportOutput<Transports, Id>	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

invoke(request: ModelCallRequest<TransportId | ModelTransportDefinition>): Promise<ModelResult<unknown>>

Invoke without narrowing the transport type.

参数	类型	传递	说明
request	ModelCallRequest<ModelTransportDefinition<unknown> | TransportId>	必需	—

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

分支 1

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	ModelTransportDefinition<unknown> | TransportId | undefined	可省略	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。

分支 2

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	可省略	只读。Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	可省略	只读。Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	ModelTransportDefinition<unknown> | TransportId | undefined	可省略	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。

返回： Promise<ModelResult<unknown>>。

等待后的值： ModelResult<unknown>。

返回值结构

字段	类型	必需	说明
value	unknown	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

使用示例

• ModelRunner：输入可以省写，输出合同保持一致：用真实 Provider 端口执行一次模型交互，返回 value 和本次 invocation。
• 实际请求测量与同次准备快照：需要提前处理上下文时才 prepare；多次测量与最终发送复用同一次传输准备。
• 子执行：隔离记录，共享祖先额度：子 Runner 不继承对话和输出接收器，但不能绕过父级预算、取消和期限。

同一输出的两种输入

入门 · 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 });
const first = await runner.invoke('你好');
const second = await runner.invoke({ input: '你好' });
console.log(first.value, second.value);
console.log(first.invocation.invocationId);

JavaScript

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

增加预算与请求取消

配置 · 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, maxCalls: 2, maxInputChars: 4000,
  maxOutputChars: 2000, callTimeoutMs: 15000,
  execution: { signal: AbortSignal.timeout(20000) },
});
const result = await runner.invoke({ input: '你好', stageId: 'reply', maxOutputTokens: 600 });
console.log(result.value, runner.remainingCalls);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const runner = new ModelRunner({ provider, maxCalls: 2, maxInputChars: 4000,
    maxOutputChars: 2000, callTimeoutMs: 15000,
    execution: { signal: AbortSignal.timeout(20000) },
});
const result = await runner.invoke({ input: '你好', stageId: 'reply', maxOutputTokens: 600 });
console.log(result.value, runner.remainingCalls);

增加独立的有序输出接收器

扩展 · Node.js

sink.output 按序等待。model.output 是尚未完整校验的提议，不能在此执行模型提出的工具操作。

TypeScript

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

JavaScript

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

相关策略源码

• Core 的基础预算缺省值
• 同次准备与真实输入计量

相关定义

• ContextJournal
• ExecutionContext
• ModelCallRecord
• ModelCallRequest
• ModelCallTrace
• ModelChildOptions
• ModelChildPolicy
• ModelPrepareRequest
• ModelResult
• ModelRunnerOptions
• ModelRunnerSettings
• ModelTransportDefinition
• PreparedModelCall
• RegisteredTransportOutput