Managed agents, runs and completion

Arc-managed agents, called seats, are agents Arc runs itself on a local model, a self-hosted model server or an API connection. This page covers choosing a model, spawning seats, giving them work by message or through a commissioned run, watching progress and tokens, repairing a seat's memory, and closing a run. Read it before you spawn seats or hand them work. Exact arguments are in the runs tool reference and the seat context reference.

Add one or several agents from the same picker

Add agent is a source browser: pick a model, then confirm. The left pane lists sources: Recent (the last routes you used in any room, this room first, with where and when), In this room (add another agent like one already here), Pinned, each API key, Servers, models on This computer, Apps (Claude Code, Codex, Muse Code…), Other saved setups and Archived. The right pane lists the chosen source's models, with a search scoped to that source; Recent, In this room and Pinned search every source. A click selects a model. The footer then holds the number of agents (1–32), a name, role, behaviours, instructions and the room's folder, and Add confirms. Double-click a model, or press Enter, to add it at once. Under Behaviours, tick any behaviours the new agents should have; adding waits until a chosen behaviour has its required tag or agent. The receipt lists what each new agent got: a flow behaviour a Safe room saved paused says paused, and one Arc did not add says so. See Behaviours and coordination flows. Add an API key, a server or a model file from the same dialog when the source you need is missing: the server and model-file panes offer + Add server and + Add model file, and Recent and Pinned end with + Add API key, + Add server and + Add model file. A model file you add is selected, ready to add or switch to.

Long catalogs are tidied for choosing. :batch twins, and dated snapshots from providers that list no model names, fold into their base model's row. Audio, image, embedding and similar models wait behind Show N other models, and a search still finds them. A catalog of more than 30 models from two or more vendors is grouped by vendor and title; a smaller one is ordered by the version number in each model ID, highest first. Free marks a model whose ID ends in :free, and No tools marks one that cannot call tools, which Arc agents need. Typing a listed model's exact ID into a key's search selects it; an ID the key does not list is offered as Use “…” as typed and sent to the provider unchanged. Change model opens on the agent's own key or server, with its model marked Current.

Apps are agents that run in their own app and join with the room's code. Adding an app with no saved profile sets one up on that first add; the agent then joins through its own harness.

Pin, archive and tidy saved setups

Star (☆) a model, a saved setup, a server's model or a model file to pin it. Pins lead the Pinned source, newest first, and are kept apart from saved setups. A saved setup records who made it (you, an agent, or unknown for setups saved before pins existed) and when an agent last used one. A key lists its pinned setups and those used in the last 14 days, with the rest behind Show all and agent-made setups behind their own link. Archive hides a setup from every picker without stopping agents that already run it; the Archived source lists archived setups, and Restore puts one back.

Tidy up appears in the source list, while you change an agent's model, and in a key's saved-setups header whenever it has something to suggest. It suggests archiving duplicate setups, test-named setups, setups made by agents, setups unused for 30 days and setups that can no longer start, and removing a key saved twice or a duplicate server that lists no models. Pinned and recently used setups are never ticked for you, and setups that are idle or cannot start are offered unticked. Nothing changes until Apply. A duplicate key can be removed only when nothing uses that copy, and a server only when it lists no models and no agent uses it.

A preset is a reusable model configuration. Creating an agent copies the selected settings into that agent; changing the preset later does not replace an existing agent's settings. A later compatibility, vision or pointing test of the same hosted route reaches agents made from that preset. Change model can also switch an existing agent to a preset. Agents and their room seats keep their own identity and access. Existing saved configurations migrate when Arc upgrades.

A project folder is optional for conversation. A folderless managed agent starts with chat-only access: it can read the room, search the web, read pages and answer, but cannot read or edit project files, run commands, or operate the computer. Arc's internal conversation storage is not a project folder. Choose a folder explicitly when the agent needs file tools, then set the room's access. Choosing another model does not increase access. In a Full Access room, an eligible model route can post messages and update room tasks, artifacts, decisions and memory without a folder. Safe access disables those writes. Filesystem, shell, browser and computer tools still require their own access.

Agent settings show effective limit values and where each came from: Arc default, Agent setting, or Model default or limit. App defaults supply inherited values; agent settings can pin them; the room seat's current access limits which tools can run. A role or name does not grant permission.

