Agent Teams

Agent Teams let you group coding agents (from Agent Hub), cloud models, and local providers into named roles, then run workflows that hand work between them.

Concepts

Piece	What it is	Stored at
Team	Named roles (`lead`, `analyst`, …) mapped to agents, models, or providers	`~/.config/arka/teams/`
Workflow	Steps for a team — sequential, parallel, or round-robin handoff	`~/.config/arka/workflows/`
Run	Execute a workflow with a task string; results pass between steps via `{task}`, `{results}`, `{step_N}`	CLI

Member kinds:

agent — ollama launch agent from Agent Hub (claude, codex, hermes, …)
model — specific model + provider (gpt-4o + openai, gemini-2.0-flash + gemini)
provider — provider default model (ollama, groq, …)

Quick start

Starter teams and workflows are seeded on first use:

arka team list
arka workflow list

arka team show research --resolve
arka team run research --task "Summarize Rust async patterns"

arka workflow run review-and-ship --task "Plan a v2 auth redesign"
arka workflow run code-review --task "Review PR #42: add JWT refresh"
arka workflow run brainstorm --task "Cache invalidation strategies for edge CDN"

From fish:

team list
team run research --task "Compare Postgres vs SQLite for edge caches"
workflow run code-review --task "Review auth middleware changes"
workflow run brainstorm --task "Ideas for offline-first mobile sync"

Example team

name: research
description: Deep research team
members:
  - kind: agent
    id: claude
    role: lead
  - kind: model
    id: gemini-2.0-flash
    provider: gemini
    role: analyst
  - kind: provider
    id: ollama
    role: local-fallback
defaults:
  memory: unified
  mcp: true
  workflow: review-and-ship

Example workflow

name: review-and-ship
team: research
steps:
  - member: lead
    action: plan
    prompt: "Break down: {task}"
  - parallel:
      - member: analyst
        action: analyze
        prompt: "Analyze: {task}\n\nPlan:\n{step_1}"
      - member: local-fallback
        action: verify
        prompt: "Sanity-check: {step_1}"
  - member: lead
    action: synthesize
    prompt: "Merge results: {results}"

Round-robin mode (v2)

Instead of explicit steps, members take turns until max_turns is reached. Outputs accumulate in {results}, {transcript}, and {last_result}.

name: brainstorm
team: research
mode: round_robin
max_turns: 6
prompt: |
  Continue brainstorming on: {task}
  Previous: {last_result}
members:
  - lead
  - analyst
  - local-fallback
defaults:
  retries: 2
  mcp: true

Run:

arka workflow run brainstorm --task "Edge cache invalidation patterns"

If members is omitted, all team roles rotate in definition order.

Retries (v2)

Retry failed agent/LLM steps before marking a run failed. Per step:

- member: analyst
  action: analyze
  prompt: "Analyze: {task}"
  retries: 3
  retry_delay: 2

Workflow or team defaults:

defaults:
  retries: 2
  retry_delay: 1

Priority: step → workflow defaults → team defaults. Retry count appears in CLI output (retries=N, attempts=N). Set TEAM_RETRY_BACKOFF=1 for exponential delay.

Per-step MCP (v2)

Enable MCP context per step (or inherit from workflow/team defaults):

- member: analyst
  action: fetch
  prompt: "Summarize open PRs for: {task}"
  mcp: true
  mcp_servers: [github]

Setting	Effect
`mcp: true`	Inject all configured MCP servers from `~/.config/arka/mcp.json`
`mcp_servers: [github]`	Limit to named servers
`defaults.mcp: true`	Enable for all steps unless overridden

For agent steps, MCP tool summaries are prepended to the prompt. For model/provider steps, they are added to the system prompt. Optional tool loop for model steps: set TEAM_MCP_TOOL_ROUNDS=1 and have the model emit JSON like {"mcp_tool": "github", "tool": "search", "arguments": {}}.

CLI reference

arka team list
arka team show <name> [--resolve]
arka team create <name> [--template research]
arka team run <name> --task "..." [--workflow <name>]

