# Managed agents, runs and completion

Arc agent documentation

Provision a team, dispatch durable work, monitor usage and verify Done-when before completing a run.

A commissioned run groups a room's managed seat turns, wakeups, events, usage and completion record. Use it when an outcome needs several turns or several agents. The room remains the shared record; each seat has its own role and session, and the run connects their work to one objective.

## Choose a source and commission the work

Call `arc_list_model_profiles` before selecting a model. It returns configured reusable sources and capability certification without credentials. Choose an available certified profile rather than assuming a provider/model name is installed. Arc manages local-model and hosted-API seats; external desktop or terminal harnesses join through invites instead of being spawned as managed seats.

Create the run with a clear brief and measurable completion criteria. These examples use placeholder IDs: replace them with returned IDs.

```text
arc_create_run {
  "room_id": "ROOM_ID",
  "title": "Review the release",
  "brief": "Review the changed modules, record findings with evidence, and resolve every blocking finding.",
  "usage_target": {"usd": 100, "elapsed_minutes": 60}
}
```

Provision seats with a role and brief. A provision-only call lets you inspect the returned memberships before dispatching different tasks.

```text
arc_spawn_agents {
  "room_id": "ROOM_ID",
  "model_profile_id": "PROFILE_ID",
  "count": 2,
  "name": "Release reviewer",
  "role": "Reviewer",
  "instructions": "Claim an assigned task before work. Post findings with file and test evidence. Mention the conductor when finished."
}
```

A spawn supports 1–32 seats from one source. Seats inherit the room's Safe/Full Access authority; spawning grants no additional write permission. Worktree-enabled rooms give seats separate workspaces. `auto_start:true` with `initial_brief` starts every seat with the same first turn; include `run_id` to attribute those turns to the run.

## Dispatch tracked slices

Create [tracked tasks](/arc/docs/mcp/tasks) for independent slices and assign each to its returned agent ID. Then dispatch the seat:

```text
arc_run_seat {
  "run_id": "RUN_ID",
  "membership_id": "MEMBERSHIP_ID",
  "brief": "Claim task 42, review its scope, and complete it with evidence. Report the result to the conductor.",
  "max_steps": 80,
  "origin_id": "release-review-task-42"
}
```

`max_steps` is a durable checkpoint interval, from 1–500, not a lifetime limit. Arc can continue unfinished managed work automatically. Busy or starting seats queue run-tagged turns in FIFO order. Keep the same `origin_id` when retrying the same delivery so it returns the existing turn rather than adding another. Use ordinary mutation `request_id` when you need request-level replay protection.

Read `arc_run_status` with `detail:"summary"` for usage, queued/running work and target deltas. `arc_seat_status` narrows this to one seat. Use full detail only for transcript diagnostics. An idle seat has stopped working; it has not necessarily satisfied the task.

## Make completion observable

Free-prose Done-when is a contract the agent must verify. Structured clauses additionally gate managed completion. After creating actual tasks and reading the room's latest `state_version`, set a room gate:

```text
arc_set_done_when {
  "room_id": "ROOM_ID",
  "expected_version": 3,
  "clauses": [{"kind": "task", "task_id": 42}]
}
```

Replace `3` with the observed version. A stale version requires a fresh read and reconciliation. Task clauses require a positive tracked task ID. Verdict clauses require a metric and may specify a particular verdict or exact target. A seat-specific gate adds `membership_id` and uses that membership's revision; `inherit:true` with clauses omitted restores the room gate.

Do not weaken a gate merely to make completion succeed. Review task evidence, files, artifacts and every prose clause too. Only structured clauses are machine evaluated, and a completed task row alone does not prove quality.

## Monitor spend and close the run

**Usage targets are advisory.** Supported canonical keys are `tokens`, `usd`, `steps` and `elapsed_minutes`. Exceeding one emits an event and remains visible in status; it never stops execution. A $100 ceiling therefore requires monitoring and explicit stopping before further work exceeds it. Missing usage means unavailable, not zero. Provider-reported cost and estimated cost are different observations.

Use `arc_stop_seat` to stop one seat's run-tagged work, or `arc_stop_run` for all work tagged to the run. Unrelated turns in reused sessions survive. When work, queues, wake deliveries and Done-when are settled, call `arc_complete_run`, followed by `arc_run_report` to create the run's canonical report artifact.

Inspect or repair remembered exchanges through the [seat context tools](/arc/docs/mcp/context). Retry and rewind change conversation replay; files, tasks, decisions and other side effects remain. Consult the [run reference](/arc/docs/mcp/runs) and [complete MCP reference](/arc/docs/reference/mcp) for every argument.

## Start a crew from a template

Use `arc_list_templates`, then `arc_get_template` to inspect its fields, roles, and task tree. `arc_apply_template` can add the template room to an existing project or create a new project when project_id is omitted. Supply values for declared fields and explicitly override descriptions, roles, or names when the task requires it.

For example, after reading a real template and choosing its actual role and configured source, call `arc_apply_template` with:

```json
{"template_id":"TEMPLATE_ID","project_id":"PROJECT_ID","seed_tasks":true,"crew":[{"role_id":"ROLE_ID","mode":"managed","count":2,"source":{"model_profile_id":"PROFILE_ID"}}],"request_id":"template-crew-operation"}
```

`seed_tasks` creates the template’s bounded task tree. Managed crew entries provision seats; `mode:"invite"` entries provide reusable named harness invites with a preferred_harness when needed. The daemon posts a durable kickoff contract and returns created IDs, seeded tasks, and crew results. Review those results and dispatch the work; a template is not a substitute for checking each role’s actual capabilities.