For API and self-hosted server agents, a blank Temperature uses the model's or server's own sampling default, and a number overrides it for that agent; an agent with a saved temperature keeps it until you clear the field. Temperature is disabled, with a note, for models that ignore it, such as models on Anthropic's API and OpenAI's GPT-5 models. When a provider's catalog lists a model's output limit, an API agent's Output tokens per step is held to it and reads Held to N by the model's output limit; a larger value you saved is kept and shown. A context window a new agent takes from its provider's catalog is labeled as a model value; one you type is an agent setting. Reply delivery, in Limits next to Output tokens per step, shows whether the agent streams and lets a Chat Completions API agent choose; see Know how long a model step may take. Images, also in Limits, says whether attached images reach an API or self-hosted server agent; see Share images with a vision seat. Conversation sets how much of its conversation an agent re-reads each turn and whether it reads the room first; see Choose what an agent remembers.

Change a model without losing the conversation

An idle managed agent can change its model while keeping its agent identity, room role, and committed text conversation. Edits and context exclusions carry across too, including after stopping and starting the seat or restarting Arc. The settings show what was kept. Image access and tool permissions follow the current model and current authorization; old image data and tool-call credentials are not transferred as text memory. Wait for active work to finish, or stop it, before changing models. Work parked on a wake or job must finish or be stopped first.

If Arc cannot load the earlier conversation journal, a new session starts fresh and posts a room notice explaining that the earlier conversation was unavailable. Arc keeps any existing old file for inspection. An available conversation with an unfinished rewind must be resumed so Arc can complete the rewind before changing or starting a model.

Change model refuses when the earlier conversation is unavailable and explains how to restore access to its journal, or stop the seat and explicitly start fresh, before retrying. Reading that history does not block status for other seats. A history that changes during the read must be checked again.

See and manage model queues

People and Work show why an agent is waiting, its model source, and its queue position. Work groups active and queued work by source. Cancel the individual active turn or queued request from that panel. Cancelling a turn keeps its seat running, including when the turn has just finished. A model queue can be waiting for capacity, a request-rate limit, a provider cooldown, or provider recovery. Cancellation can finish when the active socket or local operation unwinds; a stop request does not instantly free capacity held by work still running.

We recommend running one local agent at a time. Agents sharing one local model take turns across the whole turn, including tool steps. Adding seats gives them separate identities and conversations, but does not duplicate the model or make inference parallel. Requests for a larger context wait for the active turn to finish before the shared process is reloaded. Hosted connections instead share a limit on simultaneous model requests.

In Settings → Connections, set Concurrent requests and, optionally, Requests per minute for an API connection. API connections default to four simultaneous requests. Self-hosted servers default to one slot for a whole agent turn; raise the slot count only when the server supports parallel turns. Leave Requests per minute blank for no configured pacing limit. Provider limits still apply. Agents using the same source share provider cooldowns. Ordinary overload or rate-limit cooldowns are capped at 15 minutes; quota exhaustion or an exhausted reset allowance can wait for a daily reset.

Across model queues, operator messages are admitted before awaited replies, then room broadcasts, then background work. Old waiting work gains priority over time. Changing queue priority does not override the room's access or its conversation turn budget.

Choose a model source

Call arc_list_model_sources first. It lists connections (key state, ready or unverified, model count, and presets, the number of setups saved on that key), local models, saved setups (pinned first, then by last use), and recent routes, this room's first; pass query or connection_id to list catalog models. When the operator has pinned sources, pins lists them newest first as hosted:<connection_id>:<model_id>, local:<local_model_id> or preset:<preset_id>, and the result's next asks you to prefer them when a task names no model. Spawn a hosted: pin with connection and model, a local: pin with local_model, and a preset: pin with model_profile_id. A model ID can contain colons, so split a pin on its first two colons only. Archived setups are left out of this list; arc_list_model_profiles still lists them.

arc_list_model_sources {"query": "<model name fragment>", "room_id": "<room_id>"}

arc_list_model_profiles lists saved model presets. A seat does not need one. If nothing suitable is listed, add a connection or local model through the Add agent picker or Settings; agents should ask the operator rather than read Arc's database to discover models.

Requests made through an OpenRouter connection identify the app as Megastructure Arc, so its activity shows the Arc attribution.

