Envelope

Model routing

Envelope automatically selects the right AI model for each agent in your team. You don't have to think about it — but you can override any agent's model conversationally when you want a different trade-off.

How it works

When you create a team, each agent needs a model to run on. Rather than asking you to pick one, Envelope reads the agent's role description and its position in the team hierarchy and picks a sensible default from a set of tiered options.

The result: your orchestrating analyst gets a capable frontier model; your formatting agent that cleans up output gets a fast efficient one. Same team, different spend per agent, better overall quality-to-cost ratio.

Tiers and models

| Tier | Model | When it fires | |---|---|---| | Reasoning | o4-mini | Role contains words like verify, validate logic, chain of thought, multi-step | | Frontier | gpt-5.4 | Root orchestrators, analysts, senior/principal agents, agents that plan, decide, review, or synthesise | | Balanced | claude-sonnet-4-5 | Default for agents with no strong signal — the safest middle ground | | Efficient | gpt-5-mini | Agents that classify, triage, route, extract, format, summarise | | Fast | gpt-5-nano | Agents that label, tag, sort, rank, filter, or detect — simple, high-volume work |

Hierarchy fallback: if the role doesn't match any keyword pattern, root agents (no supervisor) default to Frontier and leaf agents (report to someone) default to Efficient.

Reading the model in Observability

After a run, open the Observability tab and look at the By Agent table. Each row shows which model ran for that agent and whether it was auto-routed or manually set.

  • Muted pill — model was chosen automatically by routing
  • Blue pill — model was set manually via a chat override

This gives you a clear view of where money is being spent and whether the routing choices look right for your team.

Overriding a model

Say something in the room thread. The assistant maps what you say to a concrete model and persists the override for all future runs — no settings panel, no JSON editing.

Common phrases:

  • "Switch the researcher to a faster model" → sets gpt-5-mini
  • "Make the analyst smarter" → sets gpt-5.4
  • "Use Claude Opus for the writer" → sets claude-opus-4-5
  • "Put the formatter on the cheapest model" → sets gpt-5-nano
  • "Give the planner a reasoning model" → sets o4-mini
  • "Reset the writer back to auto" → clears the override, routing takes over again

The override is per-agent, per-install — so if you have multiple installs of the same team template, each can have its own model choices.

Note: Per-agent overrides are currently workspace-only — there is no API endpoint for setting a model per agent programmatically. If you are installing via the API and want to override the model for all agents at once, you can pass a model field at install time: POST /installs with "model": "openai:gpt-5-mini". This sets the same model across every agent in the install. For per-agent control, use the room thread.

Available models for overrides

| Model | Provider | Good for | |---|---|---| | gpt-5.4 | OpenAI | Best general quality — analysis, synthesis, complex reasoning | | claude-opus-4-5 | Anthropic | Frontier alternative — similar quality with a different voice | | claude-sonnet-4-5 | Anthropic | Balanced — strong quality, lower cost | | gpt-5-mini | OpenAI | Efficient — classification, extraction, formatting | | claude-haiku-4-5 | Anthropic | Efficient alternative — fast and cheap | | gpt-5-nano | OpenAI | Fastest/cheapest — labels, tags, simple decisions | | o4-mini | OpenAI | Reasoning — verification, multi-step logic | | o3 | OpenAI | Heavy reasoning — complex long-horizon tasks |

When to override vs let it auto-route

Auto-routing is right for most teams. The cases where you'd want to override:

Override to frontier when:

  • The default choice isn't handling nuance well — output quality is low
  • The agent is doing genuine synthesis across large amounts of context
  • A leaf agent is being asked to do surprisingly complex work

Override to efficient when:

  • A root agent is doing a simple, well-defined task (e.g. a single-agent email sender)
  • You're running at high volume and cost matters
  • You've validated the output quality and want to optimise

Override to reasoning when:

  • The agent is doing multi-step verification or structured planning
  • You're seeing logical errors in output that more powerful generation doesn't fix

Reset to auto when:

  • You made an override during testing and want routing to take back over
  • You updated the agent's role and want routing to re-evaluate

Existing teams

Teams created before model routing was introduced have explicit model fields in their definition — routing doesn't fire for those agents. If you want them to use auto-routing, ask the assistant to "reset the model for [agent] back to auto" in the room thread.

‹ All guidesDocs ›