# Agent Configuration Guide

MindRoom uses a YAML-based configuration system that makes it easy to customize agents for your specific needs.
You can create agents by editing `config.yaml`, or generate a starter config with `mindroom config init`.

## Configuration File

The default configuration file is `config.yaml`.
MindRoom searches for it in this order: `MINDROOM_CONFIG_PATH` env var, `./config.yaml`, `~/.mindroom/config.yaml`.
You can generate a starter config with `mindroom config init`.

## Configuration Structure

The configuration file has these top-level sections:

1. **agents** - Configure individual agents and their capabilities
2. **teams** - Multi-agent collaboration groups
3. **cultures** - Shared principles and practices applied to groups of agents
4. **models** - Define available AI models and their providers
5. **defaults** - Default settings inherited by all agents
6. **memory** - Memory system configuration (mem0, file-backed, or disabled)
7. **knowledge_bases** - File-backed RAG knowledge bases
8. **router** - Agent routing system configuration
9. **voice** - Voice message processing (STT + command intelligence)
10. **authorization** - Fine-grained user and room permissions
11. **matrix_room_access** - Managed room access mode and discoverability
12. **matrix_space** - Optional root Matrix Space for grouping rooms
13. **mindroom_user** - Internal MindRoom user account settings
14. **timezone** - Timezone for scheduled tasks (default: `UTC`)
15. **bot_accounts** - Non-MindRoom bot Matrix user IDs (e.g., bridge bots)
16. **rooms** - Managed Matrix room metadata for standalone rooms and dashboard-created rooms
17. **room_models** - Per-room model overrides
18. **plugins** - Plugin paths for tool/skill extensions

## Model Configuration

Before configuring agents, you need to define which AI models are available.
MindRoom supports multiple model providers:

```yaml
models:
  default:  # Default model used when agent doesn't specify one
    provider: "ollama"
    id: "devstral:24b"

  anthropic:
    provider: "anthropic"
    id: "claude-haiku-4-5"

  ollama:
    provider: "ollama"
    id: "devstral:24b"
    # For ollama, you can add:
    # host: "http://localhost:11434"

  openrouter:
    provider: "openrouter"
    id: "anthropic/claude-sonnet-5"
```

Each model entry supports these fields:
- **provider** (required) - Provider name (see list below)
- **id** (required) - Model ID specific to the provider
- **host** - Optional host URL (e.g., for Ollama or OpenAI-compatible servers)
- **api_key** - Optional API key (usually set via env vars instead)
- **extra_kwargs** - Additional provider-specific parameters (e.g., `base_url`)
- **context_window** - Actual provider context window size in tokens; when set, MindRoom uses it for compaction summary input and as the default replay-planning window unless compaction config sets a smaller `replay_window_tokens`, and applies a final replay-fit step that may reduce or disable persisted replay for that run; on `vertexai_claude` models it additionally enables request-time fitting that trims replayed history when a request would exceed the window

### Supported Providers

- **anthropic** - Claude models (requires `ANTHROPIC_API_KEY`)
- **azure** - Azure OpenAI deployments (requires `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT`)
- **openai** - OpenAI and OpenAI-compatible models (requires `OPENAI_API_KEY`)
- **ollama** - Local models via Ollama (requires `OLLAMA_HOST`, defaults to `http://localhost:11434`)
- **openrouter** - Access multiple models through OpenRouter (requires `OPENROUTER_API_KEY`)
- **gemini** / **google** - Google Gemini models (requires `GOOGLE_API_KEY`)
- **vertexai_claude** - Claude models via Vertex AI (requires GCP credentials)
- **groq** - Groq-hosted models (requires `GROQ_API_KEY`)
- **deepseek** - DeepSeek models (requires `DEEPSEEK_API_KEY`)
- **zai** - Z.ai GLM models (requires `ZAI_API_KEY`)
- **cerebras** - Cerebras-hosted models (requires `CEREBRAS_API_KEY`)

## Memory Configuration

The memory system helps agents remember and retrieve relevant information:

```yaml
memory:
  backend: "mem0"  # Global default backend: "mem0", "file", or "none"
  team_reads_member_memory: false  # Allow team reads to access member agent memories
  embedder:
    provider: "ollama"  # Options: openai, ollama, sentence_transformers
    config:
      model: "nomic-embed-text"  # Embedding model to use
      host: "http://localhost:11434"  # Ollama host URL
      # api_key: null  # Optional API key (usually from env)
      # dimensions: null  # Optional embedding dimension override
  llm: null  # Optional LLM for memory operations (provider + config dict)
  file:
    max_entrypoint_lines: 200  # Max lines preloaded from MEMORY.md
  auto_flush:
    enabled: false  # Background file-memory auto-flush (see memory consolidation plan)
    flush_interval_seconds: 1800
```

