本页是 OpenRouter Agent SDK callModel 函数的完整类型参考。涵盖 CallModelInput 全部参数（含 dynamic function 形式）、ModelResult 的七种消费方式（文本/流/工具调用）、tool() 创建工具的类型结构、TurnContext/ToolExecuteContext 上下文类型、StopCondition 停止条件以及 fromChatMessages/fromClaudeMessages 等格式转换函数。

callModel

function callModel(request: CallModelInput, options?: RequestOptions): ModelResult

使用 OpenResponses API 创建响应，支持多种消费模式。

CallModelInput

参数	类型	必填	说明
model	string | ((ctx: TurnContext) => string)	是*	模型 ID（如 "openai/gpt-5-nano"）
models	string[]	是*	模型降级备选数组
input	OpenResponsesInput	是	输入消息或字符串
instructions	string | ((ctx: TurnContext) => string)	否	系统级指令
tools	Tool[]	否	提供给模型的工具列表
maxToolRounds	MaxToolRounds	否	工具执行轮次上限（已废弃）
stopWhen	StopWhen	否	停止条件
temperature	number | ((ctx: TurnContext) => number)	否	采样温度（0-2）
maxOutputTokens	number | ((ctx: TurnContext) => number)	否	最大生成 token 数
topP	number	否	Top-p 采样
text	ResponseTextConfig	否	文本格式配置
provider	ProviderPreferences	否	Provider 路由与配置
topK	number	否	Top-k 采样
metadata	Record<string, string>	否	请求元数据
toolChoice	ToolChoice	否	工具选择配置
parallelToolCalls	boolean	否	是否并行调用工具
reasoning	ReasoningConfig	否	推理配置
promptCacheKey	string	否	Prompt 缓存键
previousResponseId	string	否	关联上一次响应的 ID
include	string[]	否	响应中包含的额外字段
background	boolean	否	是否在后台运行
safetyIdentifier	string	否	用户安全标识
serviceTier	string	否	服务等级偏好
truncation	string	否	截断模式
plugins	Plugin[]	否	启用的插件列表
user	string	否	终端用户标识
sessionId	string	否	会话标识
store	boolean	否	是否存储请求数据
context	ContextInput<ToolContextMap>	否	按工具名索引的上下文数据

*model 和 models 二选一必填。

ProviderPreferences

参数	类型	说明
allowFallbacks	boolean	主 provider 不可用时是否允许降级（默认 true）
requireParameters	boolean	仅使用支持所有请求参数的 provider
dataCollection	"allow" | "deny"	数据收集策略
order	string[]	自定义 provider 路由顺序
only	string[]	限定到特定 provider
ignore	string[]	排除特定 provider
quantizations	string[]	按量化级别筛选
sort	string	负载均衡策略（如 "throughput"）
maxPrice	object	最高价格限制
preferredMinThroughput	number	最低吞吐率偏好（tokens/s）
preferredMaxLatency	number	最高延迟偏好

RequestOptions

参数	类型	说明
timeout	number	请求超时毫秒数
signal	AbortSignal	用于取消请求的 AbortSignal

---

ModelResult

对响应的封装，提供多种消费方式。

方法一览

getText()

getText(): Promise<string>

等待工具执行完毕后，获取最终文本内容。

getResponse()

getResponse(): Promise<OpenResponsesNonStreamingResponse>

获取完整响应，包含 usage 数据（inputTokens、outputTokens、cachedTokens）。

getTextStream()

getTextStream(): AsyncIterableIterator<string>

以增量方式流式获取文本片段。

getReasoningStream()

getReasoningStream(): AsyncIterableIterator<string>

流式获取推理内容（适用于推理模型）。

getNewMessagesStream()

getNewMessagesStream(): AsyncIterableIterator<ResponsesOutputMessage | OpenResponsesFunctionCallOutput>

以 OpenResponses 格式流式获取累积消息快照。

getFullResponsesStream()

getFullResponsesStream(): AsyncIterableIterator<EnhancedResponseStreamEvent>

流式获取所有事件，含工具预备结果。

getToolCalls()

getToolCalls(): Promise<ParsedToolCall[]>

获取初始响应中的全部工具调用。

getToolCallsStream()

getToolCallsStream(): AsyncIterableIterator<ParsedToolCall>

工具调用完成时逐个流式推送。

getToolStream()

getToolStream(): AsyncIterableIterator<ToolStreamEvent>

流式获取工具增量与预备结果。

getContextUpdates()

getContextUpdates(): AsyncGenerator<ToolContextMap<TTools>>

每当工具调用 setContext() 时推送上下文快照，工具执行完毕后自动关闭。

cancel()

cancel(): Promise<void>

取消流及所有消费者。

---

Tool 类型体系

tool()

function tool<TInput, TOutput>(config: ToolConfig): Tool

创建带 Zod 类型校验的工具。

ToolConfig