arka workflow list
arka workflow show <name>
arka workflow create <name> [--template review-and-ship] [--team research]
arka workflow run <name> --task "..."

--resolve prints how each role maps to a concrete agent or LLM target.

Runtime behavior

Load team + workflow YAML/JSON from config dir (or bundled templates).
Resolve members — agents via Agent Hub catalog; models/providers via LLM registry.
Recall unified memory when defaults.memory: unified.
Execute steps:
- Agent roles → answer_question with role context (lightweight; not full ollama launch).
- Model/provider roles → LlmOrchestrator with a fixed provider/model chain.
- Parallel blocks → thread pool (TEAM_MAX_PARALLEL, default 4).
- Round-robin → rotate members for max_turns with shared transcript variables.
Retry failed steps per retries / retry_delay (workflow or team defaults).
Inject MCP tool summaries when mcp is enabled for a step.
Pass outputs forward via template variables.

Bundled templates

Template	Type	Roles
`research`	team	lead (claude), analyst (gemini), local-fallback (ollama)
`code-review`	team	lead (codex), analyst (groq), local-fallback (ollama)
`clawbox-edge`	team	openclaw lead + ollama fallback; scoped memory for Jetson
`review-and-ship`	workflow	plan → parallel analyze/verify → synthesize
`code-review`	workflow	review checklist → parallel review → summary
`brainstorm`	workflow	round-robin ideation across team roles

Create from templates:

arka team create my-research --template research
arka workflow create my-ship --template review-and-ship --team my-research

Environment

ARKA_TEAMS_DIR=~/.config/arka/teams
ARKA_WORKFLOWS_DIR=~/.config/arka/workflows
TEAM_MAX_PARALLEL=4
TEAM_RETRY_BACKOFF=0
TEAM_MCP_TOOL_ROUNDS=0

Scoped memory (v3)

Teams can opt into policy-filtered recall and scratchpad writes with provenance:

defaults:
  memory: scoped          # unified | scoped | off
  memory_scope:
    read: [global, team, workflow]
    write: workflow
    ttl_hours: 72
    promote: manual
  trust_tier: team

Mode	Recall	Step output
`unified` (default)	Global unified memory	Not persisted
`scoped`	Filtered by trust tier + team/workflow	Scratchpad with provenance
`off`	None	Not persisted

Per-step override: memory_scope: { write: run } on a workflow step.

arka workflow run review-and-ship --task "..." --promote-final
arka memory scratchpad list --team research
arka memory promote abc123def456

Workflow runs print run_id and scratchpad_writes in CLI output. Teams and workflows are included in arka config backup.

Limitations

Agent steps use Arka chat routing, not full interactive ollama launch sessions.
Model-step MCP tool loops are opt-in (TEAM_MCP_TOOL_ROUNDS) and single-round by default.
Round-robin has no early-stop condition — runs until max_turns.
Workflow conditions and human-in-the-loop gates are not implemented.
Provider health checks run at LLM call time, not at team resolve time.

Agent Hub — shared MCP, memory, and agent catalog
LLM fallback — provider/model routing used by model/provider roles
Memory — unified memory injected into team runs

Routing & CLI

Agent & memory

Developer tools

Models & inference

Media & documents

Integrations

Finance & data

Workflows & productivity

More

Agent Teams

Concepts

Quick start

Example team

Example workflow

Round-robin mode (v2)

Retries (v2)

Per-step MCP (v2)

CLI reference

Runtime behavior

Bundled templates

Environment

Scoped memory (v3)

Limitations

​Concepts

​Quick start

​Example team

​Example workflow

​Round-robin mode (v2)

​Retries (v2)

​Per-step MCP (v2)

​CLI reference

​Runtime behavior

​Bundled templates

​Environment

​Scoped memory (v3)

​Limitations

​Related

Concepts

Quick start

Example team

Example workflow

Round-robin mode (v2)

Retries (v2)

Per-step MCP (v2)

CLI reference

Runtime behavior

Bundled templates

Environment

Scoped memory (v3)

Limitations

Related