Skip to documentation
eli.aidocs

Ports

Running & tracing

A run is one execution of an agent. Start it from the UI or API, watch tokens and tool calls stream in real time, then inspect the full step-by-step trace — the "show me exactly why it answered that" artifact. Runs live at /w/<workspace>/runs.

Start & stream

  1. Provide an input

    Type the task or question. UI, API, and scheduled starts all persist a queued row and execute in the worker, bounded by per-run and workspace admission controls.

  2. Watch it stream

    The UI follows the DB-backed reattachment stream: model_call (the model produced text and/or tool calls), tool_call (a tool ran, with an ok/error flag), and a terminal final / suspended / error event.

  3. Read the result

    On success you get the answer text and its citations. If a budget was hit, the status is budget_exceeded and you still get the partial answer produced so far.
the SSE event streamtext
data: {"type":"model_call","runId":"01J…","textLength":0,"toolCalls":1}
data: {"type":"tool_call","runId":"01J…","name":"kb_search","ok":true}
data: {"type":"model_call","runId":"01J…","textLength":412,"toolCalls":0}
data: {"type":"final","runId":"01J…","status":"succeeded","text":"…","citations":[…]}

The step timeline

Open a run at /w/<workspace>/runs/<id> to see its flat, ordered step list. Each step is one of:

  • model_call — a model turn, with tokens, cost, latency, and the model id.
  • tool_call / mcp_call — a tool invocation with its input, its result payload (capped), and an ok / error status.
  • guardrail — a deterministic or judge verdict.
  • approval — a human-in-the-loop pause (see Approvals & feedback).
  • retry — a schema or citation repair round.

The run header shows totals — status, token in/out, cost (6-decimal), trigger (ui/ api / eval / schedule), and the pinned agent version.

Run statuses

queued · running · suspended (awaiting approval) · succeeded · failed · budget_exceeded (graceful stop with a partial answer) · interrupted (crash-orphaned, marked by the boot reaper).

Cancel

Cancellation is cooperative: it sets a durable DB cancel flag that the worker polls between steps. The run ends with whatever partial output it had. From the API: POST /api/v1/runs/:id/cancel.

Durability

Run state persists at every step, so a crash or deploy leaves an inspectable record rather than a lost run. Both queued starts and suspended approval decisions are durable handoff records. Worker reconciliation can re-enqueue an interrupted initial start or continuation after a broker or web-process failure. Stable job identities plus the conditional queued-row claim make duplicate delivery harmless. See Agents & the harness for the durability model.

Endpoints

  • GET /api/w/:workspaceId/runs — list runs (UI).
  • GET /api/w/:workspaceId/runs/:id — a run and its steps.
  • POST /api/w/:workspaceId/runs/:id/cancel — cancel.

The external equivalents are documented in Agents & runs (v1).