Runs

Runs are single, bounded executions of an Intent under explicit guardrails (Context, User ID, Integration Selection, Approval Strategy). A run plans, calls tools, streams events, and produces a final state and optional result.

Why Runs exist

• Provide a durable unit of work you can audit and reason about.

• Keep actions tenant - and user-scoped (tokens tied to userId).

• Enforce safety via approvals and allow-listed integrations per run.

• Offer live observability via SSE and a consistent state model.

Anatomy of a Run

• Identity: runId (UUID)

• Intent: outcome you want (natural language)

• Context: hidden execution parameters (timezone, filters, IDs, flags)

• User ID: whose permissions/tokens apply (act-as-user)

• Integration Selection: selectedCustomerIntegrationIds allow-list or "*" (all active)

• Approval Strategy: NONE | ON_START | ON_TOOL_CALL

• Plan: text or json (returned in CreateRunResponse)

• Events (SSE): realtime lifecycle & step logs

• Result: optional structured output on completion

Lifecycle

QUEUED → RUNNING → (AUTH_REQUIRED | PAUSED)* → (SUCCESS | FAILED | CANCELED)

• QUEUED — accepted, waiting to start

• RUNNING — planning/executing; events stream over SSE

• AUTH_REQUIRED — needs user authorization (OAuth/token); auth link appears in SSE and Run events

• PAUSED — waiting for approval decision (GET /v1/runs/approval?token=...)

• SUCCESS/FAILED/CANCELED — terminal states; inspect logs, stepsFinished, and result

Planning vs Execution

• Planner builds a plan (text/json) from Intent & Context within the limits of selected integrations and approval strategy.

• Executor performs tool calls, enforces approvals, rate limits, and emits events.

Approvals (human‑in‑the‑loop)

• NONE — fire-and-forget.

• ON_START — approve the plan before any calls.

• ON_TOOL_CALL — approve each external call (recommended for production writes).

Identity & Scope

• userId defines which tokens are used. Choose least privilege.

• selectedCustomerIntegrationIds limits which tools are callable this run.

Observability

• Subscribe to GET /v1/runs/{runId}/sse for: status, step.started, step.completed, approval.required, approval.resolved, result, error.

• Use GET /v1/runs/{runId} to fetch the latest state; stepsFinished summarizes work done.

Cancellation & retries

• Abort queued/running runs: DELETE /v1/runs/{runId}.

• To retry after failure or cancellation, create a new run with corrected context/auth.

Best practices

• Write declarative intents; avoid how-to steps.

• Put sensitive/technical details in Context (not user-visible).

• Start strict with ON_TOOL_CALL; relax as confidence grows.

• Prefer explicit allow-lists over "*" in production.

• Batch responsibly (limits in Context), and watch SSE during rollout.