Choose and change models

The model is ai.model in each agent’s YAML, as <provider>/<model_id>.

You need: a recipe (Define agents) and, for your own key, a CLI login (the member role is enough).

1. Set the model in the recipe

name: agent
ai:
  model: anthropic/<model>
  thinking_level: medium   # off | minimal | low | medium | high | xhigh | max

2. Choose whose key pays

name: support-agent
path: .
runtime:
  llm_mode: byok

The mode applies from the next version built after you merge.

byok covers the agent’s calls and live judges; a judge calls the provider in its llm block, so bind an llm endpoint for that host too. Observation extraction always uses Introspection’s gateway; contact us to turn it off.

3. Add your key (byok only)

Store the key as a credential, then add an llm endpoint for the provider’s host. The provider prefix in ai.model picks the host.

introspection bindings credentials create --name ANTHROPIC_API_KEY --from-env ANTHROPIC_API_KEY -r support-agent
introspection bindings endpoints create --kind llm --name anthropic \
  --endpoint-url https://api.anthropic.com \
  --header 'x-api-key=${ANTHROPIC_API_KEY}' -r support-agent

Tune requests and caching

The ai block passes through to pi-ai, the model library under the Pi  runtime; the runtime runs pi 1.1, so use the options pi-ai 1.1 accepts. ai.options takes pi-ai’s request options in snake_case: each top-level key becomes pi-ai’s camelCase option (cache_retention becomes cacheRetention) and its value is passed unchanged, so a pi-ai option works without waiting for a Recipes release. ai.providers carries provider-specific settings.

name: agent
ai:
  model: anthropic/<model>
  thinking_level: medium
  options:
    cache_retention: long   # none | short (5 min) | long (1 h)
    max_tokens: 8192
    temperature: 0.2
    timeout_ms: 120000

The runtime owns credentials and transport, so an agent file that sets any of these fails: api_key, bearer_token, headers, env, fetch, signal, session_id, region, project, location, the azure_* keys, or reasoning (use thinking_level). Option keys must be snake_case.

An agent with from: merges options and providers by key over its base, until it declares its own ai.model: then its ai block starts fresh.

Run another model for one task

metadata.model and metadata.thinking_level override the recipe for that task’s main agent. Subagents keep their own model.

introspection tasks create -r support-agent -e staging --prompt "Summarize ticket 42" \
  --metadata '{"model":"anthropic/<other-model>","thinking_level":"high"}'

Run another model in staging

Verify

introspection tasks create -r support-agent -e staging --prompt "Say hello"
introspection conversations get <task-id>

Expect the new model on the conversation’s model calls, also shown in Conversations.

Or ask your agent: “Switch support-agent to my own Anthropic key.”

Limits