Agent Teams

Form teams across agents, models, and providers — then run sequential or parallel workflows with shared memory.

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

1. Load team + workflow YAML/JSON from config dir (or bundled templates).
2. Resolve members — agents via Agent Hub catalog; models/providers via LLM registry.
3. Recall unified memory when defaults.memory: unified.
4. 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.
5. Retry failed steps per retries / retry_delay (workflow or team defaults).
6. Inject MCP tool summaries when mcp is enabled for a step.
7. 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.

Related

• 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