@openrouter/agent 包含自己的 OpenRouter 客户端类，可完全替代 @openrouter/sdk 的 agent 功能。迁移分三步：①替换客户端类导入，②替换子路径导入（可用 sed 脚本自动化），③替换 barrel 导入（from '@openrouter/sdk'）。自动脚本处理子路径，客户端类和对话状态的 barrel 导入需手动替换。替换完成后运行 tsc 验证。

如果你的项目目前使用 @openrouter/sdk 的 agent 功能（callModel、tool()、stop conditions 等），请按本指南迁移到 @openrouter/agent。

迁移前提

如果只用非 agent 功能（client.models.list()、client.credits.get()、client.chat.send()），不需要迁移，继续使用 @openrouter/sdk 即可。

Step 1：替换客户端类

@openrouter/agent 包含自己的 OpenRouter 客户端，可以完全丢弃 @openrouter/sdk 依赖：

- import OpenRouter from '@openrouter/sdk';
- import { callModel } from '@openrouter/sdk/funcs/call-model';
+ import { OpenRouter } from '@openrouter/agent';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});
+
+ const result = client.callModel({
+   model: 'openai/gpt-4o',
+   input: 'Hello',
+ });
+ const text = await result.getText();

也可以从子路径导入：

import { OpenRouter } from '@openrouter/agent/client';

Step 2：替换子路径导入

旧导入路径	新导入路径
@openrouter/sdk/funcs/call-model	@openrouter/agent/call-model
@openrouter/sdk/lib/model-result	@openrouter/agent/model-result
@openrouter/sdk/lib/tool	@openrouter/agent/tool
@openrouter/sdk/lib/tool-types	@openrouter/agent/tool-types
@openrouter/sdk/lib/stop-conditions	@openrouter/agent/stop-conditions
@openrouter/sdk/lib/async-params	@openrouter/agent/async-params

自动迁移脚本（macOS）

find src -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
  -e "s|@openrouter/sdk/funcs/call-model|@openrouter/agent/call-model|g" \
  -e "s|@openrouter/sdk/lib/model-result|@openrouter/agent/model-result|g" \
  -e "s|@openrouter/sdk/lib/tool-types|@openrouter/agent/tool-types|g" \
  -e "s|@openrouter/sdk/lib/tool|@openrouter/agent/tool|g" \
  -e "s|@openrouter/sdk/lib/stop-conditions|@openrouter/agent/stop-conditions|g" \
  -e "s|@openrouter/sdk/lib/async-params|@openrouter/agent/async-params|g"

自动迁移脚本（Linux）

find src -name '*.ts' -o -name '*.tsx' | xargs sed -i \
  -e "s|@openrouter/sdk/funcs/call-model|@openrouter/agent/call-model|g" \
  -e "s|@openrouter/sdk/lib/model-result|@openrouter/agent/model-result|g" \
  -e "s|@openrouter/sdk/lib/tool-types|@openrouter/agent/tool-types|g" \
  -e "s|@openrouter/sdk/lib/tool|@openrouter/agent/tool|g" \
  -e "s|@openrouter/sdk/lib/stop-conditions|@openrouter/agent/stop-conditions|g" \
  -e "s|@openrouter/sdk/lib/async-params|@openrouter/agent/async-params|g"

tool-types 替换在 tool 之前执行，避免部分匹配导致错误。

Step 3：手动替换 Barrel 导入

脚本不处理裸包名导入（from '@openrouter/sdk'），需手动替换。

核心导入

- import { callModel } from '@openrouter/sdk/funcs/call-model';
+ import { callModel } from '@openrouter/agent/call-model';

- import { ModelResult } from '@openrouter/sdk/lib/model-result';
+ import { ModelResult } from '@openrouter/agent/model-result';

- import { tool } from '@openrouter/sdk/lib/tool';
+ import { tool } from '@openrouter/agent/tool';

Stop conditions

- import {
-   stepCountIs,
-   hasToolCall,
-   maxCost,
- } from '@openrouter/sdk/lib/stop-conditions';
+ import {
+   stepCountIs,
+   hasToolCall,
+   maxCost,
+ } from '@openrouter/agent/stop-conditions';

对话状态和消息格式

- import {
-   createInitialState,
-   updateState,
-   fromClaudeMessages,
-   fromChatMessages,
- } from '@openrouter/sdk';
+ import {
+   createInitialState,
+   updateState,
+   fromClaudeMessages,
+   fromChatMessages,
+ } from '@openrouter/agent';

Step 4：验证构建

npx tsc --noEmit
npm test

搜索代码库中剩余的 from '@openrouter/sdk'（不带 / 子路径），找到需要手动更新的 barrel 和客户端导入。

常见问题

Q: 迁移后还需要保留 @openrouter/sdk 吗？

A: 只有在使用非 agent REST API 功能（client.models.list()、client.credits.get()、client.chat.send()）时才需要保留。如果代码只用 callModel、工具和 agent 客户端，可以完全移除 @openrouter/sdk。

Q: 两个包可以同时使用吗？

A: 可以。两个包设计为可以并存：

import OpenRouter from '@openrouter/sdk';
import { callModel } from '@openrouter/agent/call-model';
import { tool } from '@openrouter/agent/tool';

Q: 旧的导入还能用多久？

A: agent 导出会在未来某个主版本从 @openrouter/sdk 中移除。建议尽早迁移，避免日后遇到破坏性变更。