A Meta connection, added in Settings → Connections & models with a Meta Model API key, offers Muse Spark and Muse Wonder as agents. The API protocol for a Meta connection defaults to Responses. OpenAI and custom connections can choose Responses too; they default to Chat Completions, and existing setups keep the protocol they were saved with. Run the capability check before relying on a model's tool or image support.

arc_spawn_agents takes one source:

Desktop and terminal harnesses are not spawned. Invite them with arc_create_invite; naming with base and auto_number:true mints one code to paste into every harness, and each session that joins gets the next number.

Spawn seats

arc_spawn_agents {
  "room_id": "<room_id>",
  "connection": "<connection id or label>",
  "model": "<model id>",
  "count": 2,
  "name": "Reviewer",
  "role": "Reviewer",
  "instructions": "Claim an assigned task before work. Post findings with file and test evidence."
}

One call spawns 1–32 seats from one source. name is a base that numbers itself, and a taken name gets the next free number. Each spawned entry carries membership_id, agent_id, workspace_path and workspace_mode. An unknown or conflicting argument is refused and nothing is spawned. behaviours gives every new seat up to 12 presets, for example [{"preset_id": "follows_agent", "params": {"agent_id": "<builder-agent-id>"}}]; each spawned entry then lists the behaviours it got, and one Arc refuses carries an error without undoing the spawn. See Behaviours and coordination flows.

Seats inherit the room's Safe or Full Access; a role label never raises authority. Seats from an unverified connection stay Safe. An experimental route that answered but did not pass certification can be used with workspace_mode:"read_only"; it stays Safe. Certification may return a still-certifying refusal within 8 seconds: call again after it settles. A thinking model that used the probe's output budget may be tried once with a larger budget. workspace_mode:"read_only" gives reviewer seats that cannot write; a seat with no explicitly chosen project folder is chat-only. A worktree-mode room gives each seat its own worktree when it has a project folder. auto_start:true with initial_brief starts every seat with the same first turn; add run_id to count those turns toward a run. What each access level allows is in Workspaces, shell and documents.

workspace_path gives the new seats a folder of their own instead of the room's: an absolute path to an existing folder, with room_id. A read-only reviewer can read a folder the room does not have, and the seats keep their folder when the room's folder changes. A worktree-mode room refuses workspace_path, because every seat there gets its own worktree.

arc_list_seats shows the seats of a room (default: your joined room) or a project: model, enabled, state (idle, running, waiting or stopped), active turn, queue depth, and the room's open runs.

Give a seat work by message

A room message addressed to an enabled seat starts its turn. Address it with to_agent set to the seat's agent ID, or mention its @handle. Messages of kind chat, task, task_request and handoff wake a seat; a notice does not, and neither does a direct message from arc_dm. Assigning a task to a seat with arc_create_task and to_agent wakes it the same way.

arc_post_message {"room_id": "<room_id>", "to_agent": "<seat agent_id>", "body": "Review the changed tests and report failures with evidence."}

The post receipt's seat_delivery says whether the seat was woken and, if not, gives a reason; when several seats are addressed it lists each one. A busy seat queues the message. For addressed work, later messages join a waiting turn only when they come from the same sender; the seat receives them numbered and must answer each. Addressed messages from another sender stay separate. Whole-room listeners instead gather public messages from several senders into a batch; their answer goes to the room, or they stay silent. See Listening and turn budgets.

For addressed work, the seat's final reply goes back to the sender, and wakes the sender if it is a seat. A continuation after wait, remind or a job finishing retains the original asker; an early acknowledgement does not count as the final answer. The journal records reply_skipped when a reply cannot be delivered. A turn woken by a reply ends quietly, so a request costs one answer, not a conversation. A turn woken by a seat working in a run joins that run.

Guards keep seats from messaging each other in a loop: a chain of seat-to-seat wakes stops after 8 turns, and one seat is woken by messages at most 30 times an hour. Each stop leaves one notice that says how to continue. In a room whose metadata.seat_wake is "off", messages do not wake seats; dispatch with arc_run_seat there.

The room's configurable Turn budget also bounds the conversation shared by agents, defaulting to 12 turns. See Bound a conversation's agent turns.

To correct a peer that is mid-turn on something you know is wrong, arc_note_agent delivers one short note at its next step. Anything that can wait belongs in the room.

Share images with a vision seat

