openrouter-agent-migration

@openrouter/sdk から @openrouter/agent への移行

エージェント機能（callModel、tool()、停止条件、フォーマット変換関数、ストリーミングヘルパー）は、@openrouter/sdk から独立したパッケージである @openrouter/agent に移動しました。@openrouter/agent パッケージには独自の OpenRouter クライアントクラスが含まれているため、エージェントのユースケースでは @openrouter/sdk は必要ありません。

---

対象となるケース

コードで @openrouter/sdk から次のいずれかをインポートしている場合は、移行してください。

• callModel をインポートしている、または client.callModel() を使用している
• tool() ファクトリー関数
• 停止条件：stepCountIs、hasToolCall、maxCost、maxTokensUsed、finishReasonIs
• フォーマット変換関数：fromClaudeMessages、toClaudeMessage、fromChatMessages、toChatMessage
• 型：Tool、ToolWithExecute、ToolWithGenerator、ManualTool、CallModelInput、ModelResult

---

簡単な移行手順

手順 1：インストール

npm install @openrouter/agent

エージェント機能のみを使用する場合は、@openrouter/sdk を削除できます。

npm uninstall @openrouter/sdk
npm install @openrouter/agent

エージェント以外の SDK 機能（モデル一覧、チャット補完、クレジット、OAuth、API キー）も使用する場合は、両方のパッケージをインストールしたままにしてください。

手順 2：インポートを更新

OpenRouter クライアントクラスと client.callModel() のパターンは、これまでと同じように動作します。変更するのはインポート元だけです。

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

それ以外のコードはそのままです。

const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const result = client.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Hello!',
});

const text = await result.getText();

---

インポートの完全な対応表

クライアントと callModel

旧	新
import OpenRouter from '@openrouter/sdk'	import { OpenRouter } from '@openrouter/agent'
import OpenRouter, { tool, stepCountIs } from '@openrouter/sdk'	import { OpenRouter } from '@openrouter/agent' import { tool } from '@openrouter/agent/tool' import { stepCountIs } from '@openrouter/agent/stop-conditions'

既存の OpenRouterCore インスタンスを利用できる高度なユースケース向けに、独立した callModel 関数も用意されています。

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

// Requires an OpenRouterCore instance (from @openrouter/sdk/core)
const result = callModel(coreInstance, { model: 'openai/gpt-5-nano', input: 'Hello' });

ほとんどのユースケースでは、上記の client.callModel() メソッドを使用してください。

ツールの作成

旧	新
import { tool } from '@openrouter/sdk'	import { tool } from '@openrouter/agent/tool'

停止条件

旧	新
import { stepCountIs, hasToolCall, maxCost } from '@openrouter/sdk'	import { stepCountIs, hasToolCall, maxCost } from '@openrouter/agent/stop-conditions'
import { maxTokensUsed, finishReasonIs } from '@openrouter/sdk'	import { maxTokensUsed, finishReasonIs } from '@openrouter/agent/stop-conditions'

型

旧	新
import type { Tool, ToolWithExecute, ToolWithGenerator, ManualTool } from '@openrouter/sdk/lib/tool-types'	import type { Tool, ToolWithExecute, ToolWithGenerator, ManualTool } from '@openrouter/agent/tool-types'
import type { CallModelInput } from '@openrouter/sdk/lib/async-params'	import type { CallModelInput } from '@openrouter/agent/async-params'
import { ModelResult } from '@openrouter/sdk/lib/model-result'	import { ModelResult } from '@openrouter/agent/model-result'

フォーマット変換関数

旧	新
import { fromClaudeMessages, toClaudeMessage } from '@openrouter/sdk'	import { fromClaudeMessages, toClaudeMessage } from '@openrouter/agent'
import { fromChatMessages, toChatMessage } from '@openrouter/sdk'	import { fromChatMessages, toChatMessage } from '@openrouter/agent'

型ガード

旧	新
import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from '@openrouter/sdk'	import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from '@openrouter/agent/tool-types'

---

移行前と移行後の例

移行前（@openrouter/sdk を使用）

import OpenRouter, { tool, stepCountIs, hasToolCall } from '@openrouter/sdk';
import { z } from 'zod';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const searchTool = tool({
  name: 'web_search',
  description: 'Search the web',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ results: z.array(z.string()) }),
  execute: async ({ query }) => {
    return { results: ['Result 1', 'Result 2'] };
  },
});

const finishTool = tool({
  name: 'finish',
  description: 'Complete the task',
  inputSchema: z.object({ answer: z.string() }),
  execute: async ({ answer }) => ({ answer }),
});

const result = client.callModel({
  model: 'openai/gpt-5-nano',
  instructions: 'You are a research assistant.',
  input: 'What are the latest AI developments?',
  tools: [searchTool, finishTool],
  stopWhen: [stepCountIs(10), hasToolCall('finish')],
});

const text = await result.getText();

移行後（@openrouter/agent を使用）

import { OpenRouter } from '@openrouter/agent';
import { tool } from '@openrouter/agent/tool';
import { stepCountIs, hasToolCall } from '@openrouter/agent/stop-conditions';
import { z } from 'zod';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const searchTool = tool({
  name: 'web_search',
  description: 'Search the web',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ results: z.array(z.string()) }),
  execute: async ({ query }) => {
    return { results: ['Result 1', 'Result 2'] };
  },
});

