Authoring agent definitions
An agent is one configured way of answering: a model, a set of instructions, and the tools it may use. AI agents explains that model; this page is the workflow — taking a blank form to an agent a bot actually routes to, and what each field does once it is saved.
Definitions are edited in the admin console, under Agent Studio — the screen other pages refer to as Agents → Definitions, after its address. There is no way to author one from the web app.
The studio at a glance
Three tabs, one scope selector, and three page-level actions:
- Tabs — Tools, Capabilities, Agents. An agent references capabilities and tools, so the three are edited together on one screen.
- Scope — Global shows system-owned definitions available to every tenant; selecting a tenant shows that tenant's own. What you create is owned by the scope you are in when you create it.
- Save All writes everything on screen; each agent also has its own save button. Reload clears the server's definitions cache and refetches. Export downloads what is on screen as a JSON file.
Two words are easy to conflate:
| Tools | Capabilities | |
|---|---|---|
| What they are | What an agent can do — executed with inputs and outputs | What an agent is good at — read when deciding where a message goes |
| An agent gets them | Selected directly, or pulled in by a capability | Selected on the agent |
An action capability names the tool that does its work; selecting that capability for an agent includes the tool automatically. An intrinsic capability needs no tool — the agent handles it with the model alone.
From blank form to a working agent
1. Pick the scope
Global for a definition every tenant should see; a tenant for that tenant's own. Ownership follows from this choice and cannot be edited afterwards on the form.
2. Check the tools it will need
On the Tools tab, each tool carries a badge saying where its implementation lives:
- Code-backed — implemented in the deployment, with a stored record whose metadata you can edit. The input schema shown for these is read from the code and is read-only.
- Virtual — exists in code but has no stored record yet; saving it creates one.
- DB-only — a stored record with no code implementation behind it.
Under a tenant scope you do not create tools from scratch — Create Customization asks you to pick a code-defined tool as the base, and the customization is what that tenant's agents use.
3. Define its capabilities
On the Capabilities tab, Add Capability and fill in:
- Type —
intrinsic(model-only) oraction(backed by a tool). An action capability requires selecting its Tool. - Parameters — the schema of what the capability accepts, used when a request is planned into structured steps. Where the linked tool declares its schema in code, this is shown read-only from the code.
- Prompt template and Parameter mapping — a natural-language template with
{placeholder}slots, and the mapping from parameter names to those slots. Together they turn a planned, structured step into instructions the agent receives. - Default verbosity — how much of the intermediate work reaches the user while this capability runs.
4. Create the agent
On the Agents tab, Add Agent. The field reference below covers everything; the minimum for an agent that works is a name, a model, role instructions, at least one capability, and the handoff and triage fields — without those last ones, nothing ever chooses it.
5. Save
Save the agent (its own save button, or Save All). The ID is generated on save. A save that references a tool or capability that does not exist is refused with an error naming the missing reference, and a definition that sets a configuration with no mechanism behind it is refused rather than ignored — see what you can and cannot configure.
6. Point a bot at it
Saving makes the definition exist; routing makes it answer. If the bot restricts which agents it uses, add the new agent to that list in the bot's form — see below.
Field reference (Agents tab)
| Field | What it does at runtime |
|---|---|
| Name | Display name, also used when routing describes the agent |
| Model | The model this agent answers with |
| Category | Grouping label for the studio and routing descriptions |
| Priority | Ordering among routing targets; the highest-priority target is the fallback when nothing matches |
| Role instructions | The system prompt — persona, expertise, behaviour |
| Tool instructions (one per line) | Appended guidance on how to use its tools |
| Behavior instructions (one per line) | Appended guidance on tone, style and rules |
| Handoff tool name | The unique name routing uses to hand a message to this agent |
| Handoff description | What model-based routing reads to decide this agent should take the message |
| Capabilities | What the agent is good at; tools required by them are included automatically |
| Additional tools | Extra tools not tied to a capability — use sparingly |
| Triage: when / examples | Conditions and sample messages that sharpen model-based routing |
| Triage: keywords | Feed rule-based routing — a keyword match routes here without a model call |
| Triage: flowchart step | Ordering position when routing is evaluated as a sequence; ties break on priority |
| Prompt template / parameter mapping | Agent-level fallback used only when a capability does not define its own |
| Active | Inactive definitions are kept but ignored by routing |
Temperature is not here deliberately — it is a bot setting, applied to every reply the bot makes regardless of agent: see Bot settings. The list of settings that are refused outright is in AI agents; it is not repeated here.
How a bot's routing picks it up
Each bot has a route specification listing its possible targets and how to choose between them — how a message reaches an agent describes the three methods. The targets come from the definitions you author here: an active agent becomes a target addressed by its handoff tool name, described to model-based routing by its handoff description, matched by rule-based routing on its triage keywords, and ordered by priority.
Two things gate whether your new agent actually receives messages:
- Active — an inactive definition is never a target.
- The bot's agent list — a bot can restrict itself to a subset of agents, chosen by checkbox in the bot's form (which also previews the routing instructions that result). A bot with no restriction considers every active agent.
Edits propagate to running bots on their own within a few minutes — there is no deploy step and nothing to restart. The Reload button refreshes the console's view immediately.
Versioning
- Every save creates a new version. Nothing is edited in place; the version and timestamps are shown on the definition after saving.
- Delete archives. Deleting hides every version of the definition from the lists rather than destroying them — and re-creating one with the same content re-activates the archived definition instead of starting a new history.
- Capability edits fan out. A capability lives inside every agent that uses it, so editing one creates a new version of each of those agents. Several version bumps from one edit is this working as designed, not a bug.
The marketplace: sharing definitions across tenants
Definitions can cross tenant boundaries deliberately, through publishing and copying. This is administered in the admin console under Tenant Entities, which shows, per tenant, the definitions it can use, the ones it owns, the system-owned set, and a Marketplace tab listing everything published on the deployment. Agents, capabilities and tools can each be published and copied.
Publish and unpublish
Publish lists a definition in the deployment-wide marketplace, where every tenant can see it. Unpublish retracts the listing. Both are ownership-gated: only the tenant that owns a definition can publish or retract it — an admin of some other tenant cannot.
Copy to a tenant
Copy to Tenant creates a copy owned by the selected tenant. Two rules guard it:
- You must be an admin of the target tenant — you copy into tenants you administer, never out of your own into someone else's.
- The source must be published, or already owned by the target tenant. Another tenant's unpublished definition can never be copied — publishing is what consents to sharing.
What crossing the boundary means for ownership
The copy is a new definition, owned by the target tenant, with its own ID and its own version history. From that point the two are independent:
- The target tenant edits, publishes or deletes its copy without involving the source's owner.
- Edits to the source do not propagate to copies.
- Unpublishing the source stops new copies; it does not recall copies already made.
Related pages
- AI agents — the model: routing methods, multi-step work, what is refused
- Bot settings — temperature and the other per-bot layers
- Creating a bot — the bot the agent answers through
- Tool integrations — tools that act as a specific person, which have a different and stricter safety model than the tools authored here