Create an AI agent in AI Studio

An AI agent is a named profile that Sense uses to answer a kind of question: it combines a model, an execution account, behaviour flags, run limits, instructions, guardrails, knowledge, capability grants and routing rules. You build it in two stages. The New agent dialog creates the base record, and the agent's detail page holds everything else. When a user writes in Sense chat, the router picks one eligible agent to answer.

Overview

Agents live under Setup → Sense AI Studio → Agents. The list shows each agent's Label, Source (Custom or Managed), Agent Type, Model, Interaction, Routing intents, Audience, Validation, Fallback, Default, Active and Updated. Its page header has two buttons:

• New agent builds a custom agent by hand, and is what this page covers.
• Agent gallery activates a curated platform agent. A gallery agent is managed: its template owns most fields and keeps them up to date. See Managed agents.

The detail page has the tabs Overview, Instructions & Routing, Intent Mapping and Runs. Agents that publish nudges also get a Schedules tab. The header buttons are Back, Edit and Validate.

When to use it

Create a custom agent when a distinct kind of question deserves its own instructions, tools or audience. Examples are pricing questions that must always call a pricing tool, or a helper that only the finance team should reach. If a gallery agent already does the job, activate it instead: it stays in sync with the platform template while you keep control of its model, audience and your own instructions.

How xMatix handles it

• Routing. For every chat turn the router considers only agents that are Active, have Supports chat on, and whose validation is not Failed. If an agent has audience teams, the asking user must belong to at least one of them. Intent mappings, routing keywords and example prompts then steer which candidate wins. When nothing matches, the Routing fallback agent answers.
• Identity. A chat turn always runs as the signed-in user, so the agent can only read what that person can open. Background runs, such as scheduled ones, run as the agent's Execution account. When that is empty they run as the organization's system process user.
• Instructions. The agent's effective instructions are its agent type's default instructions, plus a gallery template's instructions for a managed agent, combined with your Additional Instructions in the order Instruction merge sets. Your Input, Restrictions, Output format and guardrail settings are always added after that text.

Prerequisites

• The Manage AI agents capability, which opens Agents, Knowledge, Script tools, Traces and the other agent screens in Sense AI Studio.
• An active chat model. Either pin one on the agent or assign a tenant default chat model on Setup → Sense AI Studio → Models. Validation fails when neither exists.
• Optional: an execution account, meaning an active user with at least one active security profile, for agents that run unattended.
• Optional: documents ingested into a named collection on Knowledge, if the agent should cite them.
• Optional: the script tools, MCP servers or capabilities the agent should call, already registered.
• Optional: the security teams the agent should be limited to.

Procedure

123456 Expand

1. 1

   Label is what users see; Name is the stable internal identifier used in configuration and run evidence.

2. 2

   Agent Type supplies the base instructions and constrains which behavior flags validation accepts.

3. 3

   Model defaults to the tenant's default chat model; pick an active chat-capable model and validate it before the agent.

4. 4

   Interaction Mode (Interactive) and Instruction Merge (Append) decide how the agent runs and how its instructions combine with the type's base prompt.

5. 5

   Execution Account becomes the effective user for every turn; empty means the tenant's system-process fallback, so prefer a dedicated, narrowly profiled account.

6. 6

   Behavior Flags, Run Limits and Routing are collapsed; open and review each before Create.

Step 1 — Start the agent

Open Setup → Sense AI Studio → Agents and click New agent. The New agent dialog opens. Type the Label. Name fills in from the Label, and you can change it now, but it cannot be changed after Create. Add a Description and pick the Agent type. Only active agent types are offered.

Step 2 — Choose the model, modes and execution account

Leave Model on Tenant default to follow whichever chat model is the tenant default at run time, or pick a specific active model to pin it. Set Interaction mode (Interactive, Autonomous or Hybrid) and Instruction merge (Append, Prepend or Sectioned). Pick an Execution account, or leave System process fallback to run background work as the organization's system process user. Each account in the list shows its security profiles. Accounts marked [System] are the system process user.