You can override the memory backend per agent with `memory_backend`.
When an agent uses `memory_backend: file`, its file memory lives in the canonical workspace root.
When an agent uses `memory_backend: none`, built-in durable memory is disabled for that agent.
Use `provider: "sentence_transformers"` to run embeddings locally inside MindRoom with the optional `sentence-transformers` package.

## Router Configuration

The router determines which agent or team should handle a user's request:

```yaml
router:
  model: "default"  # Which model to use for routing decisions (references models section)
  startup_thread_prewarm: true  # Optional: participate in room-level startup prewarm for rooms already joined at first sync
```

## Agent Configuration Structure

Each agent in the YAML file follows this structure.
Tool entries can be plain strings or single-key dicts with inline config overrides:

```yaml
agents:
  agent_name:
    display_name: "Human-readable name"
    role: "What the agent does"
    tools:
      - tool_name_1
      - tool_name_2
      # Per-agent tool config override (single-key dict):
      # - shell:
      #     extra_env_passthrough: "DAWARICH_*"
      #     enable_run_shell_command: true
    include_default_tools: true  # Optional: merge defaults.tools into this agent's tools
    skills:
      - skill_name_1
    instructions:
      - "Specific behavior instruction 1"
      - "Specific behavior instruction 2"
    rooms:
      - lobby
      - dev
    accept_invites: true  # Optional: accept direct room invites and auto-join invited rooms
    learning: true  # Optional: enable Agno Learning (defaults to true)
    learning_mode: "always"  # Optional: "always" or "agentic"
    memory_backend: "file"  # Optional: per-agent override ("mem0", "file", or "none")
    knowledge_bases:
      - docs
    context_files:
      - SOUL.md
      - USER.md
    model: "anthropic"  # Optional: specific model for this agent (overrides default)
    thread_mode: "thread"  # Optional: "thread" or "room"
    startup_thread_prewarm: true  # Optional: participate in room-level startup prewarm for rooms already joined at first sync
    delegate_to: [other_agent]  # Optional: agents this one can delegate to
```

### Configuration Fields

