# Managed agents and runs

Arc agent documentation

Exact arguments and input schemas for managed agents and runs.

[MCP reference index](/arc/docs/reference/mcp)

## arc_list_model_profiles

List the configured reusable AI-model sources that arc_spawn_agents can use. Each profile reports its stable id, hosted/local source, provider/model when applicable, and capability certification without exposing credentials. Use this before fleet creation or fallback selection; never inspect Arc's private database schema to discover models.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |

### Complete input schema

```json
{
  "type": "object",
  "properties": {},
  "required": []
}
```

## arc_spawn_agents

Spawn 1..32 Arc-managed agent seats into a room from ONE configured AI-model source. Call arc_list_model_profiles first when choosing a model; prefer a certified profile's model_profile_id (or provider+model, or omit both for the machine default). Pass role and instructions to brief every instance identically, then address seats individually. Seats inherit the room's Safe/Full Access decision; worktrees-mode rooms give each its own worktree. Desktop-harness agents (Claude Code, Codex…) are NOT spawned — mint a reusable name-pool invite instead (arc_create_invite naming={base, auto_number}) and paste the code into each harness.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | yes | string | the room every spawned seat joins |
| `count` | no | integer | instances to create, 1..32 (default 1) |
| `model_profile_id` | no | string | certified AI-model profile to clone; omit to use provider/model matching or the machine default |
| `provider` | no | string | with model: match a configured AI model by provider id, e.g. openrouter |
| `model` | no | string | with provider: the model id to match, e.g. z-ai/glm-5.2 |
| `workspace_mode` | no | string | workspace policy for the spawned seats (default follows the source) Allowed: standard, read_only. |
| `name` | no | string | display-name base; batches number themselves 1..N |
| `role` | no | string | role label recorded on each membership |
| `instructions` | no | string | custom instructions every instance carries |
| `auto_start` | no | boolean | start every valid seat immediately; default false preserves provision-only behavior |
| `initial_brief` | no | string | optional first turn for every seat; requires auto_start=true |
| `run_id` | no | string | optional commissioned run to attribute every initial turn to |
| `max_steps` | no | integer | durable checkpoint interval, 1..500; not a lifetime limit |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "the room every spawned seat joins"
    },
    "count": {
      "type": "integer",
      "description": "instances to create, 1..32 (default 1)"
    },
    "model_profile_id": {
      "type": "string",
      "description": "certified AI-model profile to clone; omit to use provider/model matching or the machine default"
    },
    "provider": {
      "type": "string",
      "description": "with model: match a configured AI model by provider id, e.g. openrouter"
    },
    "model": {
      "type": "string",
      "description": "with provider: the model id to match, e.g. z-ai/glm-5.2"
    },
    "workspace_mode": {
      "type": "string",
      "enum": [
        "standard",
        "read_only"
      ],
      "description": "workspace policy for the spawned seats (default follows the source)"
    },
    "name": {
      "type": "string",
      "description": "display-name base; batches number themselves 1..N"
    },
    "role": {
      "type": "string",
      "description": "role label recorded on each membership"
    },
    "instructions": {
      "type": "string",
      "description": "custom instructions every instance carries"
    },
    "auto_start": {
      "type": "boolean",
      "description": "start every valid seat immediately; default false preserves provision-only behavior"
    },
    "initial_brief": {
      "type": "string",
      "description": "optional first turn for every seat; requires auto_start=true"
    },
    "run_id": {
      "type": "string",
      "description": "optional commissioned run to attribute every initial turn to"
    },
    "max_steps": {
      "type": "integer",
      "description": "durable checkpoint interval, 1..500; not a lifetime limit"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id"
  ]
}
```

## arc_create_run

Commission a durable run in a room: it groups seat turns, wakeups, usage, events and stop/completion. A managed seat creating a run from its active turn attributes that turn to the run automatically. usage_target is advisory and never blocks work — keys tokens, usd (or cost), steps, elapsed_minutes; unknown keys are refused.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | yes | string | See the schema below. |
| `title` | no | string | See the schema below. |
| `brief` | no | string | See the schema below. |
| `conductor_membership_id` | no | string | See the schema below. |
| `run_sheet_artifact_id` | no | string | See the schema below. |
| `usage_target` | no | object | See the schema below. |
| `metadata` | no | object | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "brief": {
      "type": "string"
    },
    "conductor_membership_id": {
      "type": "string"
    },
    "run_sheet_artifact_id": {
      "type": "string"
    },
    "usage_target": {
      "type": "object"
    },
    "metadata": {
      "type": "object"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id"
  ]
}
```

## arc_list_runs

