Agent Runs

An Agent Run groups one autonomous task with the Actions it creates. Runs are optional: a standalone Action works exactly as before, and ActionBox does not replace your framework's checkpoint, transcript, or tool state.

Use a Run when an operator needs to answer questions such as “What task created this Action?”, “What stage is it in?”, or “Has the agent stopped making progress?”

Start and link a Run

external_id is your stable identifier for the task. Reusing it for the same Source and input safely returns the existing Run.

import os
from actionbox import Actionbox

with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
    run = client.runs.start(
        external_id="checkout-fix-42",
        agent_name="codex",
        title="Fix checkout deadlock",
        stall_after_seconds=900,
    )
    run.progress(stage="tests", checkpoint="test-184")
    action = client.create(
        title="Approve the staging migration",
        run_id=run.id,
    )
    run.complete()

The Python and TypeScript SDKs manage progress sequence numbers and idempotency keys. Wire-level callers must send the next sequence value with each progress update.

Progress and waiting

A progress update can change stage, checkpoint, or status. Use waiting when the agent is deliberately paused for an external dependency; return to running when work resumes. Keep these values short and operational. Do not send transcripts, prompts, secrets, or tool logs as progress fields.

When stall_after_seconds is set, ActionBox can monitor the Run for unchanged progress. Repeating the same status, stage, and checkpoint proves liveness but does not reset the stall timer. A detected stall creates one ordinary linked Action; changed progress or Run completion resolves the open incident.

HTTP endpoints

Source-authenticated integrations use:

• POST /v1/runs to start or replay a Run.
• GET /v1/source/runs/{run_id} to read their Run.
• PATCH /v1/source/runs/{run_id}/progress to advance progress.
• POST /v1/source/runs/{run_id}/complete to finish with succeeded, failed, or cancelled.

Signed-in users can list workspace Runs with GET /v1/runs and inspect one with GET /v1/runs/{run_id}. See the live OpenAPI document for complete request and response schemas.