Model Selection

query() offers two model-selection modes:

Fixed model (default): the entire session uses one model.
Dynamic selection: a callback is called before every LLM request to return the model. You can route by purpose (main conversation, sub-agent, context compaction, etc.) or return a BYOK credential to use your own API key.

The two modes are mutually exclusive: passing a callback switches to dynamic-selection mode and the fixed-model setting is ignored.

Fixed model

Specify it via the model option; omit to use the account default:

from qoder_agent_sdk import query, QoderAgentOptions

options = QoderAgentOptions(model="performance")

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

Dynamic selection

Provide a callback function that is invoked before every LLM request:

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)

The callback receives the request's purpose, session info, and the list of currently available models.

Routing by purpose

Use a different model per purpose:

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

Purposes cover scenarios like main conversation, sub-agent, context compaction, WebFetch, and image generation. For the full list, see SDK References.

Returning model parameters

Return parameters with the selected model to override the context window and thinking depth for that LLM request. These keys are camelCase at the SDK control boundary:

def resolve_model(context: ModelPolicyContext) -> ModelPolicyResult:
    return {
        "model": "ultimate",
        "parameters": {
            "contextWindow": 200000,
            "reasoningEffort": "high",
        },
    }

Choose values supported by the selected model. The available context-window and thinking-effort metadata is exposed on context["availableModels"] through ModelInfo.context_config and ModelInfo.thinking_config.

Timeout

The callback has a default timeout (in milliseconds). Increase it when the callback performs remote I/O:

options = QoderAgentOptions(
    resolve_model=resolve_model,
    resolve_model_timeout_ms=800,
)

BYOK: use your own API key

The callback can also return a BYOK credential object — that request will be routed to a third-party provider:

import os

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

The available provider/model catalog can be fetched via runtime methods, so the front-end can render selectors and an API-key input.

Runtime operations

While a session is running you can fetch the account's currently available model list:

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)}")

You can also switch the current model in fixed-model mode, or fetch the BYOK provider catalog. For specific method signatures, see SDK References.

Error handling

Dynamic-selection mode has no automatic fallback — a callback that times out, throws, or returns an empty model causes the query to fail. Handle errors inside the callback:

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

For full field and type definitions, see SDK References.

​Fixed model

​Dynamic selection

​Routing by purpose

​Returning model parameters

​Timeout

​BYOK: use your own API key

​Runtime operations

​Error handling