Skip to content
CengridCengridCengrid Docs

Models for agents

Most agents should simply use the conversation’s model. Give an agent its own model when a specialist needs a stronger reasoner, a cheaper model for bulk work, or tighter generation settings.

Three ways to write the model

Section titled “Three ways to write the model”
AGENT.md frontmatter
---
name: data-analyst
description: Generate SQL and analyze datasets.
model:
  provider: anthropic
  name: claude-sonnet-5
---
Form Meaning
model: inherit Run on the conversation’s model, whatever it is when the agent runs. Takes no other settings.
model: <name> A plain model name. Still supported for existing agents. This is the only form that falls back to the conversation’s model when its model is unusable.
model: mapping provider and name (both required), plus optional temperature, max_tokens and parameters. Any other key is rejected.

A plugin whose manifest is a root plugin.json must name a model for each agent, either the mapping form or a plain name, and cannot use inherit. Agents created in the console or shipped by a deployment layer may use inherit. A short alias such as sonnet does not resolve, and an agent that names a model your deployment cannot use rejects its whole plugin until it is fixed.

Limits and checks

Section titled “Limits and checks”
  • provider must match the resolved model’s provider.
  • temperature must be between 0 and 2, or between 0 and 1 for Anthropic models. It is rejected for reasoning models and for providers other than Anthropic, OpenAI or a catalogue-verified OpenRouter endpoint. Where support is unverified, omit it.
  • max_tokens must be a positive integer within the model’s output limit. It can include reasoning tokens.
  • parameters passes extra provider request fields. It cannot contain core request keys such as model, messages, tools, system, tool_choice, stream, metadata, input, instructions, prompt or n, nor temperature and token-limit names. On Pi, reasoning and speed keys such as effort, model_reasoning_effort and speed are rejected too. It is limited to 32 keys, 4,096 JSON characters and a depth of 8. Base model parameters follow the same rules.

Settings are validated against the provider metadata Cengrid already fetches and the model metadata from the Pi SDK, not a hand-maintained per-model table. OpenRouter’s reported supported_parameters are kept, and a configured request needs an endpoint that supports its parameters. Metadata cannot describe every combination, so provider errors stay visible.

How a turn resolves an agent’s model

Section titled “How a turn resolves an agent’s model”

Each workflow step and later turn uses its own agent’s settings, and an agent’s model override never inherits another agent’s sampling settings.

  • If the agent uses the mapping form, which always carries a provider, and its model is unusable, the turn fails.
  • If the agent uses a plain model: <name> and it is unusable, Cengrid logs a warning and falls back to the conversation’s model.
  • After an agent’s model has failed earlier in a thread, the agent runs on the conversation’s model.
  • Explicit output limits remain ceilings, even when the runtime adjusts its default output budget.

The built-in __planner__ and __default__ agents have no model and always run on the conversation’s model.