Managed agents, runs and completion

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.

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.

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 for independent slices and assign each to its returned agent ID. Then dispatch the seat:

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:

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. Retry and rewind change conversation replay; files, tasks, decisions and other side effects remain. Consult the run reference and complete MCP reference 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:

{"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.