Step 3 — Review Behaviour flags

1234 Expand

1. 1

   Supports chat (on by default) makes the profile eligible for the chat assistant; queued runs and scheduling add unattended invocation modes the Agent Type must allow.

2. 2

   Supports approvals declares that write tools may pause for a human; the deployment's approval switch and tool list decide whether they actually do.

3. 3

   Supports checkpointing and Can persist outputs govern run state and stored results, not data authorization.

4. 4

   Active makes the profile routable; Default agent should be set on exactly one general agent — saving it here can clear the flag on a sibling.

Open Behaviour flags. Supports chat, Can persist outputs and Active start on. Supports queued runs, Supports scheduling, Supports approvals, Supports checkpointing and Default agent start off. Turn on scheduling, approvals or checkpointing only if the agent type supports them, because validation fails otherwise. Turning Supports approvals on does not by itself make anyone approve anything (see Business rules).

Step 4 — Review Run limits

1234 Expand

1. 1

   Max Tool Calls (default 8) caps callable-tool invocations in one run; raise it only from observed run evidence.

2. 2

   Max Autonomous Steps (default 8) bounds the planner's unattended loop before it must answer or stop.

3. 3

   Timeout Seconds (default 120) ends a run that exceeds the elapsed budget.

4. 4

   Concurrency Limit (default 1) caps simultaneous runs of this profile; queued and scheduled work waits behind it.

Open Run limits. The defaults are Max tool calls 8, Max autonomous steps 8, Timeout (seconds) 120 and Concurrency limit 1. Keep them until the agent's Runs tab shows that a real task needs more. These are cost and runtime limits, not permissions.

Step 5 — Review Routing and create

12345 Expand

1. 1

   Routing fallback agent answers turns no other agent matches; keep exactly one, because saving it here can clear the flag on the previous fallback.

2. 2

   Default routing profile marks the tenant's general-purpose routing choice; it is separate from the Default agent behavior flag.

3. 3

   Audience Teams restricts who can be routed to this agent; empty keeps it available to all users.

4. 4

   Routing Summary restates the flags (No fallback, No routing profile) and points to the detail page for Intent Mapping.

5. 5

   Create writes the base record only; instructions, knowledge collections, capability grants and intents follow on the detail tabs.

Open Routing. Turn on Routing fallback agent only if this agent should answer everything that matches no other agent. Turn on Default routing profile only if its routing instructions should guide the router. Pick Audience teams to limit who can reach it. If you leave them empty, the agent is available to all users. The Routing summary shows your choices and reminds you that intents are mapped on the detail page. Click Create. You see "AI agent created", and the agent appears in the list with Validation Pending.

Step 6 — Write the instructions and guardrails

Open the agent and go to Instructions & Routing. Fill in what applies:

• Additional Instructions: your own guidance, such as "call the pricing tool for current prices; never estimate".
• Input: what the agent needs before it acts. It asks for anything missing instead of guessing.
• Restrictions: the "never" rules.
• Output format: Inherit, Markdown, Table, JSON or Template. The box below it changes to Formatting notes (optional), Table columns, JSON schema or Answer template.
• Denied tools, Approval-required tools, Sensitive data rules and When tools fail.

Click Save on the card.

Step 7 — Grant knowledge, capabilities and routing text

On the same tab:

• Capability Grants: pick capabilities to limit which tools the agent can use. Leave it empty to inherit every enabled platform capability.
• Knowledge Collections: type collection names separated by commas. Leave it blank to search all ingested documents.
• Routing Description, Routing Keywords, Routing Example Prompts and, for the default routing profile, Routing System Instructions.

Click Save. You see "Instructions updated".

Step 8 — Map intents

Open Intent Mapping. Click an existing intent tag to reuse it, or click Add Intent and fill in Intent Name (required), Label, Priority (0–1000, default 100), Description, Guidance Message and Classifier Hints. Any other agent that handles the same intent is shown under Also handled by, with its priority. Use Remove to drop an intent, then click Save.

Step 9 — Validate

