OpenRouter Agent SDK：callModel 完整 API 参考

本页是 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 和 models 二选一必填。

ProviderPreferences #

RequestOptions #

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 #

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>;
}

内置辅助函数 #

格式转换函数 #

常见问题 #

Q: model 和 models 有什么区别？

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

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

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

Q: ToolWithGenerator 和普通 ToolWithExecute 怎么选？

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