Reference
Agent definitions
An agent's definition is its job description: the instructions, which AI model it uses, how long one turn may take, and which tools and skills it has.
The agent is the worker. The definition is how that worker currently does the job. Keeping those separate is what lets Scout get steadily better over months without ever losing its history.
The parts
| Part | The question it answers |
|---|---|
| Instructions | What is this for, and what should it never do? |
| Model and reasoning level | How much thinking does the work need? |
| Timeout | How long may one turn run before we stop it? |
| Toolkits | Which actions may it use? |
| Skills | Which reusable instructions can it pull in for particular tasks? |
Writing the instructions
This is the part that decides whether the agent is any good, and it's the part people rush.
Write it like you're briefing someone on their first morning. Four things:
What it's for. One sentence. "You sort incoming tickets for the Northwind IT service desk."
What good looks like. Be specific about shape. "Reply with a category, an urgency from 1 to 4, and a two-sentence summary. No preamble."
What to never do. This is the one people skip and then regret. "Never promise a client a timeline. Never say a problem is fixed unless you've confirmed it. Never guess at a licence count."
What to do when unsure. "If the ticket is ambiguous, say so and mark it for a human rather than guessing."
Keep the standing instructions about the enduring role. Put per-task procedures in skills and provider capabilities in toolkits, so the instructions stay short enough that you'll actually maintain them.
Picking a model
The model is the AI itself: Claude, GPT, Gemini, and so on. Different ones cost different amounts and are better at different things.
You don't need to have an opinion on day one. Start with the default, get the instructions right, and only then try a different model on the same task and compare. Changing the model and the instructions at the same time tells you nothing about which change helped.
Higher reasoning levels think harder and cost more. Worth it for judgment calls; wasted on "reformat this list".
The agent stays; the definition changes
You'll rewrite instructions many times. That doesn't create a new agent, and it doesn't throw away sessions, memory, or history.
| Situation | What to do |
|---|---|
| It's not quite doing the job well | Change the definition |
| You want it on a different model | Change the definition |
| It needs one more tool | Change the definition |
| A different team should use it, with different access | New agent |
| It's for a different client | New agent, probably in a different project |
| It shouldn't be able to see what this one sees | New agent |
Tuning it
Change one thing at a time. This is the entire method and it's easy to skip.
- Give it a real task in Chat.
- Read what it actually did, including which tools it reached for.
- Change one thing: a sentence of instruction, one tool, the model.
- Run the same task again and compare.
The session is a full record of what the agent saw and did, which is what makes this comparison possible at all. Change three things at once and you've learned nothing.
When your own software owns the behavior
Most teams write the definition in Mobius and edit it there. That's the right default and it keeps the behavior where operators can see it.
If you're building Mobius into your own product, you might already hold the per-customer behavior in your own system. There are three ways the definition can arrive:
| Source | Use it when |
|---|---|
| Stored in Mobius | Your team writes and operates the agent in Mobius |
| Sent by the caller | Your software starts the conversation and already knows the customer's settings |
| Fetched from your backend | Mobius starts scheduled or event-driven work, but your backend owns the current behavior |
These aren't different kinds of agent. They're different ways of supplying the same job description.
Reach for an application-owned definition when copying the same behavior into many client projects would drift out of sync. Otherwise store it in Mobius.
A definition your software sends can replace the stored tools and skills for that conversation, but it can never grant access the agent doesn't have. The Agent definitions API guide covers the exact rules, caching, and what happens when your backend doesn't answer.
In the app
Open Build > Agents, pick an agent, then Configure.
Start with clear instructions and no tools. Have one real conversation. Add the first tool only when something the agent genuinely needed was missing.
Next
- Understand the worker itself in agents.
- Add capability with toolkits and skills.
- See what a conversation remembers in agent sessions.
- Supply definitions from your own code with the Agent definitions API guide.