A seat whose model sees images receives operator-attached PNG, JPEG, GIF and WebP files after the message text. Arc verifies the bytes against the confirmed file before sending them. Changed, damaged or oversized files are skipped with an explanation. Every GIF frame must fit the declared canvas, including later animation frames. Each file must be at most 8 MiB (3.75 MiB for Anthropic), at most 8000 pixels on either side and at most 33,177,600 pixels in total. Files named in a spawned brief, a dispatch or a queued message must also be admitted for that recipient; another seat's attachment is not shared by naming its path.

Pasted and dropped images, and images attached by another agent with image_artifact_ids, arrive as real images when their message starts a vision-capable managed agent's turn. Arc checks the room artifact and media again at turn admission, including queued turns. File-button images take priority within the usual three-image cap; a small context window permits fewer or none, and text-only models keep the references and alt text. See Images, screenshots and mock-ups.

Whether a seat sees images is Arc's verdict for its model. A certified setup carries the verdict of its capability test, and a self-hosted server agent follows Arc's latest image check of its server. An API agent added with Add agent is never certified, so when it starts without a verdict, Arc sends its model one small image request and keeps the answer: a model that sees gets images from then on, and one that cannot keeps the text references and a note saying the pictures were not shown. Until that check has run, a provider catalog that lists the model's input types, such as OpenRouter's, decides. A provider that rejects the image part itself has given a verdict. A rejected key, an empty balance, a rate limit or a cancelled start records nothing, and the next start asks again. A failure on the endpoint's side (a server error, a dropped connection, the Response deadline, or a streamed error without a status) is recorded with its time, and starts within the next ten minutes skip the check.

Agent settings → Limits → Images sets this for an API or self-hosted server agent: Arc decides (the default), Shown, which sends attached images to a model Arc could not confirm, or Not shown, which keeps the agent to text. The row shows what Arc decided and why, or why there is no answer yet, and a change applies from the agent's next turn. Not shown also withholds Arc's computer tool; see Computer use.

A model-file agent sees images when its model loads with a vision projector, the mmproj .gguf that vision models ship beside their weights. When the model file's folder holds exactly one .gguf with mmproj in its name, Arc loads it with the model and counts it when sizing the context window; with several, it loads none until one is chosen. When the agent starts, it checks once that its model sees an image, and a timeout leaves the question for the next start. Model-file agents have no Images row. A model file added before Arc 2.1.6 has no projector on record: add it again, then add its agents from the new entry.

Steer a working agent

Text steers arrive together and in order at the next step. A steer arriving after the last step, or while the agent is idle, starts its own turn. Stopping that turn drops pending steers. Steers already read remain in conversation memory, including across a pause and resume. A message with images is sent as a normal message so it carries the pictures.

Commission a run and dispatch seats

A run groups seat turns, wakes, events, usage and a completion record under one objective. Use one when an outcome needs several turns or several seats.

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": {"tokens": 2000000, "elapsed_minutes": 60}
}

A run stays open until arc_complete_run or arc_stop_run. A run with no conductor can take auto_complete:true: it completes about two minutes after its last turn ends, once nothing is queued and Done-when passes. A seat that creates a run from its active turn attributes that turn to the run.

Create tracked tasks for independent slices, assign each to a seat's agent ID, then dispatch:

arc_run_seat {
  "run_id": "<run_id>",
  "membership_id": "<membership_id>",
  "brief": "Claim task <task_id>, complete it with evidence, and report to the conductor.",
  "max_steps": 80,
  "origin_id": "release-review-task-<task_id>"
}

run_id is required; name the seat by membership_id or agent_id. max_steps (1–500) is a checkpoint interval, not a lifetime limit; Arc continues unfinished work automatically. A busy or starting seat queues the turn in FIFO order, and blocked_by says what it waits behind. Repeat the same origin_id when retrying a delivery to get the existing turn back instead of a second one; request_id protects any single write.

Watch progress and tokens

The working strip above the composer shows an Arc-managed agent's current step: waiting for its model or running a named tool, with the tool's target when available. Each step has its own timer, which changes to the warning colour after a minute. A model request that has waited longer than a minute shows as waiting on its provider for N min, and the seat's events record one model_step_slow entry for that step, with the provider, model and seconds waited. A steer you send while the agent works is shown as queued for the next step or delivered. When a turn waits for model capacity, the strip names its model lane and queue position and does not show a slow-step warning for queued work. These details describe Arc-managed agents; agents in outside apps provide their own activity through those apps.

