WorkflowModel

CORE · interface · 类型合同

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.

导入

TypeScript

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

JavaScript

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

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

定义

interface WorkflowModel

字段结构

字段	类型	必需	说明
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>>; }	必需	见类型定义及调用场景。
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; }	必需	见类型定义及调用场景。
remainingCalls	number	必需	只读。Calls still available to this workflow after ancestor reservations.
callCount	number	必需	只读。Calls completed by this workflow's own runner.
totalCallCount	number	必需	只读。Calls consumed across this workflow and its descendants.

成员目录

成员	用途
invoke	完整输入输出见下方重载。
prepare	完整输入输出见下方重载。

成员详情

invoke

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

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

参数	类型	传递	说明
request	WorkflowModelRequest<never> & { readonly prepared: import("../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	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	可省略	见类型定义及调用场景。
modelId	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	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	可省略	见类型定义及调用场景。
modelId	string | undefined	可省略	只读。见类型定义及调用场景。

返回： Promise<ModelResult<Result>>。

等待后的值： ModelResult<Result>。

返回值结构

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

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

参数	类型	传递	说明
request	WorkflowModelRequest<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	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	可省略	见类型定义及调用场景。
modelId	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	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	可省略	见类型定义及调用场景。
modelId	string | undefined	可省略	只读。见类型定义及调用场景。

返回： Promise<ModelResult<string>>。

等待后的值： ModelResult<string>。

返回值结构

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

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

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

参数	类型	传递	说明
request	WorkflowModelRequest<ModelTransportDefinition<Result>> & { readonly 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	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	可省略	见类型定义及调用场景。
modelId	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	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	可省略	见类型定义及调用场景。
modelId	string | undefined	可省略	只读。见类型定义及调用场景。

返回： Promise<ModelResult<Result>>。

等待后的值： ModelResult<Result>。

返回值结构

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

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

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

参数 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	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	string | ModelTransportDefinition<unknown> | undefined	可省略	只读。见类型定义及调用场景。
input	string	必需	见类型定义及调用场景。
instructions	string | undefined	可省略	见类型定义及调用场景。
modelId	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	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	string | ModelTransportDefinition<unknown> | undefined	可省略	只读。见类型定义及调用场景。
input	readonly ModelMessage[] | BuiltContext | ContextPlan	必需	见类型定义及调用场景。
instructions	undefined	可省略	见类型定义及调用场景。
modelId	string | undefined	可省略	只读。见类型定义及调用场景。

返回： Promise<ModelResult<unknown>>。

等待后的值： ModelResult<unknown>。

返回值结构

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

prepare

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

参数	类型	传递	说明
request	(ModelPrepareRequest<never> & { readonly modelId?: string; }) | undefined	可省略	—

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

分支 1

undefined

分支 2

字段	类型	必需	说明
stageId	string | undefined	可省略	只读。见类型定义及调用场景。
transport	undefined	可省略	只读。见类型定义及调用场景。
maxOutputTokens	number | undefined	可省略	只读。见类型定义及调用场景。
modelId	string | 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>	必需	见类型定义及调用场景。

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

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

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

request 的字段

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

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

参数	类型	传递	说明
request	ModelPrepareRequest<string | ModelTransportDefinition<unknown>> & { readonly modelId?: string; }	必需	—

request 的字段

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

使用示例

• 实际请求测量与同次准备快照：需要提前处理上下文时才 prepare；多次测量与最终发送复用同一次传输准备。
• 一次绑定，单次多模型与跨次切换：构造时提供稳定模型配置；请求用配置 ID 选择，不反复注入 Provider。

普通调用仍然只有 invoke

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

只在需要测量时准备一次

配置 · 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);

相关策略源码

• 同次准备与真实输入计量

相关定义

• ModelCallRecord
• ModelPrepareRequest
• ModelResult
• ModelTransportDefinition
• PreparedModelCall