Bots
A bot is a reusable assistant configuration with fixed instructions, model settings, capability limits, and access rules.
Configuration
Bot configuration determines behavior and who can start conversations.
| Setting | Purpose |
|---|---|
| Name and Description | Identify the bot and its intended use. |
| System Prompt | Stable operating instructions. |
| Mode | Chat for conversation or Develop for development work. |
| Model | System default or a specific model. |
| Greeting, Icon, Color, Category | Discovery and presentation. |
| Read-Only Mode | Prevent file modifications. |
| Allowed Tools, Skills, MCP Servers, Polygent MCP Tools | Limit available capabilities. |
| Workspace Scope | Global or selected workspaces. |
| Required Permissions and Roles | Limit visibility and use. |
| Lock Model | Prevent users from changing the model. |
| Enabled | Allow or block new conversations without deleting the bot. |
Use least privilege. An explicit empty capability selection grants none; use the unrestricted control only when all enabled items are intended.
Categories and ordering
Categories organize bot discovery in the Bots page and new-conversation picker.
Use Manage Categories to create, rename, reorder, or delete categories. A category must be empty before deletion. Drag bot cards to reorder or recategorize them. Clear filters and search before reordering.
Built-in bots
Built-in bots ship with managed defaults and cannot be deleted.
Editing a built-in bot marks it as customized, and those changes are retained across updates. Reset to defaults discards customization and restores the current built-in configuration.
After an update, test customized bots against current workspace policies and available capabilities.
Management
Bot management covers creation, cloning, editing, enablement, and deletion.
- Define one narrow use case.
- Write the system prompt and choose Chat or Develop mode.
- Apply workspace, role, and permission restrictions.
- Grant only required tools, skills, and MCP access.
- Lock the model when predictable behavior or cost control is required.
- Test with an account that has the intended access.
- Enable the bot for users.
Disable a bot before changing critical behavior. Deleting a custom bot does not delete existing conversations, but those conversations no longer have an active bot configuration.
Conversations
Each bot conversation is a session that retains the bot association and conversation history.
Users can start a bot from the Bots page or new-conversation picker and resume eligible conversations from My Work. Session updates appear automatically.
Writing system prompts
A production bot prompt defines scope, required inputs, constraints, escalation behavior, and output format.
- State what the bot must and must not do.
- Require confirmation before destructive or externally visible actions.
- Tell the bot to identify missing information rather than invent it.
- Keep credentials and customer secrets out of prompts.
- Avoid duplicating instructions already enforced through capability controls.
Capability controls
Capability controls are server-enforced restrictions on what the bot can use.
- Read-Only Mode blocks file editing but does not make untrusted content safe.
- Allowed Tools restrict built-in operations.
- Skills restrict loaded procedural instructions.
- MCP Servers restrict external tool servers.
- Polygent MCP Tools restrict platform actions.
- Bots have access only to the built-in read-only exploration subagent; other subagents are unavailable.
Review MCP server authentication and data exposure separately. A bot can disclose data through any allowed external tool.
Access control
Access requires the bot to be enabled, available in the workspace, and permitted for the user's roles and permissions.
Global scope does not bypass workspace membership. Required roles and permissions are cumulative restrictions. Test both an allowed and denied account after access changes.
Permissions
Administrative permissions control bot lifecycle independently from bot-specific access rules.
Grant bot management only to users responsible for prompts, capability policy, and model cost. Users without management permission can use only bots visible to them.
Troubleshooting
These checks cover common bot incidents.
| Symptom | Check |
|---|---|
| Bot is not visible | Confirm enabled state, workspace scope, required roles and permissions, and user workspace membership. |
| Model cannot be changed | Lock Model is enabled or the bot configuration is managed. |
| Tool or skill is unavailable | Check read-only mode and every allowed capability list. |
| MCP action fails | Verify the server is enabled, allowed for the bot, authenticated, and reachable from the session host. |
| Built-in change is lost | Customize the bot before changing managed fields. |
| Reset removed changes | Reset intentionally restores built-in defaults; reapply only approved customization. |
| Existing conversation behaves differently | Start a new conversation after material bot configuration changes and compare the effective settings. |