• arc_list_runs rows carry activity (working, waiting or idle), idle_since, completable and blockers. Run status is commissioned, running, paused, completed, stopped or failed.
• arc_run_status returns a bounded summary: run-tagged work, events, activity, completable, token usage and target deltas. Use detail:"full" only for transcript diagnostics.
• arc_seat_status narrows to one seat: turn digests, queue, active turn and token usage. detail:"full" with a turn_id returns that turn's events.

An idle seat has stopped working; that does not mean its task is satisfied.

Reported tokens are visible, never capped. The token_usage line reports prompt_tokens, completion_tokens and unreported_turns (turns with incomplete token observations). Full usage includes reported totals and model steps. Missing usage means unavailable, not zero. Dollar totals, provider costs and catalog-based estimates are not reported. usage_target accepts tokens, steps and elapsed_minutes; there is no dollar target. Crossing a target emits run.usage_target_exceeded and never stops work, so stop the work yourself when the operator's limit is reached.

Thinking level, output tokens per step, temperature, steps per turn and the other per-agent limits are the operator's Agent settings. Over HTTP, PATCH /v1/agent-profiles/{id}/runtime-binding sets them (thinking is reasoning_effort: none, minimal, low, medium, high, xhigh or max, blank for the model default; Meta and Anthropic models take fewer, and a refusal lists the levels they take; for other providers Arc sends the chosen level and the provider decides whether it accepts it) from the seat's next turn. For API and self-hosted server agents, a blank or null temperature restores the model's or server's own default, provider_recovery_enabled takes true, false, or null for Arc's default (on), and supports_vision_override (Images) takes true for Shown, false for Not shown, or null to let Arc decide. internal_streaming (Reply delivery) takes true for Streaming, false for Buffered replies, or null for Arc's default (streaming); only Chat Completions API agents accept it. history_exchanges, history_digest and room_read_along set Conversation for every Arc-managed agent; see Choose what an agent remembers. See agent profile routes. For a model file, projector on POST /v1/local-models, POST /v1/model-profiles and PATCH /v1/model-profiles/{id} takes auto (the default: the one mmproj .gguf beside the model), off, or the path of a projector .gguf; Agent settings has no control for it.

Stop work

arc_stop_seat stops one seat's work and keeps its session. The default scope:"run" stops that run's active and queued turns; scope:"seat" stops the seat's active turn from any run and its whole queue, as the Stop button does. arc_stop_run stops all work tagged to the run and marks it stopped; unrelated turns in reused sessions survive.

arc_cancel_seat_turn cancels one managed seat's active turn while keeping its session and queue. Name the room (or use your joined room) and the seat's membership_id or agent_id; no run ID or generation fence is needed. It returns cancelled:false with a note when there is no active turn. A seat cannot cancel its own turn this way.

To read recent tool steps and turn boundaries without a full transcript, use arc_seat_steps with the same room and seat selectors. Pass since and feed the returned next_since into the next read; limit bounds a page. An empty page with a no-session note is a valid result. The HTTP equivalents are GET /v1/rooms/{id}/seat-steps and POST /v1/rooms/{id}/cancel-seat-turn; session journal reads also accept since and compact.

Know how long a model step may take

The Response deadline in Agent settings → Advanced, 300 seconds by default, bounds how long an agent waits for its model. For a self-hosted server it is the longest silence between tokens. API agents stream their replies by default, including agents and saved setups on built-in providers created before streaming became the default; a custom OpenAI-compatible endpoint saved with buffered replies keeps them until you change its Reply delivery. A streamed reply ends when no new output (text, reasoning or tool-call arguments) arrives for the deadline, or after a hard cap of the larger of one hour and four times the deadline, so a long reply that keeps producing output is not cut off; keepalives do not count as output. A buffered reply must finish within the deadline.

When a provider rejects a streaming request and the rejection names its stream or stream_options setting, Arc sends the request again without streaming; a rejection that names neither is reported, not re-sent. An endpoint that ignores the streaming request and answers in one piece with a JSON reply keeps that reply without a second request.

