> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 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](/guides/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:

```bash theme={null}
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:

```fish theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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}`.

```yaml theme={null}
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:

```bash theme={null}
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:**

```yaml theme={null}
- member: analyst
  action: analyze
  prompt: "Analyze: {task}"
  retries: 3
  retry_delay: 2
```

**Workflow or team defaults:**

```yaml theme={null}
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):

```yaml theme={null}
- 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

```bash theme={null}
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:

```bash theme={null}
arka team create my-research --template research
arka workflow create my-ship --template review-and-ship --team my-research
```

## Environment

```bash theme={null}
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:

```yaml theme={null}
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.

```bash theme={null}
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](/guides/agent-hub) — shared MCP, memory, and agent catalog
* [LLM fallback](/concepts/llm) — provider/model routing used by model/provider roles
* [Memory](/guides/memory) — unified memory injected into team runs


## Related topics

- [Sakana Fugu orchestrator](/guides/fugu.md)
- [Arka — AI terminal agent documentation](/index.md)
- [Long-term memory with Supermemory sync](/guides/memory.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Agent Hub](/guides/agent-hub.md)