Agent Configuration

This page covers the agents: section of config.yaml, where each agent is one AI actor with its own model, tools, rooms, and instructions. It also covers requester-private agents, files preloaded into an agent's prompt, naming rules, and the defaults: section that every agent inherits from.

Basic Agent

agents:
  assistant:
    display_name: Assistant
    role: A helpful AI assistant
    model: sonnet
    rooms: [lobby]

The key (assistant) is the agent's name, model names an entry under models:, and rooms lists the rooms the agent joins.

A coding agent that runs its code tools in a worker, preloads workspace notes, and replies as plain room messages in a bridged room:

agents:
  developer:
    display_name: Developer
    role: Generate code, manage files, execute shell commands
    model: sonnet
    tools:
      - file
      - github
      - shell:
          extra_env_passthrough: "DAWARICH_*"
    worker_tools: [shell, file]
    instructions:
      - Always read files before modifying them
    context_files: [AGENTS.md, USER.md]
    rooms: [lobby, dev, bridge_telegram]
    room_thread_modes:
      bridge_telegram: room
    access:
      members_of_rooms: [dev]
    delegate_to: [research]

To keep defaults.tools away from one agent:

agents:
  researcher:
    display_name: Researcher
    role: Focus on deep research
    include_default_tools: false
    tools: [duckduckgo]

Configuration Options

Unset fields that appear in the inheritance table under Defaults take the defaults value; a per-agent value overrides it. memory_backend and memory_search inherit from the top-level memory: section instead.

Private Instances

Use private when one shared agent definition should give each requester their own workspace, file memory, and knowledge index. The YAML stays shared, while each requester's files live in their own private root.

knowledge_bases:
  company_docs:
    path: ./company_docs
    watch: false

agents:
  mind:
    display_name: Mind
    role: A persistent personal AI companion
    model: sonnet
    tools: [file, shell]
    worker_tools: [file, shell]
    memory_backend: file
    private:
      per: user
      root: mind_data
      template_dir: ./mind_template
      context_files: [SOUL.md, USER.md, MEMORY.md]
      knowledge:
        path: memory
        watch: false
    knowledge_bases: [company_docs]

Here every user gets their own mind_data/ root, seeded from ./mind_template/ (for example SOUL.md, USER.md, MEMORY.md, and a memory/ folder), while company_docs stays shared by everyone. Private roots live at <storage>/private_instances/<requester scope>/<agent>/<private.root>/, not next to config.yaml, and dedicated workers mount only that root.

How a private agent behaves:

• The template directory is copied into each new private root, and template files added later are copied in without overwriting requester edits.
• The private root is created even without a template.
• private.context_files load from the private root; agent-level context_files still load from the shared agent workspace.
• With memory_backend: file, the private root is the requester's file-memory root; with any other backend, private files exist but are not file memory, and none turns memory off.
• Nothing is enabled implicitly: set memory_backend, private.context_files, and private.knowledge explicitly for whatever the template provides; the file names are up to you.
• Because private.per sets the agent's worker scope, configuring both private and worker_scope fails with Private agents derive their execution scope from private.per; configure private or worker_scope, not both.
• Private agents cannot be configured as team members, and a shared team member cannot reach one through delegate_to. Tagging a private agent together with other agents in a message still forms an ad hoc team for that requester.
• A private agent runs only for a known requester; otherwise it fails with Private agent '<name>' requires an active execution identity to resolve requester-local state.

Private Fields

File-Based Context Loading

context_files inlines files into the agent's prompt under a Personality Context section, without a knowledge base.

• Paths are relative to the agent's workspace, agents/<name>/workspace/ in the storage directory; absolute paths and .. are rejected. With memory_backend: file, the same workspace holds the agent's file memory.
• Files load in list order, each headed by its resolved path so the agent knows where to edit it.
• Missing files are skipped with a warning in the logs.
• Edits take effect on the next reply without a restart.

defaults.max_preload_chars (default 50000) caps the section. When it is exceeded, MindRoom drops whole files from the start of the list first and then trims the last remaining file from its end. Each affected file keeps its path and a marker with the omitted character count, so the agent can open the file for the rest. A cap too small to hold the headings and markers fails with max_preload_chars=<n> cannot fit required context headings and omission markers.

Naming Rules

Agent and team keys may contain only letters, digits, and underscores (^[a-zA-Z0-9_]+$). The same key cannot appear under both agents: and teams:. router, user, and _shared are reserved.

Defaults

The defaults section sets values every agent inherits unless it sets its own, plus global-only settings that cannot be overridden per agent.

defaults:
  tools: [scheduler]
  learning_mode: agentic
  max_tool_calls_per_turn: 200
  worker_tools: [shell, file, python]
  enable_streaming: true
  max_preload_chars: 50000

These defaults apply to each agent that leaves the same field unset:

defaults.tools (default [scheduler]) is added to every agent with include_default_tools: true; set it to [] to add nothing. It accepts the same per-tool overrides as agents.<name>.tools.

These settings are global-only: