Agents

An agent is a named configuration that ties together a system prompt, the tools it may use, and its approval policy. Agents are provider-agnostic — they never hard-code a model; it is chosen through the provider resolution system (models.yaml).

Where agents live

Agents are discovered across three namespaces:

• ~/.muaz/plugins/local/agents/ — your own workspace (where agents create writes). Wins name resolution.
• ~/.muaz/plugins/<id>/agents/ — installed plugins (e.g. the seeded coding plugin).
• ~/.muaz/builtins/<id>/agents/ — embedded, read-only built-ins (e.g. default).

The agent used when you don’t pass --agent is set by default_agent in config.yaml. Reference any agent by a bare name (resolved local → plugins → built-ins) or a fully-qualified @plugin/name.

A full agent config

name: coding
description: "An expert coding assistant"

# No provider here — agents are provider-agnostic. The model is chosen in
# ~/.muaz/models.yaml (a global default plus optional per-agent overrides).
# See /muaz/docs/concepts/providers/ for the binding model.

# system_prompt: inline text, OR a path (~/…, /…, ./…, ../…). Co-locate prompts
# with the agent and use relative paths so the agent stays portable.
system_prompt: "./coding.md"

# Optional: a markdown SOP file appended after system_prompt
sop_file: "./coding-sop.md"

streaming: true   # stream tokens as they arrive (default: true)

# Agentic loop limits (null = use built-in default)
max_iterations: 20         # tool-call rounds before giving up
max_concurrent_tools: 4    # parallel tool executions per round

# LLM inference parameters (null = use model default)
max_tokens: ~
temperature: ~
top_p: ~

# Compact conversation history when accumulated input tokens exceed this
# threshold. null disables compaction.
compaction_token_threshold: 80000
compaction_summary_prompt: ~   # custom summary instructions (null = built-in)

# Built-in tool safety limits
workspace_root: ~          # dir the file tools may touch + shell's cwd (default: cwd)
shell_timeout_secs: 120    # kill a shell command after this many seconds

# Hard local-egress lock: `none` strips the web tools and refuses HTTP MCP
# servers for this agent (default: full).
network: full

# Per-agent web guardrails; field-merges over the global config.yaml web_tools block
web_tools:
  allow_private_hosts: false   # reach localhost/private addresses (off blocks SSRF)
  default_format: markdown     # fetch_webpage default output: markdown | text

# Skills available to this agent (omit to expose none; opt in explicitly)
skills:
  allow:
    - verify-and-debug

# Tool access: one level per tool (off | ask | auto). Overrides the global
# config.yaml `tools:` defaults; the most specific setting wins.
tools:
  default: ask               # fallback for tools with no specific setting
  built_in:
    read_file: auto
    search: auto
    edit_file: ask
    shell:                   # stay at ask, but auto-approve read-only git
      level: ask
      allow_when:
        - "program=git"
  # MCP servers are opt-in: an agent attaches one by listing it here.
  servers:
    filesystem:
      default: ask

Key fields

• system_prompt — inline text or a path (~/, /, ./, ../). Resolved relative to the agent’s own directory, so ./coding.md works in any namespace.
• sop_file — optional SOP markdown appended after the system prompt.
• tools — the single tool-access axis: default, per-built_in levels (off/ask/auto, optionally with allow_when), and the MCP servers this agent attaches. Setting a tool off removes it from the toolset; there is no separate include/exclude or approve/deny list.
• workspace_root / shell_timeout_secs — confine the file tools (and shell’s working directory) and cap shell runtime.
• network — none is a hard local-egress lock: it strips the web tools and drops HTTP MCP servers for this agent (full by default).
• web_tools — per-agent override of the global web tool guardrails (fetch_webpage, web_search); fields merge over the global block.
• skills — controls which skills the agent sees; allow opts into a named subset, deny hides specific skills, paths adds discovery directories.
• compaction_token_threshold — summarise history once accumulated input tokens exceed this, to stay within context limits.

Managing agents from the CLI

muaz agents list           # list agents across all namespaces (tagged by namespace)
muaz agents create         # create a new agent interactively (writes to local)
muaz agents show coding    # print the resolved config (any namespace)
muaz agents edit coding    # edit a local agent; forks a built-in/plugin into local first

Editing a built-in or plugin agent forks it into your local workspace (copying the agent and its prompt/SOP), where your copy then wins resolution — the original stays intact and upgradeable.

From inside the REPL, /agents lists agents (with namespaces) and /switch <name> loads a different one in a fresh session; on an ambiguous name it lists the candidates so you can /switch @plugin/name.