Agents
Identity, models, tools, schedule, and voice — everything an agent is configured with.
An agent is the thing users chat with. The editor configures who it is, what it runs on, what it can do, when it runs on its own, and who may use it. Model settings sit behind the gear icon; publishing lives on the agent's Channels page.
Start blank or from the Templates tab on the Agents page — a template only pre-fills the create form, and what you save is an ordinary agent.
Models
| Setting | What it does |
|---|---|
| Models | The models users may pick in chat (aiModel.names). At least one. |
| Default model | Where new chats start. Must be one of the models above. |
| Fast model | A cheap model for short opening questions (Tier 1, below). Unset turns Tier 1 off. |
| Sub-agent model | The model every subagent of this agent runs on. Default: Same as main agent. |
| Temperature | 0–2. Omitted automatically for reasoning models that reject it. |
| Model selector enabled | On by default. Off pins every chat to the default model. |
The fast and sub-agent models are deliberately not limited to the agent's model list — the point is a cheaper model users never pick directly. A chat request naming a model outside the list is refused with a 400.
Turn tiers
Before any model runs, each turn is routed to the cheapest tier that can
handle it. The tier is tagged on the trace (tier:0, tier:1, tier:2).
| Tier | When | What runs |
|---|---|---|
| 0 | A bare thank-you or acknowledgement on any turn, or a bare greeting as the first message (English, Spanish, French, German, Vietnamese) | A canned reply — no model, tools, or retrieval |
| 1 | A short first-message question (one line, up to 160 characters, ending in ? or starting with an English question word) and a fast model is set | The fast model |
| 2 | Everything else, including attachments and approval resumes | The full turn on the chat's model |
A guardrail or turn hook refusal always wins over a Tier-0 reply.
Identity and output
- Instructions — the system prompt: role, tone, ground rules.
- Description — what the agent is for. Also the tool description a parent sees when this agent is mounted as a subagent.
- Transcript mode (
transcriptMode) —normalshows the answer plus results of tools set to show one;verbosespells out every tool call;thinkingadds the model's reasoning when the provider returns it. - Output format —
text(default) orjsonwith a JSON Schema (outputDefinition) the reply must match. A chat request can override both per turn withoutput.
sendSources (default on, API only) controls whether scheduled and
trigger-fired runs attach knowledge citations to the reply; chat requests set
this per turn instead (see Chat & threads).
Tools, skills, and integrations
- Toolbox — the agent's
toolslist: shared tools from the registry, tools created inline, knowledge search, and the built-inshandoff,memory, anddelegate_task. Entries can be disabled without deleting them. Linked and derived subagents are entries here too. - Skills — a separate
skillslist of skills. - Integrations — connected apps and MCP servers (
mcpServers, each with its own per-agent on/off switch). See Integrations.
Schedule
Under Triggers, a schedule runs the agent on its own:
| Mode | Settings |
|---|---|
| Daily | Time |
| Weekly | Day of week and time |
| Monthly | Day of month and time |
| Advanced | A 5-field cron expression |
Times are in the organization's timezone (Settings → Organization). A schedule runs at most once every 15 minutes. Prompt is the message each run sends; leave it empty for a default start prompt. Runs go through the background queue. The same section holds app triggers — see Integrations.
Voice
Voice talking (in the model settings) lets people hold a live voice conversation with the agent. Turning it on requires a voice model:
| Provider | Models | Voices |
|---|---|---|
| OpenAI | GPT Realtime 2.1, GPT Realtime 2.1 Mini | alloy, ash, ballad, coral, echo, sage, shimmer, verse |
| Gemini 3.8 Live, Gemini 3.8 Live Extended Thinking | Aoede, Charon, Fenrir, Kore, Puck, Zephyr |
The voice is optional (provider default otherwise). The browser gets a
short-lived session from POST /agents/:id/voice-sessions and talks to the
provider directly; the session carries the agent's instructions but no tools.
- Not on the Free plan; billed to the agent's organization, whoever is talking.
- Served with the platform's own OpenAI or Google key — providers you add under Model providers don't serve voice.
- The session endpoint 404s when voice is off and is rate-limited like chat.
Hooks
Turn hooks are code that runs before the model's turn — a beforeTurn hook
under Turn code for fetching context, grounding the prompt, or refusing
the turn. See Turn hooks.
Sharing
An agent's audience decides who can chat with it. Capabilities inherit from it: attaching a tool to an agent never widens who may use that tool beyond the agent's own audience. Shared tools, skills, apps, and MCP servers can narrow further with their own sharing.