参数	类型	必填	说明
name	string	是	工具名称
description	string	否	工具描述
inputSchema	ZodObject	是	输入参数 schema
outputSchema	ZodType	否	输出 schema
eventSchema	ZodType	否	事件 schema（触发 generator 模式）
contextSchema	ZodObject	否	工具所需的上下文数据 schema
execute	function | false	是	执行函数，或 false 表示手动处理
nextTurnParams	NextTurnParamsFunctions	否	修改下一轮参数的函数集合

Tool 联合类型

type Tool =
  | ToolWithExecute<ZodObject, ZodType>
  | ToolWithGenerator<ZodObject, ZodType, ZodType>
  | ManualTool<ZodObject, ZodType>;

ToolWithExecute：普通工具，execute 返回 Promise<Output>。

ToolWithGenerator：流式工具，execute 返回 AsyncGenerator<Event>，需配合 eventSchema。

ManualTool：无 execute 函数，工具调用需外部手动处理。

---

Context 类型

TurnContext

interface TurnContext {
  toolCall?: OpenResponsesFunctionToolCall;
  numberOfTurns: number;
  turnRequest?: OpenResponsesRequest;
}

ToolExecuteContext

传入工具 execute 函数的上下文，合并了 TurnContext 与工具专属上下文：

type ToolExecuteContext<TName, TContext> =
  TurnContext & {
    tools: {
      readonly [K in TName]: Readonly<TContext>;
    };
    setContext(partial: Partial<TContext>): void;
  };

ContextInput

上下文可以是静态值、同步函数或异步函数：

type ContextInput<T> =
  | T
  | ((turn: TurnContext) => T)
  | ((turn: TurnContext) => Promise<T>);

NextTurnParamsContext

nextTurnParams 函数接收到的当前请求上下文：

interface NextTurnParamsContext {
  input: OpenResponsesInput;
  model: string;
  models: string[];
  temperature: number | null;
  maxOutputTokens: number | null;
  topP: number | null;
  topK?: number | undefined;
  instructions: string | null;
}

---

Stream 事件类型

EnhancedResponseStreamEvent

type EnhancedResponseStreamEvent =
  | OpenResponsesStreamEvent
  | ToolPreliminaryResultEvent;

ToolStreamEvent

type ToolStreamEvent =
  | { type: 'delta'; content: string }
  | { type: 'preliminary_result'; toolCallId: string; result: unknown };

ParsedToolCall

interface ParsedToolCall {
  id: string;
  name: string;
  arguments: unknown;
}

ToolExecutionResult

interface ToolExecutionResult {
  toolCallId: string;
  toolName: string;
  result: unknown;
  preliminaryResults?: unknown[];
  error?: Error;
}

---

停止条件

StopWhen

type StopWhen = StopCondition | StopCondition[];

StopCondition

type StopCondition = (context: StopConditionContext) => boolean | Promise<boolean>;

StepResult

每轮执行的结果快照：

interface StepResult {
  stepType: 'initial' | 'continue';
  text: string;
  toolCalls: TypedToolCallUnion[];
  toolResults: ToolExecutionResultUnion[];
  response: OpenResponsesNonStreamingResponse;
  usage?: OpenResponsesUsage;
  finishReason?: string;
  warnings?: Warning[];
  experimental_providerMetadata?: Record<string, unknown>;
}

内置辅助函数

函数	签名	说明
stepCountIs	(n: number) => StopCondition	执行 n 轮后停止
hasToolCall	(name: string) => StopCondition	调用指定工具后停止
maxTokensUsed	(n: number) => StopCondition	消耗 n 个 token 后停止
maxCost	(amount: number) => StopCondition	达到费用上限后停止
finishReasonIs	(reason: string) => StopCondition	指定 finish reason 时停止

---

格式转换函数

函数	签名	说明
fromChatMessages	(messages: Message[]) => OpenResponsesInput	OpenAI Chat 格式 → OpenResponses
toChatMessage	(response) => AssistantMessage	OpenResponses 响应 → Chat 格式
fromClaudeMessages	(messages: ClaudeMessageParam[]) => OpenResponsesInput	Anthropic Claude 格式 → OpenResponses
toClaudeMessage	(response) => ClaudeMessage	OpenResponses 响应 → Claude 格式

---

常见问题

Q: model 和 models 有什么区别？

A: model 指定单一模型；models 是降级数组，前一个模型不可用时自动尝试下一个。两者必填其一。

Q: 什么时候用 getText() 而不是 getTextStream()？

A: 不需要实时展示进度时用 getText() 更简洁；有 UI 展示需求或响应较长时用 getTextStream() 可以减少用户等待感知。

Q: ToolWithGenerator 和普通 ToolWithExecute 怎么选？

A: 需要向调用方实时推送工具执行中间状态（如搜索进度、文件处理百分比）时用 ToolWithGenerator；只需最终结果用 ToolWithExecute 即可。