- **agent_name**: The configured identifier used for agent config and aliases; provisioning may propose a `mindroom_<agent_name>` username when an account is missing, but runtime identity always comes from persisted Matrix account state.
- **display_name**: A friendly name shown in conversations
- **role**: A brief description of the agent's purpose
- **tools**: List of tools the agent can use — plain strings or single-key dicts with inline config overrides (see Available Tools below and [Per-Agent Tool Configuration](../configuration/agents.md#per-agent-tool-configuration))
- **include_default_tools**: Whether to merge `defaults.tools` into this agent's `tools` (default: true)
- **skills**: Skill names the agent can use
- **instructions**: Specific guidelines for the agent's behavior
- **rooms**: List of room aliases where this agent should be active
- **accept_invites**: Whether this agent accepts direct Matrix room invites and auto-joins invited rooms (default: `true`)
- **markdown**: Per-agent override for markdown formatting (default: inherits from `defaults.markdown`; `null` means inherit)
- **learning**: Enable Agno Learning for this agent (default: inherits from `defaults.learning`, which defaults to `true`)
- **learning_mode**: Learning mode (`always` or `agentic`, default: `always`)
- **memory_backend**: Optional per-agent memory backend override (`mem0`, `file`, or `none`), inherits from `memory.backend` when omitted
- **knowledge_bases**: List of configured knowledge base IDs assigned to this agent
- **context_files**: File paths relative to the agent's canonical workspace root (`<storage_root>/agents/<name>/workspace/`) loaded into each agent instance; edits take effect on the next reply without restarting
- **model**: (Optional) Specific model to use for this agent, overrides the default model
- **allow_self_config**: (Optional) When `true`, gives the agent a scoped tool to read and modify its own configuration at runtime (default: inherits from `defaults.allow_self_config`, which defaults to `false`)
- **thread_mode**: Conversation threading mode: `thread` (default) creates Matrix threads per conversation, `room` uses a single continuous conversation per room (ideal for bridges/mobile)
- **room_thread_modes**: Per-room thread mode overrides keyed by room alias/name or Matrix room ID
- **startup_thread_prewarm**: When enabled, this bot may prewarm recent thread snapshots for rooms already joined when first sync completes, which can reduce cold-cache latency for early thread replies after startup
- **num_history_runs**: Number of prior Agno runs to include as history context (per-agent override)
- **num_history_messages**: Max messages from history (mutually exclusive with `num_history_runs`)
- **compress_tool_results**: Compress tool results in history to save context (per-agent override, inherits a default of `false`, and can invalidate Anthropic/Vertex Claude prompt caches when enabled)
- **compaction**: Optional per-agent required-compaction overrides (`enabled`, `threshold_tokens`, `threshold_percent`, `replay_window_tokens`, `reserve_tokens`, `model`, `fallback_model`, `timeout_seconds`); when the active runtime model has a known `context_window`, MindRoom always computes a replay plan for the current run and reduces or disables persisted replay when needed.
Automatic destructive compaction is enabled by default through `defaults.compaction`, but it runs only when raw history exceeds the hard replay budget for the next reply.
`threshold_tokens` and `threshold_percent` set a soft trigger budget for planning metadata and compaction notices; crossing that soft trigger while still within the hard budget leaves the stored session unchanged and relies on replay fitting.
`replay_window_tokens` can cap persisted replay and required-compaction planning below the model's real context window without lowering the provider request limit.
If the active model window is unknown, an explicit `replay_window_tokens` still supplies the replay-planning window.
Each compaction summary input chunk is sized independently from the selected compaction model's real `context_window`, after reserve, prompt overhead, and a safety margin.
Each primary, retry, and fallback summary request uses `timeout_seconds`, which defaults to 600 seconds, while an explicitly shorter provider timeout remains the stricter cap.
Destructive compaction requires the resolved summary input budget to exceed 2,000 tokens.
With the default `reserve_tokens`, this makes destructive compaction unavailable when the compaction model's context window is roughly 10,000 tokens or smaller; lowering `reserve_tokens` restores availability for such small windows.
Set `enabled: false` in defaults or the agent override to disable automatic pre-reply compaction.
Manual `compact_context` records a durable request that runs before the next reply in the same conversation scope.
Manual `compact_context` remains available when a compaction model and context window are configured and the resolved summary input budget exceeds 2,000 tokens.
Required compaction runs before the reply with a Matrix lifecycle notice that is edited in place; otherwise MindRoom leaves the session unchanged and relies on replay fitting for that reply.
Compaction rewrites the live session so compacted history moves into `session.summary` while only recent raw runs remain in `session.runs`
- **max_tool_calls_from_history**: Max tool call messages replayed from history (per-agent override)
- **show_tool_calls**: Whether to show tool call details inline in responses (per-agent override). When disabled, routed tools may still show generic worker warmup copy, but it never includes tool identifiers or tool-trace metadata
- **worker_tools**: Tool names to route through scoped workers (overrides defaults; `null` uses the built-in default routing policy)
- **worker_scope**: Worker runtime reuse mode for routed tools: `shared`, `user`, or `user_agent`
- **delegate_to**: List of agent names this agent can delegate tasks to via tool calls
- **private**: Optional requester-private state config for per-requester materialized instances

### File-Based Context Loading

`context_files` is useful for OpenClaw-style workspace context:

- Paths are relative to the agent's canonical workspace root (`<storage_root>/agents/<name>/workspace/`)
- `context_files` are injected in listed order
- Content is refreshed for each freshly built agent instance, so normal replies pick up edits on the next request

## Teams Configuration

Teams let multiple agents collaborate on requests:

```yaml
teams:
  research_team:
    display_name: "Research Team"
    role: "Collaborative research assistant"
    agents: [research, code]
    mode: coordinate  # "coordinate" or "collaborate"
    model: "default"  # Optional model override
    startup_thread_prewarm: true  # Optional: participate in room-level startup prewarm for rooms already joined at first sync
    num_history_runs: 8  # Optional team-scoped replay policy
    num_history_messages: null  # Optional; mutually exclusive with num_history_runs
    max_tool_calls_from_history: 6  # Optional replay trimming for tool calls
    compaction:  # Optional team-scoped required-compaction overrides
      # Soft thresholds do not compact by themselves while history still fits.
      enabled: true
      threshold_percent: 0.8
      reserve_tokens: 16384
      timeout_seconds: 600
    rooms:
      - lobby
```

- **coordinate**: A lead agent orchestrates the others
- **collaborate**: All members respond in parallel with a consensus summary
- **startup_thread_prewarm**: Optional background prewarm for recent thread snapshots in rooms this bot already joined when first sync completes, which can reduce cold-cache latency for early thread replies after startup

Startup thread prewarm is a background, best-effort cache warmup for rooms already joined when first sync completes.
- **num_history_runs / num_history_messages**: Optional team-owned replay policy for named teams
- **max_tool_calls_from_history**: Optional cap on replayed tool call messages for the shared team scope
- **compaction**: Optional team-owned required-compaction overrides for the shared team scope

Named teams use these explicit team settings for replay and compaction when provided.
Dynamic teams have no named config block, so they inherit replay and compaction settings from `defaults`.

## Cultures Configuration

Cultures define shared principles applied to groups of agents:

```yaml
cultures:
  engineering:
    description: "Follow clean code principles and write tests"
    agents: [code, data_analyst]
    mode: automatic  # "automatic", "agentic", or "manual"
```

## Knowledge Bases Configuration

Knowledge bases provide file-backed semantic RAG or files-only context to agents:

```yaml
knowledge_bases:
  engineering_docs:
    path: ./knowledge_docs  # Path to documents folder
    mode: semantic  # "semantic" builds embeddings; "files" skips embeddings for direct file-tool access
    watch: false  # Direct external edits require reindex; API mutations still schedule refresh
    chunk_size: 5000  # Characters per indexed chunk
    chunk_overlap: 0  # Overlap between adjacent chunks
    git:  # Optional: sync from a Git repository
      repo_url: "https://github.com/org/docs.git"
      branch: main
      poll_interval_seconds: 300  # Interval for background Git refresh scheduling
      # lfs: false  # Enable Git LFS support (requires git-lfs on the runtime host)
      # sync_timeout_seconds: 3600  # Abort a hung git command after this many seconds
      # credentials_service: null  # CredentialsManager service for private HTTPS repos
      # skip_hidden: true  # Skip hidden files/folders during indexing
      # include_patterns: []  # Root-anchored glob patterns to include
      # exclude_patterns: []  # Root-anchored glob patterns to exclude
```

Assign knowledge bases to agents via `knowledge_bases: [engineering_docs]` in the agent config.
Use `mode: files` for sources that workspace-aware agents should inspect with file, shell, or coding tools instead of `search_knowledge_base`.

## Voice Configuration

Enable voice message processing with speech-to-text:

```yaml
voice:
  enabled: false
  visible_router_echo: true  # Show STT placeholder or direct fallback when STT is disabled
  stt:
    provider: openai
    model: gpt-4o-transcribe
    # api_key: null  # Optional API key for STT service
    # host: null  # Optional host URL for self-hosted STT
  intelligence:
    model: default  # Model for command recognition
```

## Authorization Configuration

Fine-grained access control for rooms and agents:

```yaml
authorization:
  default_room_access: false
  global_users:
    - "@owner:example.com"
  room_permissions:
    dev: ["@developer:example.com"]
  aliases:
    "@alice:example.com": ["@telegram_123:example.com"]
  agent_reply_permissions:
    "*":
      - "@owner:example.com"
```

- **global_users**: Users with access to all rooms
- **room_permissions**: Per-room user allowlists
- **aliases**: Map canonical Matrix user IDs to bridge aliases
- **agent_reply_permissions**: Per-agent/team reply allowlists (`*` key applies to all entities)

## Matrix Room Access Configuration

Control how managed rooms are created and accessed:

```yaml
matrix_room_access:
  mode: single_user_private  # "single_user_private" or "multi_user"
  multi_user_join_rule: public  # "public" or "knock" (for multi_user mode)
  publish_to_room_directory: false
  invite_only_rooms: []  # Room keys that stay invite-only even in multi_user mode
  reconcile_existing_rooms: false  # Reconcile existing rooms on startup
  room_admins: []  # Matrix user IDs granted admin power (100) in every managed room
```

## Matrix Space Configuration

Optionally group all managed rooms under a root Matrix Space:

```yaml
matrix_space:
  enabled: true  # Create and maintain a root Space (default: true)
  name: "MindRoom"  # Display name for the root Space
```

Concrete Matrix users in `authorization.global_users` receive root Space admin power.
The configured `mindroom_user` also receives root Space admin power when the internal account exists.
Room-specific `authorization.room_permissions` users do not become root Space admins unless they are also global users.
Root Space admin reconciliation is grant-only and preserves existing Matrix admins.
Removing a user from `authorization.global_users` stops future MindRoom authorization but does not automatically demote that user in the Space.

## Defaults Configuration

Default settings inherited by all agents unless overridden:

```yaml
defaults:
  tools: [scheduler]  # Tools added to every agent
  markdown: true
  enable_streaming: true
  show_stop_button: true
  learning: true
  learning_mode: "always"  # "always" or "agentic"
  compress_tool_results: false
  compaction:
    enabled: true
    threshold_percent: 0.8
    reserve_tokens: 16384
    timeout_seconds: 600
  show_tool_calls: true
  allow_self_config: false
  max_preload_chars: 50000  # Hard cap for context_files preload
  tool_output_auto_save_threshold_bytes: 51200  # Auto-save supported tool outputs larger than 50 KiB
  thread_summary_model: null  # Use the default model when unset
  thread_summary_temperature: 0.2  # Set null to omit temperature and use provider defaults
  thread_summary_first_threshold: 1  # First automatic thread summary after 1 message
  thread_summary_subsequent_interval: 10  # Re-summarize after each additional 10 messages
  # num_history_runs: null  # Default: all
  # num_history_messages: null  # Mutually exclusive with num_history_runs
  # max_tool_calls_from_history: null  # Default: no limit
  # worker_tools: null  # Default: use built-in routing policy
  # worker_scope: null  # Default: no worker scoping
```

Automatic thread summaries use `defaults.thread_summary_temperature` when the selected provider supports runtime temperature overrides.
MindRoom always uses provider temperature defaults for Vertex Claude, Claude Opus 5, Sonnet 5, Fable 5, and direct Google Gemini 3.6 Flash and Gemini 3.5 Flash-Lite thread summaries.
When a thread has no trusted prior summary, its first automatic summary call is summary-only so a useful thread title appears early.
The next scheduled automatic summary refresh also returns one to three tags when the thread has no existing tags, whether the prior summary was automatic or manual.
Initial tags therefore use the same summary model, room override, temperature, prompt, and background task as the refreshed summary.
After initial enrichment completes, later summary refreshes never regenerate tags.

## Room Configuration

Agents can be assigned to specific rooms in your Matrix server.
This allows you to create topic-specific rooms, control agent access, and organize assistants by domain.

### How Rooms Work

1. **Room Aliases**: In `config.yaml`, you specify simple room aliases like `lobby`, `dev`, `research`
2. **Automatic Creation**: When you run `mindroom run`, it automatically creates any missing rooms
3. **Agent Assignment**: Agents are automatically invited to their configured rooms
4. **Room Persistence**: Room information is stored in `matrix_state.yaml` (auto-generated)

### Example Room Setup

```yaml
agents:
  code:
    display_name: "CodeAgent"
    role: "Programming assistant"
    tools: [file, shell]
    rooms:
      - lobby      # Available in main lobby
      - dev        # Available in development room

  research:
    display_name: "ResearchAgent"
    role: "Information gathering"
    tools: [duckduckgo, wikipedia, arxiv]
    rooms:
      - lobby      # Available in main lobby
      - research   # Available in research room
```

## Available Tools

Tools give agents the ability to perform specific actions.
MindRoom includes 100+ tools; the full list is available in the dashboard.
Below is a representative selection:

### Basic Tools
- **calculator** - Perform mathematical calculations
- **file** - Read, write, and manage files
- **shell** - Execute command line operations
- **python** - Run Python code snippets
- **coding** - Code generation and editing (file read/write/edit, grep, find, ls)
- **sleep** - Pause execution for a specified duration
- **reasoning** - Chain-of-thought reasoning prompts

### Data & Analysis Tools
- **csv** - Process and analyze CSV files
- **pandas** - Advanced data manipulation and analysis
- **yfinance** - Fetch financial market data
- **duckdb** - SQL queries on local data files

### Research & Information Tools
- **arxiv** - Search academic papers
- **duckduckgo** - Web search
- **googlesearch** - Google search (requires API key)
- **tavily** - AI-powered search (requires API key)
- **exa** - Neural search API (requires API key)
- **wikipedia** - Encyclopedia lookup
- **newspaper4k** - Parse and extract news articles
- **website** - Extract content from websites
- **jina** - Web reading and search via Jina Reader API
- **crawl4ai** - Advanced web crawling
- **pubmed** - Search biomedical literature

### Development Tools
- **docker** - Manage Docker containers (requires Docker installed)
- **github** - Interact with GitHub repositories (requires token)
- **jira** - Jira issue tracking (requires API token)
- **linear** - Linear issue tracking (requires API key)

### Communication Tools
- **email** - Send emails (requires SMTP configuration)
- **telegram** - Send Telegram messages (requires bot token)
- **slack** - Slack messaging (requires bot token)
- **discord** - Discord messaging (requires bot token)
- **matrix_message** - Send messages to other Matrix rooms
- **thread_summary** - Write or update a one-line Matrix thread summary with `set_thread_summary`
- **thread_model** - Show, switch, or reset the model override for the current Matrix thread (applies from the next message)

### AI & Generation Tools
- **dalle** - Generate images with DALL-E
- **gemini** - Google Gemini multimodal capabilities
- **claude_agent** - Spawn Claude sub-agents
- **subagents** - Delegate tasks to other MindRoom agents

### Productivity Tools
- **scheduler** - Schedule recurring tasks (included by default)
- **todo** - Create persistent per-thread work plans with dependencies and templates
- **gmail** - Gmail integration (requires Google OAuth)
- **google_calendar** - Calendar management (requires Google OAuth)
- **google_docs** - Google Docs creation, reading, and text editing (requires Google OAuth)
- **google_drive** - Google Drive file reading and management (requires Google OAuth)
- **google_sheets** - Spreadsheet operations (requires Google OAuth)
- **homeassistant** - Home Assistant device control (requires OAuth or long-lived access token)
- **spotify** - Spotify playback and library (requires OAuth)
- **todoist** - Task management (requires API key)
- **notion** - Notion workspace integration (requires API key)

### Special Tool Bundles
- **openclaw_compat** - Convenience bundle that expands to: shell, coding, duckduckgo, website, browser, scheduler, subagents, matrix_message (matrix_message also implies attachments via `IMPLIED_TOOLS`)

## Example Agent Configurations

### Example 1: Simple Helper Agent

```yaml
agents:
  helper:
    display_name: "HelpfulAssistant"
    role: "Provide friendly help and encouragement"
    tools: []
    instructions:
      - "Always be positive and encouraging"
      - "Offer specific, actionable advice"
      - "Ask clarifying questions when needed"
```

### Example 2: Project Manager Agent

```yaml
agents:
  project_manager:
    display_name: "ProjectManager"
    role: "Help manage software projects"
    tools:
      - file
      - shell
      - github
    instructions:
      - "Track project tasks and milestones"
      - "Generate status reports"
      - "Help with version control"
      - "Create and update documentation"
```

### Example 3: Data Science Agent

```yaml
agents:
  data_scientist:
    display_name: "DataScientist"
    role: "Analyze data and create insights"
    tools:
      - python
      - pandas
      - csv
      - calculator
    instructions:
      - "Perform statistical analysis"
      - "Create data visualizations"
      - "Clean and preprocess data"
      - "Explain findings clearly"
```

### Example 4: Research Assistant

```yaml
agents:
  researcher:
    display_name: "ResearchAssistant"
    role: "Comprehensive research and fact-checking"
    tools:
      - arxiv
      - wikipedia
      - duckduckgo
      - website
      - file
    instructions:
      - "Find credible sources"
      - "Cross-reference information"
      - "Create research summaries"
      - "Track sources and citations"
```

## Using Agents in the Multi-Agent System

Each agent has its own Matrix account.
Persisted Matrix state is the source of truth for each agent's runtime Matrix identity after provisioning or login.
Generated `mindroom_<agent>` usernames are provisioning proposals only when an account is missing.
To interact with an agent:

1. **Mention the agent by its configured name**: `@agentname`
   - Example: `@code what is 25 * 4?`

2. **In threads**: Agents continue responding based on thread context, but multi-human threads require an explicit current `@mention`
   - Start a thread by replying to any message
   - In single-human threads, the agent can continue the conversation without repeated mentions
   - Once two or more humans are participating, mention the agent again before expecting a reply

3. **Multiple agents**: You can mention multiple agents in one message
   - Example: `@research @code Compare renewable energy trends`

## Tool Requirements

Some tools need additional setup:

### Tools requiring API keys:
- **googlesearch** - Set up Google API credentials
- **tavily** - Get API key from Tavily
- **exa** - Get API key from Exa
- **github** - Create a GitHub personal access token
- **telegram** - Create a Telegram bot and get token
- **email** - Configure SMTP server details

### Tools requiring OAuth:
- **gmail**, **google_calendar**, **google_docs**, **google_drive**, **google_sheets** - Google OAuth
- **homeassistant** - Home Assistant OAuth or long-lived access token
- **spotify** - Manually supplied Spotify OAuth access token

The structured `OAuthConnectionRequired` flow applies only when a tool's MindRoom catalog metadata names an `auth_provider`, not to every tool in the list above or every `SetupType.OAUTH` integration.
When the current agent already has one of these MindRoom-managed provider tools, call an appropriate safe status, read, or list operation from that tool.
For an OAuth MCP server, use its generated `*_connection_status` or `*_list_tools` operation.
If the operation returns `oauth_connection_required: true` and provides a `connect_url`, present that exact scoped link directly and do not send the user to the dashboard.
If `requires_host_browser` is true, explain that the loopback URL (`localhost`, `127.0.0.1`, or `::1`) must be opened in a browser on the computer where MindRoom is running.
Have the target agent retry the operation after the user connects.
Do not promise that a newly configured tool can be called in the same run, because the current provider-visible tool schema may not include it yet.
Use the dashboard only as a manual alternative when the structured result does not provide a `connect_url`.

### Tools requiring software:
- **docker** - Install Docker on your system

### Tools that work immediately:
- **calculator**, **file**, **shell**, **python**, **csv**, **pandas**, **arxiv**, **duckduckgo**, **wikipedia**, **newspaper4k**, **website**, **jina**, **yfinance**, **sleep**, **reasoning**

## Complete Configuration Example

```yaml
# Memory configuration
memory:
  backend: "mem0"  # "mem0", "file", or "none"
  embedder:
    provider: "ollama"
    config:
      model: "nomic-embed-text"
      host: "http://localhost:11434"

# Model definitions
models:
  default:
    provider: "ollama"
    id: "devstral:24b"

  smart:
    provider: "anthropic"
    id: "claude-sonnet-5"

# Agent configurations
agents:
  assistant:
    display_name: "SmartAssistant"
    role: "Advanced reasoning and analysis"
    model: "smart"
    tools: []
    instructions:
      - "Provide thoughtful, detailed responses"
      - "Use advanced reasoning capabilities"
    rooms:
      - lobby

# Teams
teams:
  research_team:
    display_name: "Research Team"
    role: "Collaborative research"
    agents: [assistant]
    mode: coordinate

# Defaults
defaults:
  tools: [scheduler]
  markdown: true
  enable_streaming: true
  tool_output_auto_save_threshold_bytes: 51200
  thread_summary_model: null
  thread_summary_first_threshold: 1
  thread_summary_subsequent_interval: 10

# Router
router:
  model: "default"
  accept_invites: true

# Managed room access
matrix_room_access:
  mode: single_user_private
  room_admins:
    - __MINDROOM_OWNER_USER_ID_FROM_PAIRING__

# Timezone
timezone: "America/Los_Angeles"

# Authorization
authorization:
  default_room_access: false
  global_users:
    - __MINDROOM_OWNER_USER_ID_FROM_PAIRING__
  agent_reply_permissions:
    "*":
      - __MINDROOM_OWNER_USER_ID_FROM_PAIRING__
```

## Troubleshooting

If an agent isn't working as expected:

1. Check that all required tools are properly configured
2. Verify the YAML syntax is correct (proper indentation)
3. Ensure tool names are spelled correctly
4. Test with simpler instructions first
5. Check logs for any error messages (`mindroom run --log-level DEBUG`)

## Best Practices

1. **Clear Agent Roles**: Give each agent a specific, well-defined purpose
2. **Appropriate Tools**: Only include tools the agent actually needs
3. **Detailed Instructions**: Provide clear behavioral guidelines
4. **Test Your Agents**: Try different scenarios to ensure they behave as expected

## Tips for Writing Instructions

Good instructions are specific and actionable:

- Good: "Always cite your sources with author and publication date"
- Vague: "Be accurate"

- Good: "Explain technical concepts in simple terms"
- Vague: "Be helpful"

- Good: "Ask for clarification if the request is ambiguous"
- Vague: "Understand the user"
