Agents

Ziro can run as one of several named agents, each with its own persona, tool policy, MCP servers, and guardrails. Plug-and-play is per agent: every agent carries its own on/off flag, so agents are enabled and disabled independently. There is no global single-vs-multi toggle.

An agent is a folder

Each agent lives in packages/ziro-core/src/ziro/agents/<agent_id>/ and is self-contained. It is configured by a single settings.yaml with one optional section per concern:

# packages/ziro-core/src/ziro/agents/researcher/settings.yaml (sections all optional)
meta:          # name, description, enabled, model, provider
persona:       # the persona / soul prompt (was agent_config.yaml)
tools:         # core_tools, max_active (was tool_policy.yaml)
permissions:   # the tool permission gate
guardrails:    # input/output guards
compaction:    # context compaction
mcp:           # selector over the shared MCP catalog (was mcp_servers.yaml)
shell:         # run_shell (off by default)
fs:            # read/write file tools
webfetch:      # web_fetch
websearch:     # web_search
memory:        # fact extraction + project memory
subagents:     # which children may be spawned
hooks:         # lifecycle hooks
plugins:       # the plugin policy gate (opt-in, was plugin_config.yaml)

Each section key is the old split file name minus its _policy / _servers / _config suffix. Legacy split files (shell_policy.yaml, …) still resolve at each layer as an alternative to the matching section, so existing agents keep working; run ziro migrate-config to fold them into one file. There are no agent config files in the project root. If an agent omits a section, the loader degrades to the built-in defaults for that feature.

For the field-by-field schema of each section, see Agent files, and Configuration for how layers deep-merge.

The meta section

meta:
  name: Researcher
  description: A factual research aide with lighter guardrails
  enabled: true
  model: null        # null → the provider's default model
  provider: null     # null → the global default provider (openrouter)

The shipped agents

chat flavour
engineering flavour
research flavour

Agent	Role
`default`	The autonomous Generalist. `web_search` and `fs_write` are core tools. The one shipped agent with plugins enabled.

Agent	Role
`product_manager`	Read-only role: `permissions.yaml` denies `fs_write:` and `shell:`. The flavour default.
`architect`	Read-only role, same denials.
`coder`	Full autonomous build surface: shell plus writes, no per-call approval. Web tools are disabled for it.

Agent	Role
`researcher`	Factual research aide, lighter guardrails, shell and web on, host mode. The flavour default.
`analyst`	Quantitative, autonomous host shell. Web tools disabled.
`writer`	Synthesis. Shell denied, writes allowed.

coder, analyst, and researcher run shell and write tools with default_action: allow and no per-call approval, so they work in headless and subagent flows. Autonomy is bought back with deterministic containment rather than a human gate: they do not hold the web tools, fs_write refuses the control plane (.env, settings.yaml, the legacy *_policy.yaml files, .git, .github, .ziro), and their shell sections add a per-agent deny regex list. See Permissions.

Per-agent model and provider

The meta section’s model field sets the model id for that agent. It flows through AgentProfile.model into the LLM factory at startup. Omit it, or set model: null, to use the provider’s env default.

python -m app.cli.manage_agents set-model researcher anthropic/claude-sonnet-4
python -m app.cli.manage_agents set-model researcher none   # clear the pin

The meta section’s provider field selects the LLM provider for that agent: openrouter, anthropic, openai, or any custom label you have registered. Default is None, which falls back to the global default provider (ZIRO_LLM_PROVIDER, itself defaulting to openrouter).

Provider and model resolve as one coupled pair, never as independent axes. An explicit model choice wins and carries its provider; otherwise the provider decides and the model follows the agent’s pin only when compatible, else the provider default. See Providers.

You can also pin a model tier token instead of a concrete id:

model: ${EXECUTION_MODEL}

planning, execution, and fast_execution each resolve from <PROVIDER>_<TIER>_MODEL (for example OPENROUTER_EXECUTION_MODEL), collapsing to <PROVIDER>_MODEL when unset. The token resolves against whichever provider is active at build time.

The enabled flag

The meta section’s enabled flag controls whether an agent is selectable. A disabled agent is hidden from the picker and rejected if requested with --agent.

python -m app.cli.manage_agents list
python -m app.cli.manage_agents enable researcher
python -m app.cli.manage_agents disable analyst

packages/ziro-core/src/ziro/agents/registry.yaml holds only default, the agent used when none is named. If the default agent is disabled, the first enabled agent is used instead.

python -m app.cli.manage_agents set-default researcher

Config resolution order

Every section resolves most-specific-first across three layers, and the layers deep-merge (a partial override inherits unset keys from lower layers):

Project layer

<project>/.ziro/agents/<id>/settings.yaml (or the matching split file)

Home layer

~/.ziro/agents/<id>/settings.yaml

Bundled package

The settings.yaml shipped inside Ziro itself.

Resolution is per section, not per folder: an agent can override just the permissions section in the project layer and inherit everything else from the bundle. This is how an installed Ziro is configured under ~/.ziro/agents/<id>/ without editing the package.

An untrusted project layer is skipped wholesale for dangerous sections (the permissions, mcp, hooks, and plugins sections, and any matching split file such as plugin_config.yaml). Folder trust is content-hashed, so editing such config revokes trust until you re-confirm it.

Memory isolation

Long-term memory is keyed ("memory", user_id, agent_id), so each agent keeps its own facts per user. The agent_id flows through the runnable config to both the memory loader and the save_memory tool. When a flavour is active, the key becomes ("memory", user_id, flavour) instead. Every agent in a flavour shares one memory store, so switching agents inside a flavour never loses or cross-contaminates memory. A config with no flavour (subagents, legacy callers) falls back to agent_id.

Selecting an agent

ziro                                              # interactive picker
python -m app.main --user alice --agent coder     # explicit
python -m app.cli.chat_once --user alice --agent researcher --message "..."

In-chat, /agent lists the agents available in the active flavour and switches in place, keeping the same thread and history.

Managing agents

python -m app.cli.manage_agents add my_agent --name "My Agent"
python -m app.cli.manage_agents add my_agent --name "My Agent" --template researcher
python -m app.cli.manage_agents remove my_agent

add seeds the config files from the default agent, or from --template <id>. Pass --no-copy for a meta-only scaffold.

A newly scaffolded agent ships no plugins section, and an agent with no plugins section in any config layer surfaces zero plugins. Plugins are per-agent opt-in: a new agent never silently inherits whatever the machine has installed.

Next steps

Manage agents CLI

Every subcommand, with flags.

Agent files

The schema of each settings.yaml section.

Flavours

Grouping agents into a shared workspace.

Getting started

Concepts

Interfaces

Guides

An agent is a folder

The meta section

The shipped agents

Per-agent model and provider

The enabled flag

Config resolution order

Memory isolation

Selecting an agent

Managing agents

Next steps

Manage agents CLI

Agent files

Flavours

​An agent is a folder

​The meta section

​The shipped agents

​Per-agent model and provider

​The enabled flag

​Config resolution order

​Memory isolation

​Selecting an agent

​Managing agents

​Next steps

Manage agents CLI

Agent files

Flavours

An agent is a folder

The meta section

The shipped agents

Per-agent model and provider

The enabled flag

Config resolution order

Memory isolation

Selecting an agent

Managing agents

Next steps