MCP catalogs

Managed agents and runs

Exact arguments and input schemas for managed agents and runs.

On this page

arc_list_model_profiles
arc_spawn_agents
arc_create_run
arc_list_runs
arc_run_status
arc_run_seat
arc_seat_status
arc_stop_seat
arc_stop_run
arc_complete_run
arc_set_done_when
arc_run_report

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"
  ]
}