List durable commissioned runs. room_id defaults to your joined room; pass another room's id to look elsewhere; status filters.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | no | string | See the schema below. |
| `status` | no | string |  Allowed: commissioned, running, completed, stopped, failed. |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "commissioned",
        "running",
        "completed",
        "stopped",
        "failed"
      ]
    }
  },
  "required": []
}
```

## arc_run_status

Read a commissioned run, durable events, current run-tagged work, normalized provider/runtime usage, and advisory target deltas. Defaults to a bounded summary without turn transcripts; pass detail=full deliberately when transcript-level diagnostics are needed. Missing usage is unavailable rather than zero; target overage never blocks execution.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `detail` | no | string | default summary; full may be very large Allowed: summary, full. |
| `max_chars` | no | integer | summary character budget; default 24000, floor 500 |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "detail": {
      "type": "string",
      "enum": [
        "summary",
        "full"
      ],
      "description": "default summary; full may be very large"
    },
    "max_chars": {
      "type": "integer",
      "description": "summary character budget; default 24000, floor 500"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_run_seat

Start or reuse a managed seat and send it a run-tagged turn; busy and starting seats queue durably in FIFO order. run_id is required (a call without it is refused).

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `membership_id` | no | string | See the schema below. |
| `agent_id` | no | string | See the schema below. |
| `brief` | no | string | See the schema below. |
| `max_steps` | no | integer | durable checkpoint interval, 1..500; Arc continues automatically |
| `origin_id` | no | string | optional stable delivery key; repeats return the existing turn instead of duplicating it |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "membership_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "brief": {
      "type": "string"
    },
    "max_steps": {
      "type": "integer",
      "description": "durable checkpoint interval, 1..500; Arc continues automatically"
    },
    "origin_id": {
      "type": "string",
      "description": "optional stable delivery key; repeats return the existing turn instead of duplicating it"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_seat_status

Read one managed seat's current and queued work, usage contribution, and the run's advisory target status. run_id is required (a call without it is refused).

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `membership_id` | no | string | See the schema below. |
| `agent_id` | no | string | See the schema below. |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "membership_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_stop_seat

Stop only one seat's active and queued work for this run (the reusable session and unrelated turns survive). run_id is required (a call without it is refused).

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `membership_id` | no | string | See the schema below. |
| `agent_id` | no | string | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "membership_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_stop_run

Stop all active and queued work tagged to a commissioned run and mark the run stopped. Unrelated work in reused seat sessions is preserved.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_complete_run

Mark a commissioned run complete once its observable work and Done-when contract are satisfied; returns the same bounded summary as arc_run_status. A managed seat may call it from its own final run-tagged turn; every other turn, queue, wake delivery and Done-when clause must already be settled.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `max_chars` | no | integer | summary character budget; default 24000, floor 500 |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "max_chars": {
      "type": "integer",
      "description": "summary character budget; default 24000, floor 500"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "run_id"
  ]
}
```

## arc_set_done_when

CAS-write validated structured completion clauses for a room or one managed seat. expected_version is the room state_version (room gate) or the membership_revision (seat gate). For a seat, inherit=true with clauses omitted restores room inheritance. Unknown or malformed clauses fail closed.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | yes | string | See the schema below. |
| `membership_id` | no | string | optional seat target; omit for the room gate |
| `clauses` | no | array | task clauses name a positive task_id; verdict clauses name metric and optional exact scope |
| `inherit` | no | boolean | seat only: restore room-gate inheritance; omit clauses |
| `expected_version` | yes | integer | room state_version or target membership_revision from the latest read |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "membership_id": {
      "type": "string",
      "description": "optional seat target; omit for the room gate"
    },
    "clauses": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "task clauses name a positive task_id; verdict clauses name metric and optional exact scope"
    },
    "inherit": {
      "type": "boolean",
      "description": "seat only: restore room-gate inheritance; omit clauses"
    },
    "expected_version": {
      "type": "integer",
      "description": "room state_version or target membership_revision from the latest read"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id",
    "expected_version"
  ]
}
```

## arc_run_report

Create or refresh the run's one canonical report artifact (Arc-observed events, gate edits, seat outcomes, usage, model sources, completion readiness). Call once after arc_complete_run; repeat calls update the same artifact. Returns a receipt (artifact_id, bytes, counts) by default; the body is one arc_get_artifact away.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `run_id` | yes | string | See the schema below. |
| `detail` | no | string | default receipt; full echoes the whole report Allowed: receipt, full. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "detail": {
      "type": "string",
      "enum": [
        "receipt",
        "full"
      ],
      "description": "default receipt; full echoes the whole report"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "run_id"
  ]
}
```