Agents, teams & swarms

Revka is multi-agent from the ground up. Your primary agent can hand work to specialized sub-agents, run several of them as a coordinated swarm, or spawn whole teams of agents that report to one another over a dependency graph. This page explains the agent identity model and the three orchestration layers, so you can pick the right one for a task.

There are two distinct surfaces, and it helps to keep them straight:

• Config-level orchestration — [agents.<name>] sub-agents and [swarms.<name>] swarms, driven by the built-in delegate and swarm tools. Lightweight, defined in config.toml, available to any agent.
• Operator-level orchestration — the Agent Template Pool and Agent Teams, managed by the Operator MCP and stored in Kumiho graph memory. Persistent, graph-backed, with trust scoring and wave execution.

Use config-level orchestration for fast, declarative fan-out inside a single chat. Use teams when you need durable, reusable agent rosters with explicit topology. For the patterns that string agents together (review-fix loops, handoffs, group chat, supervisor delegation, map-reduce), see Spawning & coordinating agents.

The agent identity model

Every Revka agent has an identity made of a few first-class fields. The primary agent draws its identity from SOUL.md and the [identity] config section; sub-agents and pooled agents carry the same shape so behavior is consistent wherever an agent runs.

Field	Meaning
identity	Who the agent is — its name, role, and remit.
soul	Persona, values, and voice that shape how it responds.
expertise	The domains it is good at (e.g. ["Rust", "async"]).
tone	Communication style (e.g. direct, friendly).
role	Functional slot: coder, reviewer, researcher, tester, architect, or planner.
model	Preferred provider/model for instantiating the agent.
system_hint	Optional extra system-prompt guidance.

The [identity] config section controls the format of the identity document injected into the primary agent’s system prompt:

[identity]
format = "aieos"             # "openclaw" or "aieos"
aieos_path = "identity.json" # workspace-relative
# or: aieos_inline = '{"name": "Revka", ...}'

Pooled and dashboard-managed agents store the same identity/soul/expertise/tone fields in Kumiho. See the Agent Template Pool and Agent Teams sections below for how those fields are persisted and reused.

Delegate sub-agents — [agents.<name>]

A delegate sub-agent is a named agent defined in config.toml that your primary agent can hand a subtask to with the delegate tool. Each sub-agent has its own provider, model, system prompt, and — in agentic mode — its own tool allowlist.

[agents.researcher]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-6"
system_prompt = "You are a research assistant."
max_depth = 2
agentic = true
allowed_tools = ["web_search", "http_request", "file_read"]
max_iterations = 8
agentic_timeout_secs = 600

[agents.coder]
provider = "ollama"
model = "qwen2.5-coder:32b"
temperature = 0.2
timeout_secs = 60

[agents.code_reviewer]
provider = "anthropic"
model = "claude-opus-4-5"
system_prompt = "You are an expert code reviewer focused on security and performance."
agentic = true
allowed_tools = ["file_read", "shell"]
skills_directory = "skills/code-review"

Sub-agent config keys

Key	Type	Default	Meaning
provider	string	required	Provider name (anthropic, openrouter, ollama, …).
model	string	required	Model for the sub-agent.
system_prompt	string	unset	System-prompt override.
api_key	string	unset	API key override (encrypted when secrets.encrypt = true).
temperature	float	unset	Temperature override.
max_depth	int	3	Max recursion depth for nested delegation.
agentic	bool	false	Enable the multi-turn tool-call loop.
allowed_tools	array	[]	Tool allowlist for agentic mode.
max_iterations	int	10	Max tool-call iterations in agentic mode.
timeout_secs	int	120	Timeout for non-agentic calls (1–3600).
agentic_timeout_secs	int	300	Timeout for agentic loops (1–3600).
skills_directory	string	unset	Workspace-relative skills dir for scoped skill loading.

Caution

agentic = true requires at least one entry in allowed_tools. The delegate tool is excluded from every sub-agent allowlist to prevent re-entrant delegation loops.

Global delegate defaults live in their own section and apply to any sub-agent that does not set its own timeouts:

[delegate]
timeout_secs = 120          # non-agentic calls
agentic_timeout_secs = 300  # agentic loops

In agentic mode a sub-agent receives an enriched system prompt — its allowed tools and their parameters, a skills section (from skills_directory or the default workspace skills/ dir), the workspace path, the current date/time, safety constraints, and the shell policy when shell is in its tool list.

Using the delegate tool

The delegate tool runs one sub-agent. By default it sends a single prompt → response; in the background it returns a task_id you check later, and with parallel it fans out to several named agents at once.

{ "agent": "researcher",
  "prompt": "Summarize the top 5 recent papers on diffusion models",
  "background": false }

Field	Meaning
action	delegate (default), check_result, list_results, cancel_task.
agent	Sub-agent name from [agents.<name>].
prompt	The subtask prompt.
context	Optional context prepended to the prompt.
background	Return immediately with a task_id.
parallel	Array of agent names to run concurrently.
task_id	Used with check_result / cancel_task.

The background workflow is: delegate with background: true → receive task_id → later delegate with action: "check_result". Sub-agent providers are validated by revka doctor, so a typo in a provider name surfaces before runtime.

Swarms — [swarms.<name>]

A swarm runs a group of named sub-agents together under one strategy. Where delegate drives a single agent, the swarm tool coordinates several at once.

[swarms.analysis]
agents = ["researcher", "coder"]
strategy = "sequential"
description = "Research a topic, then implement the findings."
timeout_secs = 300

Key	Type	Default	Meaning
agents	array	required	Agent names; must reference keys in [agents].
strategy	string	required	sequential, parallel, or router.
router_prompt	string	unset	Prompt the router uses to pick the best agent.
description	string	unset	Shown to the LLM when choosing a swarm.
timeout_secs	int	300	Max total swarm execution time.

The three strategies:

• sequential — a pipeline. Each agent’s output feeds the next, in the order listed in agents.
• parallel — fan-out / fan-in. Every agent runs on the same prompt and all outputs are collected.
• router — the LLM reads router_prompt and picks the single best agent for the task.

Invoke a swarm with the swarm tool:

{ "swarm": "analysis",
  "prompt": "Analyze the competitive landscape for AI code assistants" }

Field	Meaning
swarm	Swarm name from [swarms.<name>].
prompt	The task prompt.
context	Optional additional context.

Note

delegate is one agent; swarm is many. Reach for a swarm when a task naturally splits into a pipeline, a fan-out, or a routing decision across the sub-agents you have already defined.

Agent Template Pool

Beyond config-level sub-agents, the Operator MCP maintains a persistent Agent Template Pool in Kumiho (under the harness project’s AgentPool space). A template is a reusable agent definition — its type, role, capabilities, identity, soul, tone, preferred model, and default working directory — that the operator instantiates on demand.

Templates carry the full identity model:

• role: coder, reviewer, researcher, tester, architect, planner
• agent_type: claude, codex, agy, agent, opencode

The operator exposes pool management as MCP tools:

Tool	Purpose
save_agent_template	Create or update a template (name, type, role, capabilities, identity, soul, tone, model, …).
search_agent_pool	Keyword search the pool, e.g. {"query": "rust testing agent"}.
list_agent_templates	List templates, sorted by usage count.
get_agent_trust	Success rate and recent outcomes per template.

Templates are referenced by name when spawning agents. The operator’s create_agent tool can inherit a template and override fields per call:

{ "title": "rust-coder",
  "cwd": "/home/user/myproject",
  "agent_type": "codex",
  "template": "rust-coder",
  "initial_prompt": "Implement the auth module" }

Usage counts are tracked automatically, and get_agent_trust feeds trust-aware patterns — for example, the refinement loop auto-switches its critic when a template’s trust drops below 0.7. You can also manage pooled agents from the dashboard’s Agents, teams & canvas page or the Agents API.

Agent Teams

An Agent Team is a bundle of agent templates wired together with directed relationship edges, stored in Kumiho under Revka/Teams. The edges define a topology (a DAG) that the operator executes in waves: every agent with no unresolved dependencies runs in parallel, then the next wave, and so on.

Edge types describe how members relate:

• REPORTS_TO
• SUPPORTS
• DEPENDS_ON

Teams are managed with operator MCP tools:

Tool	Purpose
create_team	Create/update a team bundle from member krefs and edges.
get_team	Full team detail — members and edges.
list_teams / search_teams	Discover existing teams.
spawn_team	Execute the team in dependency waves.
get_spawn_progress	Per-wave progress, completions, and halt reasons.
lint_team	Check role balance, naming, capability coverage, and edge completeness.

spawn_team accepts execution controls:

Param	Default	Meaning
task	required	The work given to the team.
cwd	required	Working directory for spawned agents.
halt_on_failure	true	Stop downstream waves when an upstream agent fails.
resume_from	unset	Checkpoint ID to resume a halted spawn without re-running completed waves.
dry_run	false	Validate and preview waves without spawning agents.

When a spawn halts mid-run, the response includes a checkpoint ID you pass to resume_from to continue. Team execution is static — the DAG is fixed up front — which contrasts with dynamic supervisor delegation, where a supervisor picks the next specialist based on results so far.

Teams are also first-class in the gateway and dashboard. They are Kumiho bundles of agent members linked by REPORTS_TO / SUPPORTS / DEPENDS_ON edges, can designate a supervisor member, and can be referenced from a workflow’s team: field. Manage them over the Agents, skills & teams API:

GET    /api/teams?include_deprecated=false
POST   /api/teams
GET    /api/teams/{*kref}
PUT    /api/teams/{*kref}
DELETE /api/teams/{*kref}
POST   /api/teams/avatar

All /api/teams/* routes require Authorization: Bearer <token> from the pairing flow.

Which layer should I use?

Delegate a subtask

One specialized agent, defined in [agents.<name>], invoked with the delegate tool. Best for quick, scoped hand-offs inside a chat.

Run a swarm

Several config sub-agents under one sequential, parallel, or router strategy via the swarm tool. Best for pipelines and fan-out.

Spawn a team

A persistent, graph-backed roster with explicit dependency edges, executed in waves with checkpoint resume. Best for durable, reusable topologies.

Coordinate dynamically

Review-fix loops, refinement, handoff, group chat, supervisor delegation, and map-reduce — see Spawning & coordinating agents.

Related pages

Spawning & coordinating agents Operator orchestration patterns: review-fix, refinement, handoff, group chat, supervisor, map-reduce.

Code agents, delegation & pipelines The delegate, swarm, and CLI code-agent tools in detail.

Config: provider, agent & routing Full reference for [agents], [swarms], [delegate], and routing config.

Operator MCP The orchestration sidecar that powers the Agent Template Pool and Teams.

The agent loop How a single agent reasons, calls tools, and responds.

Autonomy levels & approvals The policy and approval gates that bound what any agent can do.