Reply delivery sits in Agent settings → Limits, next to Output tokens per step. An API agent that uses the Chat Completions protocol, including a custom OpenAI-compatible endpoint, can choose Arc default: Streaming, Streaming, or Buffered replies. A custom endpoint saved with buffered replies keeps them until you choose Streaming or Arc default there; upgrading does not change it. A change applies from the agent's next turn, and it also asks a provider that declined streaming for a stream again; only another refusal buffers it. API agents on Anthropic Messages or Responses, and self-hosted server agents, always stream, so their Reply delivery is read-only. While a running agent's provider is declining streaming, the setting shows Buffered replies (provider declined streaming).

A step that runs out of time fails with provider_request_timeout, and the message says which limit ended it. Arc does not re-send a request the provider may already be working on; the agent holds the unfinished step instead (see Recover from provider failures). The message says what to change before you choose Retry unfinished step now: raise Response deadline in Agent settings → Advanced for a model that thinks for a long time before it writes, or lower Output tokens per step in Agent settings → Limits when replies keep reaching the hard cap. For an agent whose Reply delivery is set to Buffered replies, it also suggests switching to Streaming, which lets a reply run as long as new output keeps arriving. The failure offers Open relevant settings, which opens that agent's Agent settings at Response deadline, expanding Advanced, or at Output tokens per step when the hard cap ended the reply.

Recover from provider failures

When an API or self-hosted server agent's provider is rate-limited, overloaded or briefly failing, Arc retries only the unfinished model step, after about 20 seconds and then about 3 minutes. Tool work the agent already finished stays in its conversation and is never run again. A stream the provider ends with an unexplained error gets one retry, after about 3 minutes. Waits honor the provider's Retry-After; when waiting would take recovery past ten minutes in total, Arc pauses and shows the earliest retry time.

Arc never automatically re-sends a request the provider refused, for example a rejected key, exhausted quota or an invalid request, or a request to an API provider whose outcome is unknown because the connection dropped after it was sent. In those cases, and when retries run out, the agent holds the unfinished step until the operator acts. A self-hosted server or model file that drops the connection still gets one immediate re-send once it answers again; see Recover from a model-server restart.

While a step is waiting or held, a card in the room shows the provider's error, how many replies are waiting, and Recovery details with Copy diagnostics, including the provider's request or generation ID when it sends one. While a retry is scheduled, the card also shows the countdown and the automatic retries used, and the agent's model queue entry reads Waiting for provider recovery. The card offers:

• Retry unfinished step now, which sends the held step at once. It is unavailable while a request is in flight or while a provider cooldown runs.
• Pause retries, which holds a scheduled retry.
• Open relevant settings, when the failure names a setting.
• Provider recovery, which opens that setting for the agent.

Stopping the agent cancels recovery. Messages sent to the agent meanwhile wait in its queue and run in order once the step completes; they do not start a new turn, so timeout and dropped-connection errors point to Retry unfinished step now rather than a new message. Only the operator can retry or pause recovery. A retry asked for while a provider cooldown runs is refused with the earliest retry time in the local time of the computer running Arc, with its UTC offset, for example 2026-10-15T00:30:00-07:00. A limit you change in Agent settings, such as the Response deadline, applies when you choose Retry unfinished step now. Agents can see a held seat with arc_seat_status: its session status reads error, and its queued turns carry a blocked note.

The unfinished step, finished tool work, token counts and retry counts are saved in the agent's private session journal, so recovery continues when the agent resumes after Arc restarts. A request cut off by a restart stays paused and is marked as having an unknown outcome; check the provider's activity before you retry it. Arc will not resume a step after the agent's model, key, folder or room access has changed.

Provider recovery is on by default. Turn it off for one agent in Agent settings → Advanced → Provider recovery; Arc then makes no automatic retries, and a failed step still waits for you to retry it or stop the agent. Agents running a model file get no timed retries, but a failed step shows the same card in local-model wording.

When a provider rejects a request and names its temperature, thinking level or output-token value, the failure offers Open relevant settings. It opens that agent's Agent settings at Temperature, Thinking or Output tokens per step, without saving anything or retrying the request.

Recover from a model-server restart

If a local or self-hosted model server closes or refuses the connection, Arc names the server and waits up to 10 seconds for it to answer before retrying the step once. If the server stays unavailable, the agent's provider recovery takes over, as described above. A self-hosted server agent with Provider recovery off skips this wait too. API provider steps are not retried this way. Thinking Off sends llama-server's per-request thinking switch; other thinking levels do not set its server-side reasoning budget.

Choose what an agent remembers

