Managing Agents

Mattermost Agents V2 turns agent management into a first-class product surface. Each agent is a database-backed identity with its own bot user account, instructions, model, access rules, and MCP tool grants. This guide explains where agents live in the product, who can manage them, and how to create, edit, and delete them.

For broader plugin configuration (services, web search, embedding search, MCP servers, per-tool policies), see the Admin Guide. For chat usage and tool approval flows, see the User Guide.

Overview

In v2, an agent is more than a JSON entry in plugin config. Each agent has:

• A persistent record in the Agents_UserAgents database table. Migrations 000005 and 000006 create the table and add the model, native-tool, reasoning, and structured-output columns.
• A linked Mattermost bot account. Display name and avatar updates on the agent flow through to that bot account; deleting an agent deactivates the bot.
• A creator (CreatorID) and an optional list of agent admins (AdminUserIDs). The creator is always an admin and can't be removed from that role.
• Channel and user access rules and an MCP tool allowlist (or "all MCP tools" auto-grant) stored on the same record.
• Cluster-aware change propagation: when an agent is created, edited, or deleted, the originating node refreshes its bot cache, publishes a agent_update cluster event, and broadcasts a bots_invalidate websocket event so every node and connected client picks up the change.

This means agent identity, instructions, scoping, and tool grants are part of your Mattermost data — they live in the same database as your channels and users, are covered by your normal Mattermost backups, and survive plugin restarts and upgrades.

Where Agents live in the product

Agents is a top-level Mattermost product entry, not a plugin panel. It registers itself with the Mattermost product switcher (the grid icon) so the Agents page renders inside the Mattermost shell with full theming.

You can reach the Agents page in three ways:

• Use the product switcher (grid icon) and select Agents.
• Open the URL /plug/mattermost-ai/agents directly.
• From a conversation, open AI Actions > Manage agents.

The System Console > AI Bots page no longer hosts the agent editor. Instead, it shows an AI bot configuration has moved notice with a link back to the Agents page. System administrators can still set the default bot in the same System Console section, just below the redirect notice — but creating, editing, and deleting agents happens on the Agents page. The default bot is the fallback agent for users who have not made an explicit selection; a user's own choice takes precedence.

The Agents page itself shows:

• A header with the page title and a Create agent button (visible only to users who can create agents — see Permissions and license).
• Two tabs: All agents (every agent the user can see) and Your agents (agents the current user created that they can still see).
• A search box that filters by display name or username.
• One row per agent showing the avatar, display name, @username, an All MCP tools or N tools badge, and an Inactive warning badge when the agent is not running. Hovering the badge explains why: the agent's AI service was deleted or is missing required settings, the service is not active on the current plan, or the plan's agent limit is reached (see Agent shows an "Inactive" badge).
• A row-level overflow menu (⋯) with Edit and Delete actions for users who can manage that agent. Selecting the row itself also opens the editor for users who can manage the agent.

Permissions and license

Agent management uses three Mattermost system permissions plus a license check.

Permissions

Permission	Capability
manage_own_agent	Create new agents and edit/delete agents the user is an admin of.
manage_others_agent	Edit and delete any agent on the server, including agents the user did not create.
manage_system	System administrator. Always allowed to manage agents that have no creator (migrated legacy bots) and may create agents in the absence of manage_own_agent.

The Agents page applies these rules consistently between the UI and the API:

• The Create agent button is shown to users with manage_own_agent or manage_system.
• A row's Edit/Delete actions are available to:
  • The agent's creator,
  • Anyone listed in the agent's Agent admins field,
  • Anyone with manage_others_agent,
  • System administrators, when the agent has no creator (a migrated legacy bot — see Legacy bot migration).
• The same checks gate the underlying POST /agents, PUT /agents/:id, and DELETE /agents/:id API routes, so direct API calls cannot bypass the UI rules.

By default, regular users do not have manage_own_agent. Grant it through your existing Mattermost role/permission model to delegate agent creation — typically under System Console > User Management > Permissions (exact path varies by Mattermost server version).

Who can see which agents

