> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# モデル選択

`query()` には 2 つのモデル選択モードがあります：

* **固定モデル（デフォルト）**：セッション全体で 1 つのモデルを使用します。
* **動的選択**：LLM リクエストごとにコールバック関数を呼び出してモデルを返します。用途（メイン会話、サブエージェント、コンテキスト圧縮など）に応じて異なるモデルにルーティングしたり、BYOK 認証情報を返して自分の API キーを使うことができます。

2 つのモードは排他的です：コールバックを渡すと動的選択モードに切り替わり、固定モデル設定は無視されます。

<div id="固定モデル" />

## 固定モデル

モデルオプションで指定します。省略するとアカウントのデフォルトが使われます：

```typescript theme={null}
import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Analyze this code',
  options: {
    auth: qodercliAuth(),
    model: 'performance',
  },
});
```

<div id="動的選択" />

## 動的選択

LLM リクエストごとに呼び出されるコールバック関数を提供します：

```typescript theme={null}
import { qodercliAuth, query, type ModelPolicyProvider } from '@qoder-ai/qoder-agent-sdk';

const resolveModel: ModelPolicyProvider = (context) => {
  return { model: 'performance' };
};

const q = query({
  prompt: 'Analyze this code',
  options: {
    auth: qodercliAuth(),
    resolveModel,
  },
});
```

コールバックの入力にはリクエストの用途、セッション情報、および現在利用可能なモデルリストが含まれます。

<div id="用途別のルーティング" />

### 用途別のルーティング

用途ごとに異なるモデルを使用します：

```typescript theme={null}
const resolveModel: ModelPolicyProvider = (context) => {
  switch (context.purpose) {
    case 'main':       return { model: 'performance' };
    case 'subagent':   return { model: 'efficient' };
    case 'compact':    return { model: 'lite' };
    default:           return { model: 'auto' };
  }
};
```

用途はメイン会話、サブエージェント、コンテキスト圧縮、WebFetch、画像生成などのシナリオをカバーします。完全な値については [SDK References](/ja/cli/sdk/references) を参照してください。

<div id="モデルパラメータを返す" />

### モデルパラメータを返す

選択したモデルと一緒に `parameters` を返すと、この LLM リクエストのコンテキストウィンドウと思考の深さを上書きできます。これらのキーは SDK 制御境界では camelCase です：

```typescript theme={null}
const resolveModel: ModelPolicyProvider = (context) => {
  return {
    model: 'ultimate',
    parameters: {
      contextWindow: 200000,
      reasoningEffort: 'high',
    },
  };
};
```

選択したモデルがサポートする値を指定してください。利用可能なコンテキストウィンドウと思考 effort のメタデータは、`context.availableModels` の `ModelInfo.context_config` と `ModelInfo.thinking_config` で確認できます。

<div id="タイムアウト" />

### タイムアウト

コールバックにはデフォルトのタイムアウト（ミリ秒単位）があります。コールバックがリモート I/O を行う場合は緩和できます：

```typescript theme={null}
{ resolveModel, resolveModelTimeoutMs: 800 }
```

<div id="byok自分の-api-キーを使用" />

### BYOK：自分の API キーを使用

コールバックは BYOK 認証情報オブジェクトを返すこともできます——このリクエストはサードパーティのプロバイダーにルーティングされます：

```typescript theme={null}
const resolveModel: ModelPolicyProvider = () => ({
  model: {
    provider: 'bailian',
    model: 'qwen3.5-plus-cp',
    api_key: process.env.MY_API_KEY!,
  },
});
```

利用可能なプロバイダー / モデルのカタログはランタイムメソッドで取得でき、フロントエンドはこれを使って選択 UI と API キー入力フィールドをレンダリングできます。

<div id="ランタイム操作" />

## ランタイム操作

セッション実行中にアカウントで現在利用可能なモデルリストを取得できます：

```typescript theme={null}
import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: '...',
  options: { auth: qodercliAuth() },
});

const models = await q.getAvailableModels();
for (const m of models) {
  console.log(`${m.value}\t${m.displayName}\t${m.isEnabled ?? true}`);
}
```

また、固定モデルモードで現在のモデルを切り替えたり、BYOK プロバイダーカタログを取得したりすることもできます。具体的なメソッドシグネチャは [SDK References](/ja/cli/sdk/references) を参照してください。

<div id="エラー処理" />

## エラー処理

動的選択モードには**自動フォールバックがありません**——コールバックのタイムアウト、例外、空モデルの返却はすべてクエリを失敗させます。コールバック内部で自前にフォールバックすることを推奨します：

```typescript theme={null}
const resolveModel: ModelPolicyProvider = async (context) => {
  try {
    const policy = await fetchRemotePolicy(context);
    return { model: policy.model };
  } catch {
    return { model: 'auto' };   // フォールバック、空にしてはいけない
  }
};
```

完全なフィールド・型定義は [SDK References](/ja/cli/sdk/references) を参照してください。