const finishTool = tool({
  name: 'finish',
  description: 'Complete the task',
  inputSchema: z.object({ answer: z.string() }),
  execute: async ({ answer }) => ({ answer }),
});

const result = client.callModel({
  model: 'openai/gpt-5-nano',
  instructions: 'You are a research assistant.',
  input: 'What are the latest AI developments?',
  tools: [searchTool, finishTool],
  stopWhen: [stepCountIs(10), hasToolCall('finish')],
});

const text = await result.getText();

変更点は、先頭にある 3 行のインポートのみです。

---

@openrouter/sdk を引き続き使用する場合

以下のエージェント以外の機能を使用する場合は、@openrouter/sdk をインストールしたままにしてください。

機能	アクセス
モデル一覧	client.models.list()
チャット補完	client.chat.send()
レガシー補完	client.completions.generate()
使用状況の分析	client.analytics.getUserActivity()
クレジット残高	client.credits.getCredits()
API キー管理	client.apiKeys.list()、.create() など
OAuth PKCE フロー	client.oAuth.createAuthCode()、.exchangeAuthCodeForAPIKey()

複数の機能を組み合わせたプロジェクトでは、これらの機能に @openrouter/sdk を、エージェント機能に @openrouter/agent を使用してください。

import OpenRouter from '@openrouter/sdk';               // SDK client for models, credits, etc.
import { OpenRouter as Agent } from '@openrouter/agent'; // Agent client for callModel
import { tool } from '@openrouter/agent/tool';
import { stepCountIs } from '@openrouter/agent/stop-conditions';

// Use SDK client for non-agent features
const sdkClient = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const models = await sdkClient.models.list();
const credits = await sdkClient.credits.getCredits();

// Use Agent client for callModel
const agent = new Agent({ apiKey: process.env.OPENROUTER_API_KEY });
const result = agent.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Hello!',
  tools: [myTool],
  stopWhen: stepCountIs(5),
});

---

@openrouter/agent の新機能

以下の機能は @openrouter/agent でのみ利用でき、@openrouter/sdk では利用できません。

共有コンテキストスキーマ

会話内のすべてのツールで共有する、型安全な状態です。

import { OpenRouter } from '@openrouter/agent';
import { z } from 'zod';

const client = new OpenRouter({ apiKey: '...' });

const result = client.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Process this data',
  sharedContextSchema: z.object({
    userId: z.string(),
    sessionData: z.record(z.unknown()),
  }),
  context: {
    shared: { userId: '123', sessionData: {} },
  },
  tools: [myTool],
});

ツールコンテキスト

ツールは独自の型付きコンテキストを宣言し、共有コンテキストにアクセスできます。

import { tool } from '@openrouter/agent/tool';
import { z } from 'zod';

const myTool = tool({
  name: 'my_tool',
  description: 'A tool with context',
  inputSchema: z.object({ query: z.string() }),
  contextSchema: z.object({ apiKey: z.string() }),
  execute: async (params, context) => {
    // context.local — this tool's own context
    // context.shared — shared context across all tools
    // context.setContext({ ... }) — update this tool's context
    // context.setSharedContext({ ... }) — update shared context
    return { result: 'done' };
  },
});

ツール承認フロー

ツールの実行前にユーザーの承認を必須にします。

const dangerousTool = tool({
  name: 'delete_file',
  description: 'Delete a file',
  inputSchema: z.object({ path: z.string() }),
  requireApproval: true, // or a function: (toolCall, context) => boolean
  execute: async ({ path }) => { /* ... */ },
});

ターンのライフサイクルコールバック

const result = client.callModel({
  model: 'openai/gpt-5-nano',
  input: 'Complex task',
  tools: [myTool],
  onTurnStart: async (context) => {
    console.log(`Starting turn ${context.numberOfTurns}`);
  },
  onTurnEnd: async (context, response) => {
    console.log(`Turn ${context.numberOfTurns} complete`);
  },
});

---

すべてのサブパスエクスポート

@openrouter/agent は、細かく指定できるサブパスインポートを提供します。

サブパス	エクスポート
@openrouter/agent	バレル：以下のすべてのエクスポート
@openrouter/agent/client	OpenRouter クラス
@openrouter/agent/call-model	callModel スタンドアロン関数
@openrouter/agent/tool	tool() ファクトリー関数
@openrouter/agent/tool-types	Tool、ToolWithExecute、ToolWithGenerator、ManualTool、型ガード
@openrouter/agent/stop-conditions	stepCountIs、hasToolCall、maxCost、maxTokensUsed、finishReasonIs
@openrouter/agent/model-result	ModelResult レスポンスラッパー
@openrouter/agent/async-params	CallModelInput、hasAsyncFunctions、resolveAsyncFunctions
@openrouter/agent/anthropic-compat	fromClaudeMessages、toClaudeMessage
@openrouter/agent/chat-compat	fromChatMessages、toChatMessage
@openrouter/agent/conversation-state	createInitialState、updateState、appendToMessages
@openrouter/agent/next-turn-params	nextTurnParams ユーティリティ
@openrouter/agent/stream-transformers	extractUnsupportedContent、getUnsupportedContentSummary
@openrouter/agent/tool-context	buildToolExecuteContext、ToolContextStore
@openrouter/agent/tool-event-broadcaster	ToolEventBroadcaster
@openrouter/agent/turn-context	buildTurnContext