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.

PreviousIntent & ContextNextIntegrations

Last updated