Manage permission alone does not decide list visibility. Agents (and the AI services shown when binding an agent) are filtered by what the signed-in user can use:

• System administrators can see agents even when a service ABAC policy would deny them personally, so they can rebind services or restore access.
• All other users — including creators and delegated agent admins — only see agents they can use under both agent access and the agent's AI service access. Agents whose service they cannot use are hidden, not shown with a deny badge.

If a non–system-admin agent admin loses access to an agent's service under ABAC, that agent disappears from their Agents page until a system admin restores service access or changes the binding. See Attribute-based access control (ABAC) in the Admin Guide.

License

The number of agents that can be active depends on the license level. Configuration-file bots and user-created agents count together as one pool.

• Free (no license): one agent. Once one agent exists, the Create agent button is disabled with a hint naming the plan that raises the cap, and the API returns HTTP 403 with an actionable licensing message for any over-limit creation attempt.
• Professional: three agents.
• Enterprise, Entry and Enterprise Advanced: unlimited agents (subject to permissions).

Agent access controls (restricting an agent to named users, teams or channels, and the corresponding block lists) are available at Professional and above; attribute-based access is available at Enterprise Advanced; service-account authentication is available at Enterprise and above. Resetting any of these to their open defaults is always permitted, and an agent that already has user, team or channel lists can have those lists edited at any level.

For the full feature/license matrix, see License requirements in the Admin Guide.

Creating an agent

1. Open the Agents page.
2. Select Create agent. A full-page editor opens with three tabs: Configuration, Access, and MCPs.
3. Fill in the tabs (see below). Required fields are validated when you save.
4. Select Save. The plugin creates a Mattermost bot user, persists the agent record, propagates the change to other cluster nodes, and returns you to the Agents list.

Configuration tab

The Configuration tab covers identity, model selection, custom instructions, and per-agent capability toggles. The fields that appear depend on the AI service you select.

Field	Description
Display name	Required. The user-facing name shown in posts, the agent list, and the RHS picker. Updating the display name also updates the linked Mattermost bot's display name.
Agent username	Required. The @mention handle for the agent. Must start with a letter and contain only lowercase letters, numbers, periods, hyphens, and underscores. Maximum 22 characters in the UI. The server-side validator does not enforce a length limit; direct API callers are constrained only by the database schema (VARCHAR(64)). The username is set when the agent is created and cannot be changed afterward.
Agent avatar	Optional. Upload a custom image. Avatar upload is a second step after the agent record is created or updated; if the avatar upload fails the rest of the save still succeeds.
AI Service	Required. Pick a configured service from the dropdown. Services are managed in System Console > Plugins > Agents and shared across agents. If the agent references a service that has been deleted, an "Unknown service (deleted)" entry appears in the dropdown until you pick a new one.
Model	Optional. Override the service's default model for this agent. For OpenAI, Anthropic, Azure, OpenAI Compatible, Gemini, and Vertex AI services the field becomes a combobox populated by a live model fetch from the provider; for other services it is a free-text field. Leave empty to use the service default.
Max tool turns	Maximum number of consecutive tool-call/execute rounds the agent performs in a single response before stopping. Defaults to 30 (allowed range 1–250). Lower this for smaller models that tend to loop on tool calls; raise it for agents that chain many tools per turn (for example dynamic MCP discovery: search → load → execute). Clearing the field saves the default.
Custom instructions	Free-text. Prepended to every request as the agent's system prompt. Use it for tone, role, vocabulary, or workflow guidance.
Enable Vision	Available for service types that support image input. Lets the agent process attached images. Requires a vision-capable model.
Enable Tools	Available for service types that support tool calling. When off, the agent runs without tools and the MCPs tab is disabled. Some Mattermost Agents features will not work without tools.
Native provider tools	Available when the selected provider exposes native tools (Anthropic, OpenAI on Responses API, Gemini, Vertex AI, and OpenAI Compatible/Azure when Use Responses API is on). Pick which native tools (such as web search) the agent may use.
Reasoning	Available for Anthropic, OpenAI (Responses API), Gemini, and Vertex AI services. Lets you enable extended thinking and pick a reasoning effort or thinking budget.