Click Validate in the page header. The Validation value on Overview becomes Ready, or Failed with the reasons, and you see "Agent validated" either way. A Ready result can still carry warnings, for example a denied tool name that is not a built-in tool. Fix any reason, save and validate again.

Step 10 — Test in chat

Start a fresh Sense chat conversation. Send a prompt the agent should win, an ambiguous one and an out-of-scope one. Test as a user inside the audience and as one outside it. Then open the agent's Runs tab, and Traces for chat turns, to check which agent answered, which tools it called and what it returned. Test turns use AI credits.

Fields

New agent dialog

Instructions & Routing tab

Intent Mapping tab

Business rules

• Save resets validation. Every save of a custom agent, from the dialog or a detail tab, sets Validation to Pending. Pending agents can still be routed to. Only Failed removes an agent from routing, so validate after every change.
• Validate checks, with these messages: Name and Label present; the agent type exists and is active, and supports any scheduling, checkpoint or approval flag you turned on ("Selected agent type does not support scheduling." and so on); the model exists and is active, supports chat when Supports chat is on, and is not failing validation ("Selected model is currently failing validation."). An unpinned agent needs a tenant default chat model ("No model is pinned and no tenant default chat model is assigned…"). An explicit execution account must exist, be active, and have an active security profile unless it is the system process user. With no account selected, the tenant must have a system process user.
• One of each per tenant. Saving an agent with Default agent, Routing fallback agent or Default routing profile on clears that flag on every other agent.
• Reused intents keep their definition. If an intent name already exists, the agent joins it with its own priority. The Label, Description, Guidance Message and Classifier Hints you type are used only when the intent is new.
• Audience is replaced in full on each save. A team that is inactive or not found stops the save ("One or more routing audience teams could not be resolved for this tenant.").
• Deleting a custom agent (row action Delete → "Delete agent?") removes its configuration. Managed agents cannot be deleted; deactivate them instead.
• Routing readiness. If no active agent has an intent mapped, or none is the routing fallback, the Agents list shows "Sense AI routing is not fully configured", and routed conversations fail with a configuration error until you fix it.
• Model in use. A model that an agent uses cannot be deleted from Models ("Model is in use by one or more AI agents.").

Managed agents

A gallery agent shows Managed — template '…' as its Source. Its template owns the label, description, agent type, modes, flags, limits, routing text, knowledge, capability grants and set of intents. Those fields are locked, and the server refuses changes to them. You can change the Model, Execution account, Active, Audience teams, intent Priority, Additional Instructions, Input, Restrictions, Output format and guardrails. Re-activate in Agent gallery applies the latest template and keeps those settings.

Example

A distribution company wants pricing questions answered only from live prices. The administrator creates Price Helper (Name price-helper). It uses the interactive agent type, the tenant default model and Instruction merge Append, and its audience is the Sales Desk team. On Instructions & Routing they add "Always call the pricing tool; never estimate a price" as Additional Instructions, and "Never quote a price without its price list" as a Restriction. They set Output format to Table with columns Item, Price List, Unit Price, Valid To, grant the capability that holds the pricing script tool, and add the routing keywords price, rate, price list. On Intent Mapping they add price-lookup with priority 200. Validate shows Ready. A Sales Desk user asks "What is the rate for item FG-100 on the dealer list?", and the Runs tab shows Price Helper answered with one tool call. A warehouse user asking the same question is outside the audience, so the fallback agent answers.

Training

Practice exercise

In a sandbox, create an agent called Practice Helper with an audience of one test team. Add one routing keyword, one intent with priority 150 and the restriction "Never answer questions about payroll". Validate it, and note that its Validation is Ready. Edit its description and check that Validation is back to Pending. Then ask a matching question as a team member and as a non-member. Expected result: the team member's turn is answered by Practice Helper on its Runs tab, and the non-member's turn is answered by the fallback agent.

Quick reference

