Models & Providers

tama uses a role-based model system that decouples agent definitions from specific model choices.

Roles

Instead of hardcoding model names in agents, you define roles:

# in AGENT.md
call:
  model:
    role: thinker

Then map roles to models:

# env var (runtime)
export TAMA_MODEL_THINKER=anthropic:claude-opus-4-6

# tama.toml (project defaults)
[models]
thinker = "anthropic:claude-opus-4-6"
writer  = "anthropic:claude-sonnet-4-6"
fast    = "anthropic:claude-haiku-4-5"

Environment variables take priority over tama.toml.

Direct model override

Skip roles and specify a model directly in an agent:

call:
  model:
    name: anthropic:claude-opus-4-6

When both role and name are present, name wins.

Model format

All models use provider:model-id format:

anthropic:claude-opus-4-6
openai:gpt-4o
google:gemini-2.0-flash

Supported providers

Anthropic

export ANTHROPIC_API_KEY=sk-ant-...

Model	ID
Claude Opus 4.6	`anthropic:claude-opus-4-6`
Claude Sonnet 4.6	`anthropic:claude-sonnet-4-6`
Claude Haiku 4.5	`anthropic:claude-haiku-4-5`

OpenAI

export OPENAI_API_KEY=sk-...

Model	ID
GPT-4o	`openai:gpt-4o`
GPT-4o mini	`openai:gpt-4o-mini`

Google

export GEMINI_API_KEY=...

Model	ID
Gemini 2.0 Flash	`google:gemini-2.0-flash`
Gemini 2.0 Pro	`google:gemini-2.0-pro`

Temperature and max_tokens

Configure at the agent level or per-step:

call:
  model:
    role: writer
    temperature: 0.9    # 0.0 (deterministic) to 1.0 (creative)
    max_tokens: 4096

<!-- In a step file -->
---
call:
  model:
    role: thinker
    temperature: 0.0    # deterministic for this step only
---

Hyphen-to-underscore mapping

Role names with hyphens map to env vars with underscores:

Role	Env var
`thinker`	`TAMA_MODEL_THINKER`
`my-fast`	`TAMA_MODEL_MY_FAST`
`code-writer`	`TAMA_MODEL_CODE_WRITER`

Recommended role conventions

These aren’t required, but make multi-model projects easier to manage:

Role	Intended use	Example model
`thinker`	Complex reasoning, main agents	claude-opus-4-6
`writer`	Creative writing, drafting	claude-sonnet-4-6
`fast`	Simple tasks, step functions	claude-haiku-4-5
`judge`	Evaluation and selection	claude-opus-4-6