Structured output is not configured on the agent. How a request-time JSON schema is fulfilled (native provider structured output versus a prompt-based fallback) is controlled by the Structured output policy on the service, configured in System Console > Plugins > Agents; see Structured output in the Admin Guide. The deprecated per-agent structuredOutputEnabled API property and database column are still accepted for compatibility but are ignored at runtime.

Switching the AI Service to a service of a different type clears the model field and resets the native tools, reasoning, and thinking budget fields back to defaults so you don't carry stale provider-specific values across providers. Switching between two services of the same type (for example two OpenAI Compatible entries) preserves those fields.

If the form is invalid when you select Save, validation errors are shown inline (display name required, username required and must match the allowed pattern, AI Service required) and the editor returns to the Configuration tab.

Access tab

The Access tab controls who can interact with the agent and who can administer it.

• Channel access restricts the channels in which the agent can be @mentioned:
  • All channels (default): the agent works in every channel where it is a member.
  • Allow only: the agent only responds in the channels you list.
  • Block: the agent responds everywhere except the channels you list.
  • None: the agent cannot be used in channels at all (DM-only).
• User access restricts which users can interact with the agent:
  • All users (default): anyone in the workspace.
  • Allow only: only listed users, or members of listed teams.
  • Block: everyone except listed users or members of listed teams.
  • Attribute-based (access policy): an ABAC policy is the only user-access gate (allow/block lists are ignored). See Attribute-based access control (ABAC).
• Agent admins is a list of users who can edit and delete this agent in addition to the creator. The agent creator is always an admin and is not shown in the editable list. Agent admins still only see the agent when they can use its AI service (system admins are the exception — see Who can see which agents).

These rules are enforced both for @mentions in channels and for direct conversations with the agent. They are enforced in the server in bots/permissions.go, so they apply uniformly to UI flows, slash commands, and tool-driven access.

MCPs tab

The MCPs tab is available only when Enable Tools is on (Configuration tab). It controls which MCP tools the agent may call and how MCP tool schemas are exposed to the model.

• Dynamic tool loading: enabled by default for new agents and for existing agents that do not yet have this setting. The agent starts with MCP discovery and loading helpers, then loads full MCP tool schemas only when needed. Disable this to use the full MCP tool list for this agent up front. Once a tool is loaded in a conversation, it can be used in later turns in that same conversation without repeating the search/load prelude.
• Automatically enable all MCP tools: the agent has access to every MCP tool available in the server right now and to any MCP tools added later. This is the default for new agents and the setting used by all migrated legacy bots.
• When the auto-grant is off, pick the specific MCP tools to enable. Tools that are no longer present on the server are dropped from the agent's allowlist when you save.
• For OAuth-backed MCP servers, you can also start the per-user Connect flow directly from this tab. Enabling a server that is currently disconnected stores a wildcard grant — once you finish the OAuth flow, the agent gets every tool that server exposes. The tab refreshes automatically when you connect or disconnect (mcp_connection_updated websocket event). Connect is not shown while Use service accounts for authentication is on; the tab lists that agent's service-account catalog instead of your personal connections.
• Use service accounts for authentication switches the agent from per-user credentials to admin-configured service account credentials for external MCP servers. External MCP servers without service account headers configured in the System Console are excluded from the agent (fail closed). Mattermost (embedded) and plugin tools run with each requesting user's own permissions, and users are never asked to connect accounts. The MCPs tab then shows Connected for servers whose service account credentials work, and No service account credentials for servers that have none. Turning it on shows a warning because it flattens permissions on those external servers — anyone who can use the agent acts with the agent's shared access there — so restrict usage on the Access tab. Only system administrators can turn this setting on. While it is enabled, some fields are system-admin-only; see What's editable vs locked. Anyone who can manage the agent can still turn the setting off or delete the agent. Requires the same license as remote MCP servers. See Service account authentication in the Admin Guide.

Dynamic tool loading and the auto-grant are separate controls: dynamic loading decides when schemas are shown to the model, while the auto-grant decides which MCP tools the agent is allowed to use.