• Path: Setup → Sense AI Studio → Agents → New agent.
• The dialog creates the record; instructions, grants, knowledge and intents live on the detail page.
• Name is locked after Create.
• Empty Model = tenant default; empty Execution account = system process user.
• Empty Audience teams = everyone; empty Capability Grants = all enabled capabilities; blank Knowledge Collections = all documents.
• Default agent, Routing fallback agent and Default routing profile are one per tenant.
• Every save sets Validation to Pending; only Failed blocks routing.
• Test in a fresh conversation, and check Runs and Traces.

Permissions

Manage AI agents opens the Agents list, the detail page, the gallery and every action on them. A user without it does not see Agents in Setup. Agents never widen data access in chat, because a chat turn runs as the asking user. Background runs use the execution account's security profiles, so give that account only the access the job needs. Who may use Sense at all is governed separately — see How Sense AI is governed.

Configuration

• Models (Setup → Sense AI Studio → Models): the tenant default chat model that unpinned agents follow.
• Knowledge: the collections the agent's Knowledge Collections name.
• Script tools, Configuration → MCP servers and Configuration → Capabilities: the tools that Capability Grants expose. See Extending Sense.
• Security teams: the teams offered under Audience teams.
• Nudges: agents granted nudge publishing get the Schedules tab. See Enable and configure Sense nudges.
• Configuration → AI credits: every agent turn uses credits from the organization's pool.

Common problems

"Selected execution account must have at least one active security profile assignment"

The account has no active security profile. Assign a narrow profile to it, or choose System process fallback, then validate again.

"No model is pinned and no tenant default chat model is assigned"

Assign a default chat model on Models, or pin a model on the agent with Edit.

"Selected agent type does not support scheduling" (or approvals, or checkpoints)

Turn that flag off under Behaviour flags, or pick an agent type that supports it.

Saving says the JSON output format needs a JSON schema

With Output format JSON, the JSON schema box must contain valid JSON. With Template, the Answer template box must not be empty.

My edit to a managed agent is refused

That field belongs to the platform template. Only the model, execution account, active state, audience teams, intent priorities, Additional Instructions, Input, Restrictions, Output format and guardrails can change.

The agent validates Ready but never answers

Check that it is Active with Supports chat on, and that the user is in one of its Audience teams. Check that an intent, keyword or example prompt matches the wording, and that a higher-priority agent does not claim the same intent (Also handled by). If nothing matches, the fallback agent answered.

Knowledge answers come back empty

The named collection is empty or misspelled. Names must match the Knowledge screen exactly. Clear the field temporarily to search all documents and rule the scope out.

Common questions

Which agent answers a user's message?

The router looks only at agents that are active, support chat, are not validation Failed and include the user in their audience (an empty audience includes everyone). Among those, mapped intents and their priorities, routing keywords and example prompts decide the winner. A higher priority ranks an agent ahead of others on the same intent. If nothing fits, the routing fallback agent answers. Because a Pending agent is still eligible, an agent you have just edited keeps answering before you validate it again. Check Runs or Traces to see which agent actually answered.

Does creating an agent widen what users can see?

Not in chat. Every chat turn runs as the signed-in user, so an agent can read only what that person could open themselves. Background runs are different: they act as the agent's execution account, or the system process user when it is empty. An unattended agent with a broad account can therefore read and change more than any one user would. Give it a dedicated account with a narrow security profile, keep its capability grants short, and test with that account's access.

Should we build many small agents or one big one?

Prefer a few well-scoped agents. Routing works best when each agent's intents, keywords and examples describe a clearly different job, and narrow capability grants keep each agent's tools small. Keep exactly one routing fallback agent so that unmatched questions still get an answer. Without one, the Agents list warns that routing is not fully configured.

What is the difference between Default agent, Routing fallback agent and Default routing profile?

Each is one per tenant. The routing fallback agent answers turns that match no other agent. The default routing profile supplies its Routing System Instructions to the router. The default agent marks the tenant's default agent profile. Turning any of them on for one agent turns it off on all others when you save.

Related topics

• AI Studio
• Extending Sense
• Enable and configure Sense nudges
• Asking Sense about your data
• How Sense AI is governed