Each turn, an Arc-managed agent re-reads its own recent exchanges, each request it was given and its reply, as text: tool calls, tool results and images are never replayed. Agent settings → Conversation sets three things for each agent, on API, self-hosted server and model-file agents alike:

• Conversation memory (exchanges): how many recent exchanges the agent re-reads in full, a whole number from 1 to 50. Blank uses Arc's default of 12, up from 6 before, so each turn sends more of the conversation and an agent billed through a provider's API uses more input tokens; set it to 6, and Older exchanges to Dropped, for the earlier amount. Arc's replay character budget, sized from the model's context window, still applies, so on a small window older replayed exchanges are clipped.
• Older exchanges: Summarised (Arc's default) or Dropped. Summarised opens the replayed conversation with a short summary of up to 20 of the newest exchanges older than the memory: what was asked, and the reply's main points, such as its headings, its opening and the sentences that state a choice. Each names the message ID of the posted reply, so the agent can read the whole of it with arc_list_messages. Arc builds the summary on this computer from the text, without another model call, in at most a tenth of the replay budget (600 to 4,000 characters), and counts the exchanges it leaves out. The agent's Context panel shows the summary its next turn carries. Dropped leaves older exchanges out.
• Read the room: Off (Arc's default) or On. With it on, a turn that a room message starts, including your own message to the agent, first carries what the room said since its last turn: public posts, and messages to and from the other agents Arc runs. Messages addressed to an agent in its own app are not included. The newest messages are kept, up to 30 messages and 12,000 characters, each message clipped at 2,000 characters, with a pointer to read the rest. The agent's own posts, messages addressed to it, Arc's notices and private messages are left out, and none of these messages wakes the agent. The block becomes part of that turn's request, so a retry reads the room afresh instead of twice.

Excluded exchanges stay out of both the memory and the summary. A change applies from the agent's next turn and carries across Change model. Over HTTP, PATCH /v1/agent-profiles/{id}/runtime-binding takes history_exchanges (1 to 50, or null for Arc's default), history_digest (false for Dropped, true, or null for Arc's default, summarised) and room_read_along (true, false, or null for Arc's default, off).

Repair a seat's memory

arc_seat_context shows what the seat's next turn will replay, including earlier_digest, the summary of older exchanges that turn carries, and returns history_revision. Pass that value as expected_history_revision to the tools below; a stale value is refused.

Retry and rewind take dry_run:true for a preview and refuse while the seat is busy. They change conversation replay only: files, tasks, claims, artifacts and decisions stay. Replaced rows stay in the room as stubs for audit.

Make completion observable

Free-prose Done-when is a contract the agent must verify. Structured clauses also gate managed completion. After creating the actual tasks, read the room's state_version with arc_get_room_status and 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 version you read and 42 with a real task ID. A stale version requires a fresh read and reconciliation. A task clause names a positive tracked task ID and is met when that task is done. A verdict clause names a metric and optionally a verdict_id, or a target_kind with a target_id; it is met by a passing, unretracted fitness verdict in the room. A seat gate adds membership_id and takes that membership's revision as expected_version; inherit:true with clauses omitted restores the room gate. Unknown or malformed clauses are refused.

Do not weaken a gate to make completion succeed. Review task evidence, files, artifacts and every prose clause too: only structured clauses are machine-checked, and a done task row alone does not prove quality.

Complete the run

When every turn, queue, wake delivery and Done-when clause is settled, call arc_complete_run. A seat may call it from its own final run-tagged turn. Then call arc_run_report once to create the run's report artifact; it returns a receipt, and a repeat call refreshes the same artifact. For open-ended recurring work, use a loop instead; loop cycles end with finish, not arc_complete_run.

Start a crew from a template

Call arc_list_templates, then arc_get_template to read a template's fields, roles and task tree. arc_apply_template adds its room to an existing project, or creates a project when project_id is omitted; supply values for declared fields and override descriptions, roles or names as the task requires. For example, with a real role and model:

{"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 task tree. Managed crew entries spawn seats (omit source for the machine default); mode:"invite" entries mint reusable named harness invites, with a preferred_harness when needed. The daemon posts a kickoff contract and returns created IDs, seeded tasks and crew results. Review them, then dispatch the work.

Related

• Runs, seats and model sources tools
• Seat context tools
• Workspaces, shell and documents
• Loops
• Run HTTP routes, seat routes and model source routes
• Event and message vocabulary