Per-tool approval policies (ask, auto_run, auto_run_everywhere) are configured by an administrator in System Console > Plugins > Agents > Model Context Protocol (MCP) > Tools. Granting a tool to an agent on the MCPs tab does not override those policies — runtime approval still applies. MCP discovery and loading helpers run automatically, but MCP tools that are dynamically loaded still follow their configured approval policy. For more on MCP setup, see Model Context Protocol (MCP) in the Admin Guide. For more on the approval model, see Multiplayer Tool Calling.

Editing an agent

To edit an agent:

1. Open the Agents page.
2. Select the row, or open the row's ⋯ menu and choose Edit.
3. Update fields across the three tabs as needed. The editor opens on the Configuration tab and remembers your tab selection while editing.
4. Select Save.

The editor uses a full-document PUT /agents/:id save, so every visible field on every tab is sent on save. There is no per-field partial update.

API clients can set mcpDynamicToolLoading on POST /agents and PUT /agents/:id; GET /agents/:id and agent list responses include the field. Send the desired boolean explicitly on create and update. If omitted from a create or update request body, it is stored as false; older persisted bot config that omits the field defaults to true when unmarshalled for compatibility.

What's editable vs locked

While Use service accounts for authentication is off, anyone who can manage the agent may edit every field except the permanent username (below).

While Use service accounts for authentication is enabled:

• Editable by anyone who can manage the agent: display name, avatar, AI service, model, max tool turns, custom instructions, vision, Enable Tools, native tools, dynamic tool loading, and reasoning.

• System-admin-only (sensitive): channel access, user access, and agent admins; MCP tool grants and Automatically enable all MCP tools; and enabling service account authentication itself.

• Anyone who can manage the agent may still turn service account authentication off or delete the agent.

• Agent username is permanent. Once the agent is created, the username field is disabled in the editor. The Mattermost bot account is keyed off this username, and changing it would orphan existing @mentions and conversation history. To use a different username, create a new agent.

Unsaved-changes warning

If you have unsaved changes and try to leave the editor — by selecting Cancel, pressing Escape, or selecting the back arrow — Mattermost shows a Discard changes? confirmation with Discard and Keep editing buttons. Discard abandons your edits and returns to the Agents list. Keep editing dismisses the prompt and leaves you in the editor.

The dirty-state check considers both form fields and a queued avatar upload, so swapping the avatar but making no other change will still trigger the warning.

Effect of edits on running conversations

• Updating the agent's display name flows through to the linked Mattermost bot's display name immediately.
• Updating the AI service, model, or instructions takes effect on the next agent turn — in-flight responses already streaming to a user are not interrupted.
• Updating channel/user access rules takes effect immediately for new mentions; the next time a user @mentions the agent in a channel that is now blocked, the agent will refuse the request.

Deleting an agent

To delete an agent:

1. Open the Agents page.
2. Open the row's ⋯ menu and select Delete.
3. Confirm in the Delete agent dialog. The action cannot be undone.

Deleting an agent:

• Soft-deletes the row in Agents_UserAgents (sets DeleteAt).
• Deactivates the linked Mattermost bot account, so @mentions no longer route to it.
• Publishes a cluster event so every Mattermost node refreshes its bot cache, and broadcasts a bots_invalidate websocket event so connected webapp clients drop the agent from their pickers.

Existing posts that mention or were authored by the agent remain in channels with their original content; only the agent's ability to reply to new requests is removed. Custom prompts that referenced the agent by username may no longer resolve that agent after deletion.

Legacy bot migration

Mattermost Agents V1 stored bot definitions inline in the plugin's config.bots array in config.json. V2 moves agents into the database. To make this transition automatic, the plugin runs a one-time migration on startup.

What happens on upgrade

When the v2 plugin first activates against a server that previously used v1:

1. The plugin acquires a cluster mutex (ai_legacy_bots_migration) so only one node performs the migration.
2. It reads the stored config and, for each entry in config.bots that is not already represented in Agents_UserAgents, creates a new agent record. The existing Mattermost bot user account is reused; only the agent record is new.
3. Each migrated agent is created with AutoEnableNewMCPTools = true so it preserves the legacy "all tools allowed" behavior. The MCP tool allowlist is not carried over from any prior gate because v1 bots had access to every MCP tool by default.
4. Each migrated agent has an empty CreatorID and an empty admin list. This is what marks them as legacy. Any system administrator (manage_system) can edit or delete migrated agents from the Agents page.
5. The plugin clears config.bots from the stored configuration to prevent duplicate bot registration on the next run, and writes legacy_config_bots_migrated = true to the system table so the migration does not run again.

Soft-deferred migration

If a config bot exists but its corresponding Mattermost bot account isn't yet registered (which can happen during a fresh plugin enable that occurs before the bot owner runs EnsureBots), the migration defers instead of creating partial records:

• No agents are created.
• config.bots is not cleared.
• The migration flag is not set.
• A warning is logged: Deferring legacy bot migration: Mattermost bot not found.

The migration retries on the next config update or plugin reload. This is the expected behavior for e2e and fresh-install scenarios — no operator action is needed.

How to verify migration

After upgrading:

1. Open the Agents page. Each pre-existing v1 bot should now appear as an agent row.
2. Open System Console > AI Bots. You should see the AI bot configuration has moved notice with a link to the Agents page.
3. Confirm in the database that Agents_UserAgents contains the expected number of rows and that config.bots is empty in the stored plugin configuration. Use:

   mmctl config get PluginSettings.Plugins.mattermost-ai.bots

   SELECT COUNT(*) FROM Agents_UserAgents WHERE DeleteAt = 0;

4. Confirm that the system value legacy_config_bots_migrated is set to true. The flag lives in the plugin-owned Agents_System table — there is no mmctl command for plugin-specific system tables, so this check is SQL-only:

   SELECT SValue FROM Agents_System WHERE SKey = 'legacy_config_bots_migrated';

If migration was not performed (because no config.bots entries existed) the flag is not set; the plugin will check again the next time configuration changes. This is intentional: enabling the plugin on a clean instance and then importing bots later should still trigger the one-time migration.

Backups

Agents_UserAgents is a plugin-owned table and is included in standard Mattermost database backups. Plain mattermost-config.json snapshots are no longer sufficient to restore agents — they contain only services and the default-bot setting, not agent definitions. See Backup and restore for details.

HA cluster behavior

Agent changes propagate across Mattermost cluster nodes through two channels: a plugin cluster event and a webapp websocket broadcast.

When an agent is created, edited, or deleted on any node:

1. The node that handled the request refreshes its own bot cache, calling EnsureBots() so the new or changed agent is loaded into memory immediately.
2. The plugin publishes an agent_update cluster event using model.PluginClusterEventSendTypeReliable. Every other plugin node receives it via OnPluginClusterEvent and triggers the same forced refresh.
3. The plugin broadcasts a bots_invalidate websocket event to all connected clients (custom_mattermost-ai_bots_invalidate). Webapp clients invalidate their RHS bot picker cache and refetch.

The same channels carry plugin config updates (config_update cluster event) so service changes made in one System Console session are picked up cluster-wide.

Practical consequences:

• Agent changes are visible cluster-wide within seconds. There is no need to restart the plugin or stagger updates across nodes.
• If the cluster event is dropped (for example because a node briefly leaves the cluster), the next config or plugin reload on that node forces a fresh DB load, so agents will not stay stale indefinitely.
• The migration mutex ensures that legacy bot migration runs on exactly one node even when several nodes start simultaneously.

EnsureBots() is called during OnActivate() (server/main.go:220), so a node that never receives an agent_update event will still load DB-backed agents on startup.

Troubleshooting

"Create agent" is disabled and an upgrade hint is shown

The server has reached the number of agents its license level allows (one on Free, three on Professional). The Agents page still shows the list, but Create agent is disabled. Apply a Professional, Entry, Enterprise, or Enterprise Advanced licence in System Console > About > Edition and License to raise the cap, or delete an existing agent before creating a replacement.

