> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Configuration
> Configure and customize your AI agents with models, tools, skills, and behavioral parameters.
# Agent Configuration
Agents are the core unit of work in Myrm. Each agent can be independently configured with a specific model, custom system prompt, tools, skills, memory, and behavioral parameters.
## Creating an Agent
1. Navigate to **Agents > New Agent**
2. Choose a name and description
3. Select a model (or let smart routing decide)
4. Configure tools, skills, and permissions
5. Save — the agent is ready to use
A default general-purpose agent is created automatically on first launch.
## Edit-Test Zero Navigation
Myrm embeds the Agent configuration panel directly inside the chat page, enabling a "modify config → send message → see result" workflow with zero page navigation:
* **Inline config panel**: Click the Agent indicator button next to the input box to expand the config panel. Changes to System Prompt, skills, and MCP tools take effect on the very next message
* **Smart collapse**: The panel auto-collapses after sending a message so it never obstructs the conversation; expand it again with one click
* **Auto-save on navigate**: Clicking "Start Chat" from the editor page automatically saves unsaved changes before navigating to the chat page
* **Consistent navigation**: All entry points (sidebar, settings, template market, org marketplace) navigate within the same tab — never opens a new browser tab
## Per-Turn Capability Chips (Skill/MCP)
In addition to agent-level defaults, Myrm supports **one-turn capability override** directly from the chat input:
* Pick a temporary Skill/MCP subset for the **next message only**
* Subtractive-first behavior: selection is constrained to capabilities already enabled on the current agent
* Queue-safe semantics: direct send, queued send, and busy requeue all preserve the same one-turn override intent
* Prompt-cache-safe normalization: selecting the full set collapses to no-op override instead of creating noisy config churn
### Why this matters in real usage
* **Lower accidental tool spend**: users can narrow tools for one risky turn without changing their long-term agent profile
* **Cleaner collaboration**: teammates can run a focused turn and immediately return to the default profile
* **Operational proof, not guesswork**: telemetry tracks submit/apply/noop/queue/busy/final outcome and failure reasons
You can inspect summary metrics from:
* `GET /api/v1/statistics/turn-capability/summary`
## Model Selection
Myrm supports 100+ models through LiteLLM integration:
| Provider | Models |
| ---------------- | ------------------------------------------------------------ |
| **OpenAI** | GPT-4o, GPT-4.1, o4-mini |
| **Anthropic** | Claude Sonnet 4, Claude 3.5 |
| **Google** | Gemini 2.5, Gemini 2.0 |
| **DeepSeek** | DeepSeek V3, DeepSeek R1, DeepSeek V4 Flash, DeepSeek V4 Pro |
| **Local Models** | Ollama, LM Studio, vLLM |
| **Custom** | Any OpenAI-compatible API |
### Smart Routing
The complexity router automatically selects the optimal model tier. **Enabled by default** — no configuration required. When light/reasoning models are not explicitly set, the system auto-selects from your enabled models by cost (cheapest → light, most expensive → reasoning).
| Tier | When Used | Cost |
| ------------- | ------------------------------------- | -------- |
| **SIMPLE** | Quick questions, simple lookups | Cheapest |
| **STANDARD** | General tasks, moderate complexity | Moderate |
| **REASONING** | Complex analysis, multi-step planning | Highest |
The router uses a two-stage assessment (rule-based scoring at zero cost + LLM judge for ambiguous cases) with session momentum — short follow-up messages inherit the session's established tier.
**Complaint-up**: When you click Regenerate without adding modification instructions, the system interprets this as dissatisfaction and automatically upgrades the routing tier (SIMPLE→STANDARD→REASONING). The PenaltyTracker records this feedback so future similar queries route more accurately. If you add instructions (e.g., "rewrite in a more formal tone"), it's treated as a direction change, not a complaint — no tier upgrade occurs.
**Per-Agent Routing Strategy**: Each agent can have its own routing configuration independent of the global setting. In the Agent Capabilities tab, you can set:
* **Inherit Global** (default): follows the global Smart Routing configuration
* **Custom**: specify independent light and reasoning models for this agent
* **Disabled**: this agent always uses its primary model — no routing, no tier classification
Use cases: A customer service agent bound to a messaging channel can disable routing to always use a cheap model (saving \$200+/month), while a research agent can disable routing to always use the strongest model for quality assurance.
### Multi-Slot Model Architecture
Each agent can be configured with 11+ independent model slots for different task types:
| Slot | Purpose | Example |
| ------------- | ----------------------------------- | ----------------- |
| **Main** | Primary conversation model | Claude Sonnet 4 |
| **Lite** | Title generation, quick summaries | GPT-4o-mini |
| **Light** | Lightweight auxiliary tasks | DeepSeek V4 Flash |
| **Reasoning** | Complex analysis, planning | o4-mini |
| **Vision** | Image understanding, visual QA | GPT-4o |
| **Research** | Deep research, web browsing | Gemini 2.5 Pro |
| **Safety** | Content moderation, risk assessment | Claude Haiku |
| **Fallbacks** | Auto-switches on failure per slot | Configurable |
Each slot supports per-agent override (inherit or customize), with automatic fallback to the main model when unset. The model discipline system detects weak models and injects behavioral constraints to ensure quality output regardless of model tier.
### Thinking Intensity
6 levels of reasoning depth, adjustable per conversation:
`off` → `low` → `medium` → `high` → `xhigh` → `max`
Each model remembers your preferred thinking level via localStorage.
## Prompt Modes
Three prompt modes control system prompt construction:
| Mode | Description | Token Cost |
| ------------ | -------------------------------- | -------------- |
| **Minimal** | Essential instructions only | \~1,765 tokens |
| **Standard** | Full capabilities with tools | \~2,200 tokens |
| **Extended** | All features + context injection | Variable |
Myrm's optimized system prompt uses only \~1,765 tokens in minimal mode — **86% less** than comparable platforms (Hermes: \~15,520, OpenClaw: \~18,000).
## Custom System Prompt
Each agent can have a custom system prompt that defines its personality, expertise, and behavioral rules. This is combined with Myrm's core rules (safety, tool usage, etc.) at runtime.
## Tool Configuration
Agents can access:
* **Built-in tools**: File operations, terminal, browser, search, code execution, workspace `@codebase` overview + grep/glob exploration
* **MCP tools**: External tools via Model Context Protocol servers
* **Skills**: Reusable task-specific capabilities
Tools can be enabled/disabled per agent, with approval policies configured individually.
### Progress Planes
The agent config panel offers progress modes (off by default — zero Turn1 token cost when disabled):
| Mode | Built-in Tool | Best For |
| ------------ | ------------- | -------------------------------------------------------------------------------------------- |
| **Planning** | `todo_write` | Multi-step task breakdown and live progress (deer-flow / Cursor TodoWrite style) |
| **Kanban** | kanban\_\* | Cross-session board and DAG orchestration (chat: orchestrator 3 tools; task worker: 6 tools) |
With Planning enabled, todos persist in the chat sandbox under `{sandbox}/.myrm/progress/todos.json`; CompletionGuard blocks premature completion when file writes exist but todos remain incomplete. The frontend merges repeated SSE `tasks_steps` events by `step_key` so ProgressSteps never duplicate on re-emit. Planning is **off by default** (\~150 tokens when enabled) — simple Q\&A pays zero progress-tool tax.
### Deferred Tool Loading
Not all tools need to occupy the LLM prompt at all times. Myrm splits tools into two tiers:
| Tier | Behavior | Examples |
| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Immediate** | Always available in the prompt when enabled | File ops, terminal, search, browser, **image/video/TTS when you toggle them in Agent config** (AgentDeclared eager mount) |
| **Deferred** | Loaded on demand when intent is detected | UI rendering (`render_ui`), **cron management (default)**, computer use, optional integrations |
**Media tools & credentials**: When you enable Image / Video / TTS in the Agent built-in tools panel, those tools appear in Turn 1 **only if** a provider API key or media gateway is configured in Settings → Model Service. If credentials are missing, the UI shows an inline amber warning with a link to Settings — the agent will not crash or expose broken tool schemas.
This saves approximately 4,000 tokens per turn for agents with many *deferred* tools configured, while media tools you explicitly opt into are immediately callable without an extra discovery step.
### Skill Hot-Reload
When you modify a skill's configuration (via GUI or API), the running agent detects the change and reinitializes in-session. No restart, no reconnect — the updated skill is live immediately.
## Memory
Each agent has:
* **Agent-specific memory**: Knowledge unique to this agent
* **Global shared memory**: Knowledge accessible by all agents
Memory persists across sessions, enabling agents to learn and adapt. See [Memory System](/docs/core-concepts/memory-system) for details.
## Personality
16 built-in personality presets (8 professional + 8 creative) with:
* Chinese and English bilingual support
* Emoji + tone customization
* Category-based gallery in the GUI
* Custom personality creation
## Sub-Agent Orchestration
Complex tasks can be decomposed using 7 orchestration patterns:
| Pattern | Description |
| ---------------- | ------------------------------------------------------------------------ |
| **Chain** | Sequential execution A → B → C with structured handover state |
| **DAG** | Directed acyclic graph with dependency resolution and concurrency limits |
| **Batch** | Parallel independent tasks with aggregated results |
| **Race** | Multiple agents compete, fastest correct result wins |
| **Verified** | Worker + independent Verifier cross-validation in sandbox |
| **Swarm** | Autonomous multi-agent fission and merge |
| **Alternatives** | N agents generate competing solutions, user picks the best |
### Role Boundaries & Tool Safety Isolation
Every sub-agent inherits a `SubagentConfig` — a 21-field declarative profile that defines its responsibilities, permissions, and resource limits:
| Control Layer | Fields | Effect |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Responsibility** | `system_prompt`, `display_name`, `description` | Declares what the agent does and doesn't do |
| **Tool Access** | 4-layer isolation: type admission → global blocklist → per-config allow/blocklist → parent superset constraint | Prevents privilege escalation — child can never exceed parent's toolset |
| **Data Scope** | `workspace_policy` (3 levels) + `memory_isolation` (3 levels) | Controls which files and memories each agent can access |
| **Model Strategy** | `model_selection` with 3-level resolution chain (config → model → parent fallback) | Per-agent model assignment with safety fallbacks. Toolbar model switch is **memory-sticky** (not auto-persisted); refresh reverts to saved profile. Explicit **Update** in Config Panel to persist changes. |
| **Resource Budget** | `budget_tokens` + `max_cost_usd` + `max_children` + `max_descendants` | 4-dimensional budget guard with progressive response |
| **Orchestration Role** | `delegation_role` (LEAF / ORCHESTRATOR) + `max_spawn_depth` | Controls delegation hierarchy depth |
| **Context Isolation** | `context_mode` (isolated / fork) + `max_fork_tokens` | Prevents context leakage between agents |
The GUI agent config editor provides 5 dedicated panels (Skills / MCP / Built-in Tools / Subagents / Instruction) for visual configuration, with AI-assisted prompt generation and ActionSpace Accuracy Radar for coverage analysis.
### External Agent Delegation (ACP)
Delegate tasks to external coding agents via the ACP protocol:
* **Claude Code** — Anthropic's coding agent
* **Codex CLI** — OpenAI's coding agent
* **Gemini CLI** — Google's coding agent
* **Any ACP-compatible agent** — extensible via RuntimePool
The `delegate_to_agent` tool allows seamless handoff with full context injection, persistent/oneshot session modes, and automatic retry.
**Web chat benefits:** within the same conversation, external CLI agents reuse their session (`--resume`) so multi-turn delegation keeps context without cold starts. A per-chat turn lock serializes concurrent requests from multiple tabs or rapid clicks; cancel remains responsive (lock-exempt) so runs never deadlock. Direct-only agents skip mounting the delegate tool to save tokens when you only need the built-in visual CLI path.
**Per-agent `external_cli` switch (Jul 2026):** under **Settings → Developer → External Agents**, Myrm auto-detects CLIs on PATH in local mode — you do **not** need Anthropic subscription credentials if Claude Code is already configured with a third-party model. The Settings badge shows **CLI ready** (not a scary “not logged in”) when the binary is usable. Enable **External CLI** only on agents that should call `delegate_to_agent` at runtime (e.g. General Assistant, Code Developer). Writer/Research presets stay OFF by default — they skip \~216 Turn1 schema tokens and avoid eager RuntimePool init. Both Settings and the Agent builtin-tools panel show cross-hints; the chat panel no longer warns “no backend” when auto-detect finds a CLI.
**Verified (Jul 10 2026):** 108+ backend integration/unit tests green (including `test_external_cli_live_e2e.py` direct claude-code PONG); Chrome E2E on `:3000` confirms Writer/Research presets hide the chip, General/Developer show it, Developer → Add Agent → Claude Code shows **CLI ready**, and live `mimo-v2.5-pro` → delegate → Claude Code returns **PONG** with task steps + tool trace in the chat UI.
**Migrating from Hermes or AionUi-style tools:** keep your installed Claude Code / Codex / Gemini CLI — Myrm auto-detects them in Settings. You gain optional delegation on top of Myrm's own agent engine, MCP ecosystem, 5-layer approvals, and SubAgent orchestration without giving up external CLI strengths. Deleting a chat immediately stops any pooled external CLI process—no orphaned background agents.
### Google A2A Protocol
Discover and integrate third-party agents via the standard Google Agent-to-Agent protocol. AgentCard resolution includes SSRF protection and TTL caching.
See [Kanban & Orchestration](/docs/core-concepts/kanban-orchestration) for details.
## Agent Profile: Precision Without Crosstalk
Each Agent Profile is a full-dimension configuration unit — far beyond simple skill grouping.
| Dimension | Configurable |
| ------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| **Skills** | `skill_ids[]` — exact set of skills this agent can use |
| **Model** | Per-agent model selection (different agents, different models) |
| **Built-in Tools** | `enabled_builtin_tools[]` — whitelist of 15 canonical tool IDs (py↔ts contract; legacy IDs like `image_gen` rejected with 422) |
| **MCP Tools** | `mcp_tool_selections{}` — per-server tool selection |
| **Security** | `security_overrides{}` — independent security policy |
| **Sub-Agents** | `subagent_ids[]` — opt-in multi-layer collaboration. Multiple agents in a unified sandbox natively share files and browser with zero sync cost. When enabled, agents can delegate sub-tasks to specialists automatically |
| **Notifications** | `notify_targets[]` — proactive push; dynamic running-channel picker + pairing recipient whitelist + workspace-bounded attachments; tool loads only when configured (zero token otherwise) |
| **Browser Config** | 4-axis: engine (Chromium/Firefox), source (auto/extension/launch), dialog policy, session recording |
| **System Prompt** | Custom personality and behavioral rules |
| **Memory** | Independent memory + global shared memory |
### How It Prevents Skill Crosstalk
When an agent has too many skills loaded, the LLM may invoke irrelevant ones — a problem known as "crosstalk." Myrm solves this with 5 layers:
1. **Agent Profile** — Each agent loads only its designated skills via `skill_ids[]`
2. **Tool Condition Activation** — Skills auto-show/hide based on available tools via `requires_tools` / `fallback_for_tools`
3. **Progressive Disclosure (L0–L3)** — Only relevant skill details are expanded to full content
4. **Noise Gauge** — Skills exceeding noise thresholds are automatically attenuated
5. **Hybrid Retrieval** — Qdrant vector search selects the most relevant skill for each query
### Built-in Tools SSOT (Jul 2026)
* **15 canonical IDs** — 14 UI-togglable IDs plus **agent baseline** `file_ops` / `code_execute` (always Turn1 eager, no panel toggle).
* **27 preset agent matrices** — initializer syncs on startup; gallery and settings list show all 27 built-ins (`AGENT_LIST_BUILTIN_PAGE_SIZE=50` default; chips from `enabled_builtin_tools`).
* **Single write path** — `persist_enabled_builtin_tools` validates before DB writes; legacy IDs return 422 instead of silent failure.
* **Default profile** — UI defaults to `web_search` + `memory` + **`structured_clarify`** (structured multi-question forms); file/shell capabilities are always on via agent baseline. Form payload uses **`requires_confirmation: bool`** (replacing competitor-style 5-type enums); when `true`, WebUI renders an amber risk-confirmation emphasis.
* **User switch ON → Turn1 direct use** — default or manually enabled builtins (including **cron** when opted in, **structured\_clarify**, render\_ui, computer\_use, x\_search, delegate\_to\_agent) and bound-skill tools appear in the first-turn LLM schema without calling `discover_capability` first. **Cron default is OFF (discoverable)** — only users who enable it pay \~827 tok eager schema; OpenClaw/Hermes always mount cron in Turn1 with no per-agent opt-out. **`structured_clarify` OFF → zero `ask_question_tool` schema** — unlike competitors that bake clarification into permanent prompts. Harness **`ClarificationGuardMiddleware`** enforces at most one `ask_question_tool` per turn and blocks parallel tools (aligned with Hermes single-turn `clarify` constraint).
* **active\_tool\_groups SSOT** — `derive_active_tool_groups()` derives enabled groups in one place, preventing false `capability_gap` when render\_ui or media groups are already on.
* **Full matrix regression** — `CAPABILITY_GAP_REGISTRY` covers **14 GUI-togglable** builtins (web\_search, memory, cron, answer\_tool, browser, render\_ui, computer\_use, wiki, kanban, planning, **structured\_clarify**, media trio). Agent baseline `file_ops` / `code_execute` are runtime-forced and excluded from gap hints. Editable whiteboards: [Diagrams via MCP](/docs/guides/diagram-via-mcp).
* **Entitlement gap** — **preflight** scans each user message before the agent loop (SSE `capability_gap` / `skill_gap` without mutating Turn1 schema); discover miss uses the same registry. WebUI receives preflight events via **`/api/v1/workspace/stream` multiplex** (listener registered before POST so early chunks are buffered). Toast offers one-click enable/bind; if clicked while the stream is still loading, `pendingGapRetry` auto-resends after **MESSAGE\_END**, **ERROR**, or **CANCEL** (no second manual send).
* **Session tools panel** — the chat input **wrench** icon shows live **Turn1-bound** tools via SSE `tools_snapshot` (with layer badges), reflecting what the Agent can call right now—not just what is toggled in settings.
* **Control-plane tools (zero default Turn1 token)** — orchestration signals (Deep Research), CompletionGuard (`_completion_check`), Verifier (`submit_verdict`), and Workflow PTC (`spawn_subagent`/`notify`) are registered for audit but **excluded from default Chat bind** — casual chat does not pay spawn/orchestration schema tax. Measured default profile: **15 tools / \~8,354 tok tool layer** (Jul 2026 SSOT).
### vs. Competitor Approaches
Some platforms use "Skill Bundles" — YAML files that group skills under a slash command. Myrm's Agent Profile is a complete superset:
| Capability | Skill Bundles | Agent Profile |
| -------------------- | :-------------------------: | :----------------------------: |
| Multi-skill grouping | YAML `skills[]` | GUI-configurable `skill_ids[]` |
| Model selection | No | Per-agent model |
| Tool-level control | No | Whitelist per agent |
| Security policy | No | Per-agent overrides |
| Anti-crosstalk | Single layer (fewer skills) | 5-layer defense |
| Configuration | CLI + YAML files | Visual GUI editor |
## Agent Bindings
Agents can be bound to different contexts:
| Context | Description |
| ------------------- | --------------------------------------------- |
| **Web Sessions** | Default agent for new chat conversations |
| **Scheduled Tasks** | Agent used for cron job execution |
| **Channels** | Agent assigned to specific messaging channels |
| **IM Topics** | `/bind` command assigns agent to a chat topic |
Unbound contexts use the default general-purpose agent. Switch agents anytime via the GUI or the `/bind` / `/unbind` commands in messaging channels.
## Slash Command Bindings
Each agent can define custom slash commands that trigger one or more skills in a single turn.
### Single Skill
Map a command like `/deploy` to one skill:
```yaml theme={null}
command_name: deploy
skill_ids: [deploy_skill]
description: Deploy to production
```
### Multi-Skill Bundle
Combine multiple skills into a single command with optional guidance:
```yaml theme={null}
command_name: daily-report
skill_ids: [data_collector, report_generator, email_sender]
instruction: Collect today's metrics, generate a summary, and email it to the team.
```
When triggered, all SOPs are merged and injected into a single LLM turn with automatic token budget protection (12K char soft cap).
### How It Works
1. **Configure** — In the Agent editor, select multiple skills from a dropdown, optionally add an instruction
2. **Trigger** — Type `/daily-report` in the slash palette (WebUI), desktop app, or any IM channel
3. **Execute** — The harness loads all SOPs, enforces the token budget, and runs them as one coordinated turn
### Per-Agent Isolation
Each agent has its own set of command bindings. A "Code Assistant" agent's `/review` is completely independent from an "Ops Assistant" agent's `/deploy` — no crosstalk, no conflicts.
## Profile Snapshots & Rollback
Every configuration change creates an automatic snapshot. You get worry-free experimentation with one-click undo:
| Feature | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Auto-snapshot** | Each update creates a versioned snapshot (up to 10 retained) |
| **One-click rollback** | Revert to any previous configuration state instantly |
| **Pre-rollback protection** | Rolling back auto-saves the current state first, so you can always undo the undo |
| **Selective history** | Cosmetic changes (avatar-only) do not pollute the snapshot timeline |
| **Cache-safe** | Rollback invalidates the profile resolver cache immediately — the agent uses the restored config on the very next turn |
Access snapshot history from **Agent Settings > Version History**.
No competitor offers automatic multi-version profile snapshots with rollback. Hermes, OpenClaw, and ChatGPT require manual backup before changes — one mis-click permanently overwrites your configuration.
## Export, Import & Clone
Share agent configurations across teams or back them up externally:
| Operation | Description |
| ---------- | -------------------------------------------------------------------------------------- |
| **Export** | Downloads the full agent profile as JSON (credential fields auto-stripped for safety) |
| **Import** | Creates a new agent from any exported JSON (supports both individual and team formats) |
| **Clone** | One-click duplicate within your workspace — new UUID, same configuration |
For team agents, export bundles the leader + all member profiles in a single versioned package.
Sensitive fields (API keys, OAuth tokens, gateway credentials) are automatically removed during export to prevent accidental credential leaks when sharing.