Settings → AI → Agents
An AI agent is a named combination of a model, a required prompt, generation settings, and optional tool restrictions. Agents are invoked from the chat interface, Quick Assist, live session assistance, reports, and automation Run Agent actions.
The workspace ships with a set of built-in agents for common use cases (config analysis, session assistance, resource summary, chat). You can edit the built-ins’ settings but you cannot delete them. You can also create your own custom agents.
Creating and editing custom agents requires the Base edition. Without it, the Add Agent button and the edit control on custom agents stay visible but locked, with a padlock explaining what is missing; built-in agents remain editable.
Table columns
| Column | Notes |
|---|---|
| Name | The agent’s display name. |
| Type | Badge identifying the agent’s purpose — Chat, Background, Quick Action, or Session Assist. |
| Status | Green check if the agent has a model configured, warning icon if not. Non-functional agents do not appear in the chat agent picker until a model is assigned. |
| Source | Built-in badge for shipped agents, Custom for ones you created. |
| Tools | Number of explicitly selected tools, or All when every tool compatible with the agent type is available. |
| Actions | Edit / Delete (custom only). |
Common tasks
Create a custom agent
- Click Add Agent at the top right.
- Fill the form:
- Name — descriptive label.
- Type — choose Chat for interactive conversations or Background for automation and reporting.
- Description — what the agent is for.
- Model — pick from the configured models on the Models tab.
- System prompt — pick a prompt from the Prompts tab. Every agent must have one.
- Tools — select a narrower allowlist, or leave empty to allow every tool compatible with this agent type.
- Generation settings — Token Budget (max total tokens), Max Response Tokens, Max Steps (how many model round-trips, including tool calls, a single run may take), Max Execution Time in seconds, plus Temperature and Top P sliders.
- Click Save.
Count settings require nonnegative whole numbers. Clearing a count saves 0:
Token Budget and Max Steps become unlimited, Max Response Tokens uses 4096,
and Max Execution Time uses 300 seconds. Positive execution times are clamped
to 10–3600 seconds. Temperature accepts 0–2 and Top P accepts 0–1; providers
may impose narrower model-specific sampling limits.
API clients must send JSON numbers, not numeric strings or null count values. Unknown config keys are rejected. An omitted config leaves an existing agent’s settings unchanged; a supplied custom-agent config replaces its settings. Builtin config updates merge supported settings and retain platform identity.
Edit an agent
- Click the blue edit icon.
- Update the settings. A built-in agent’s name, type, description, and platform identity are managed by MisterShell. Its model, prompt, selected tools, and generation settings are administrator-owned and survive restarts and upgrades.
- Click Save.
Changes take effect on the next invocation.
Delete a custom agent
- Click the red trash icon (not available on built-in agents).
- Confirm.
Deleting a custom agent always succeeds. Chat conversations and run history that referenced the agent are removed along with it, so archive anything you need first.
Tool access rules
Tool restrictions declared by MisterShell are safety boundaries. An agent cannot use a tool that is incompatible with its type. A selected list only narrows the compatible set.
An empty tool selection means all type-compatible tools. For a background agent, that intentional default can be broad: background runs operate as system automation and do not inherit a human user’s permission or location scope. Select a narrower list when the job does not require the full compatible catalog.
When is an agent “not functional”?
An agent is flagged as non-functional when it has neither an assigned model nor a workspace default model. This includes built-in agents awaiting a model assignment and agents whose selected model registration has been deleted.
Edit the agent and pick a model to make it functional again.
Permissions
- Read:
app.ai.read. - Create / edit:
app.ai.write. - Delete custom agents:
app.ai.delete.