"Create agent" button is hidden

The signed-in user does not have manage_own_agent or manage_system. Grant manage_own_agent through your role/permission configuration, or sign in as a system administrator.

"Edit" and "Delete" actions are not shown for an agent

The signed-in user is not the agent's creator, not in Agent admins, and does not have manage_others_agent. For migrated legacy bots (no creator), only system administrators see these actions.

Agent shows an "Inactive" badge

The agent is stored but not running. The badge tooltip names the reason:

• Service deleted or incomplete — the agent's serviceID no longer matches a service in System Console > Plugins > Agents, or that service is missing required settings such as its API key. Edit the agent and pick a current service, or complete the service configuration.
• Service not active on the plan — Free and Professional use only the first service in the Services list. Edit the agent and choose that service; multiple services are available at Enterprise and above.
• Agent limit reached — the plan's agent cap is filled by configuration-file bots and agents created earlier. Delete an earlier agent or move to a plan with more agents.

The badge is not used to mean "you are denied by service ABAC." Non–system-admins who cannot use an agent's service simply do not see that agent.

Saving an agent returns "This username is already taken"

Another agent (active or recently deleted) already uses the username. Pick a different username. Usernames cannot be changed after creation, so attempting to edit the conflicting agent is not a workaround — delete that agent if it is truly unused, or pick another name.

Saving an agent returns a licensing error naming a required plan

The server has reached the number of agents its license level allows, or the agent uses a capability available at a higher level (for example access controls, attribute-based access or service-account authentication). The message names the level that provides it. Apply a qualifying license, or adjust the agent so it stays within the current level.

Avatar didn't update after save

Avatar upload runs as a second request after the agent record is saved. If the avatar upload fails (network blip, image too large, unsupported format), the agent record is still saved successfully but the avatar is unchanged. Re-open the editor, re-select the file, and save again. Avatar upload enforces a 10 MB maximum size. There is no content-type pre-validation in the plugin; the Mattermost server's profile image processing handles format checks.

Editor shows the previous agent's avatar after switching agents

This was a known issue (MM-68531, fixed in PR #690). If you observe this on a v2.0 build, confirm the plugin version includes that fix and refresh the page.

MCPs tab is grayed out

The agent has Enable Tools turned off in the Configuration tab. Turn it back on to access MCP configuration. Some product features (channel summaries with tool-backed actions, tool-using custom prompts) will not work for this agent until tools are enabled.

MCP server is shown but tools list is empty

For agents using per-user authentication with OAuth-backed MCP servers, each user must complete the OAuth flow before tools are visible. Use the Connect button on the MCPs tab — or in the Agents RHS Tools popover — to start the flow. Until you connect, you can still toggle the server on; this stores a wildcard grant so the agent gets every tool the server exposes once you authenticate. See OAuth-backed MCP servers for details.

For agents with Use service accounts for authentication enabled, an empty tools list with No service account credentials means that server has no Service Account Authentication headers in System Console MCP settings and is excluded from the agent. Couldn't connect means those headers are present but the server rejected them — check the header name/value split (the value should not repeat the header name) and the plugin logs.

Agent change isn't visible on another cluster node

Cluster propagation is fast but not synchronous. Wait a few seconds and refresh the Agents page on the other node. If the agent still doesn't appear, check the plugin logs on that node for Failed to re-ensure bots after agent update cluster event or Failed to publish agent update cluster event — both indicate the cluster event channel itself is unhealthy. A plugin reload on the affected node forces a fresh DB load.

Cannot delete a migrated legacy bot

Migrated legacy bots have no creator and no agent admins, so only system administrators (manage_system) can delete them. Sign in as a system administrator and try again.

Related docs

• Admin Guide — installing the plugin, configuring services, embedding search, MCP servers, per-tool policies.
• Upgrading to 2.0 — full upgrade path including the config.bots → DB migration covered above.
• Custom Prompts — reusable prompt templates that can target a specific agent.
• Multiplayer Tool Calling — how tool approval works in channels, including the initiator-only approval rule.
• Providers — provider-specific configuration referenced by the AI Service field.