> ## 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="固定モデル" />

## 固定モデル

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

```python theme={null}
from qoder_agent_sdk import query, QoderAgentOptions

options = QoderAgentOptions(model="performance")

async for msg in query(prompt="Analyze this code", options=options):
    print(msg)
```

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

## 動的選択

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

```python theme={null}
from qoder_agent_sdk import query, QoderAgentOptions
from qoder_agent_sdk.types import ModelPolicyContext, ModelPolicyResult, ModelPolicyProvider

resolve_model: ModelPolicyProvider = lambda context: {"model": "performance"}

options = QoderAgentOptions(resolve_model=resolve_model)

async for msg in query(prompt="Analyze this code", options=options):
    print(msg)
```

コールバックの入力からは、今回のリクエストの用途、セッション情報、現在利用可能なモデルリストを読み取れます。

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

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

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

```python theme={null}
def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    match context.get("purpose"):
        case "main":     return {"model": "performance"}
        case "subagent": return {"model": "efficient"}
        case "compact":  return {"model": "lite"}
        case _:          return {"model": "auto"}
```

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

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

### タイムアウト

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

```python theme={null}
options = QoderAgentOptions(
    resolve_model=resolve_model,
    resolve_model_timeout_ms=800,
)
```

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

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

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

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

```python theme={null}
import os

def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    return {
        "model": {
            "provider": "bailian",
            "model": "qwen3.5-plus-cp",
            "api_key": os.environ["MY_API_KEY"],
        },
    }
```

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

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

## ランタイム操作

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

```python theme={null}
from qoder_agent_sdk import query, QoderAgentOptions

options = QoderAgentOptions(...)

async with QoderSDKClient(options=options) as client:
    models = await client.get_available_models()
    for m in models:
        print(f"{m['value']}\t{m['displayName']}\t{m.get('isEnabled', True)}")
```

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

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

<div id="error-handling" />

## エラー処理

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

```python theme={null}
async def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    try:
        policy = await fetch_remote_policy(context)
        return {"model": policy["model"]}
    except Exception:
        return {"model": "auto"}  # fallback, must be non-empty
```

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