AI agents
An agent is one configured way of answering: a model, a set of instructions, and a list of tools it may use. A bot can have several, and something has to decide which one takes each message.
Agents are configuration, not features
There is no fixed catalogue of agents that ships with Mesa. An agent is a row in your deployment's database, versioned, edited through the admin console. Adding one is a configuration change, not an upgrade — and the set of agents you have is whatever your deployment has defined.
So there is no list here of "the built-in agents", because there isn't one. A fresh development install seeds five examples — a web search agent, an image generator, a code interpreter, a JSONata expression generator and a dad-jokes agent — purely so a developer has something to run against. Those are sample data, not the product.
To see the agents you actually have, open Agents → Definitions in the admin console. To create or change one, see Authoring agent definitions.
How a message reaches an agent
Each bot has a route specification listing its possible targets and how to choose between them. There are three ways to choose, and which one applies is part of that specification:
| Method | How it decides |
|---|---|
| Rules | Keyword and pattern matching. Deterministic, no model call, fast. |
| Model | Asks a model to read the message and pick a target. |
| Both | Tries the rules first; falls back to the model when nothing matches. |
Rule-based routing evaluates in a fixed order: keywords first, then patterns, then the highest-priority target as a fallback. A message that matches nothing still gets an answer — it goes to the fallback rather than being dropped.
Routing decisions can be recorded, so a surprising answer can be traced back to the agent that produced it. Whether they are recorded depends on how your deployment is wired.
Multi-step work
Some requests need several steps — find something, then act on it, then check the result. Mesa can run that as a plan: a planner breaks the goal into steps, each step runs, and a checker decides whether the goal has been met or another pass is needed. State is stored as it goes, so a long task survives a restart instead of starting over.
Multi-step execution starts only when an agent explicitly asks for it — the agent's own output has to request it. A complicated-sounding question does not trigger it on its own, and an agent that has not been written to ask for it will simply answer in one step.
What you can and cannot configure
Agent configuration is validated strictly, and this is deliberate: a setting that looks accepted but does nothing is worse than a setting that is refused.
Refused outright. If an agent definition sets any of these, it fails to load with a clear error rather than being quietly ignored:
- maximum response tokens
- persistent memory and retrieval
- per-agent spending budgets
- behaviour blocks
- structured output schemas
- tool constraints
- fallback models
Each is refused because there is no mechanism behind it yet. When one is built, it stops being refused.
Temperature is the sampling setting you can tune: it is stored on the bot and passed to the model on every reply — see Bot settings.
Tools
Tools are what an agent can do — search, generate an image, call an external service. Every tool call is checked before it runs: whether this agent may use this tool, how many times it has already called it during this reply, and how much data it may return. A blocked call returns an error the agent can recover from rather than killing the reply.
Tools that fetch URLs go through a hardened path that refuses internal addresses, so an agent cannot be talked into fetching something inside your infrastructure.
For tools that act as you — using your own connected GitHub account, for instance — see Tool integrations, which has a different and stricter safety model.