Background Runs and Streaming

Use the support-agent service from Run Claude or Run Codex. Add the deployment queue configuration before relying on worker recovery.

Start background work with a stream

curl -N http://127.0.0.1:7777/agents/support-agent/runs \
  -F 'message=Explain the steps for investigating a delayed order. Do not use tools.' \
  -F 'session_id=background-demo' \
  -F 'background=true' \
  -F 'stream=true'

This request returns SSE. Copy the run ID and latest event_index. Closing this client connection does not cancel a background run. Short requests may complete before you disconnect; use a controlled slow tool when testing a genuinely active reconnect.

Reconnect or poll

Set the values from the original stream:

RUN_ID="paste-the-run-id"
LAST_EVENT_INDEX="paste-the-last-received-event-index"
curl -N -X POST "http://127.0.0.1:7777/agents/support-agent/runs/$RUN_ID/resume" \
  -F 'session_id=background-demo' \
  -F "last_event_index=$LAST_EVENT_INDEX"

Use the last received index, not the count of displayed text chunks. With shared Redis coordination, a different API replica can provide retained events. If you received no indexed event, use -1 to request the retained stream from its beginning.

Poll the stored run independently:

curl "http://127.0.0.1:7777/agents/support-agent/runs/$RUN_ID?session_id=background-demo"

For Claude and Codex, request streaming at submission if later event catch-up is required. A background request with stream=false returns HTTP 202 and a run ID for polling, but does not establish replayable SSE events. When live transport events expire, /resume can replay retained events from the stored run. AgentOS enables event storage for registered harness agents; RunContent token deltas are skipped by default, so database replay is not a token-for-token copy of the live stream. Use the stored terminal content for the final answer. An unavailable Redis connection is distinct from an expired stream; handle transport errors and poll saved run state when appropriate.

Cancel a run

curl -X POST "http://127.0.0.1:7777/agents/support-agent/runs/$RUN_ID/cancel?session_id=background-demo"

For durable queued runs, inspect metadata.queue.final when polling: the queue's settled outcome is distinct from a failed component attempt. See Retries and Tool Effects for retry, pause and unknown-finality handling.

Poll for terminal status after cancellation. Cancellation does not undo tool effects that have already happened. Share Redis coordination to cancel through a replica other than the one executing the run.

Choose the durability policy

background=true separates execution from the client connection. Add QueueConfig(durable=True) for supported requests that must be durably accepted. Share Postgres for storage and Redis for multi-replica coordination.

The default queue max_attempts=1 makes interrupted execution fail visibly without automatic re-execution. Opting into more attempts can repeat external effects. See Durable Queue for queue eligibility, ownership and retry configuration, and Deploy and Operate for the combined service setup.