Agent runs

An agent run is an autonomous task: the model plans, calls tools (web, code, the workspace's data, file creation, a real browser), verifies, and delivers a result — streamed step by step. Unlike chat, it owns the task end to end.

Start a run

POST/v1/workspaces/{workspace_id}/agent/runs —

start the run. The run is decoupled from the connection: this endpoint returns a small JSON object immediately and the engine keeps working detached. Tail the live stream with GET …/attach (below).

Minimal integration — one field. Send only {"task": "…"} and you're done. The platform auto-routes to the best model, auto-picks and calls the right tools (web search, your knowledge base, code, browser…), and streams the result back. You never wire up tools, models, or prompts yourself — every other body field below is an optional override for when you want more control. See the Cookbook for copy-paste examples.

POST returns {"run_id", "trace_id"} — the run id is all you need to follow it. A client disconnect never kills the run; billing, persistence and the final answer always land.

Required:

task — what to do, in natural language (up to 20,000 chars). That's the only field you must send.

Optional (all have sensible defaults — override only when needed):

model — empty lets the platform pick a tool-capable driver. Pin only to force a specific one.
max_steps — cap on tool/think iterations (1–50).
budget_usd — a hard cost ceiling (> 0, up to 100).
pro — unlocks deeper, multi-threaded reasoning (parallel sub-agents on complex tasks).
project_id — run with a project's instructions and files injected as context.
conversation_id — thread this run under an existing chat conversation (the result is written back into that thread). Omit for a standalone task.
skills — slugs of skills the user explicitly picked (up to 8); empty runs the pure baseline (skills are never auto-attached).
persona_slug — a specialist role from the agency-agents library; injected as an identity head for this run. At most one.
history — recent turns ({role, content}, role is user or assistant) for cross-turn continuity. Ignored when conversation_id is set (history is then rebuilt server-side).
mode — composer lane hint (auto lets the router pick chat / agent / cowork / code). Only consulted when the unified router is enabled.
approval_mode — posture for dangerous local-machine actions: ask (default, pauses for the user's OK) or auto (runs without pausing).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Compare the fee schedules of Wise and Airwallex; output a table.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

Follow the run (Server-Sent Events)

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

tail the run's event stream (text/event-stream). Each frame is one JSON object on a data: line.

It is reconnect-safe: the id: line carries a stream entry id, so EventSource tracks lastEventId natively and resends it as Last-Event-ID on reconnect — a refresh, a WiFi flip, or a second device opening the run resumes exactly where it left off (the backlog is replayed from your last-seen id). The generator closes after the run's terminal frame; idle periods get a : ping heartbeat so proxies don't drop the connection.

Event types:

type	fields	when
`step_start`	`step_no`	a loop iteration began
`llm_delta`	`step_no`, `text`	streamed model text
`reasoning` / `reasoning_delta`	`step_no`, `text`	the step's chain-of-thought (full at turn end; deltas stream it live)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	the model requested a tool (deltas stream the args)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	a long tool reports interim progress
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	a tool finished (may carry `artifacts`, `sources`, `screenshot_url`)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	a dangerous local action is awaiting (or got) a user decision
`step_end`	`step_no`, `cost_usd`	iteration done
`context_compacted`	`step_no`, `summary`	old turns were rolled into a summary to fit the context window
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	terminal — the final answer is in `final_text`
`error`	`message`	terminal failure

Every event also carries run_id (and step_no) so a multiplexed consumer can route frames without per-connection state. The stream ends with the terminal run_end (or error) frame — there is no [DONE] sentinel.

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

Prefer GET …/attach over replaying POST: it resumable from Last-Event-ID, so reconnecting clients never lose frames. The run keeps going whether or not anyone is attached.

Manage runs

GET/v1/workspaces/{workspace_id}/agent/runs —

list runs (query: limit, project_id, scheduled_only, include_archived).

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

fetch one: status, the persisted final_text, the full steps trajectory, cost, and produced artifacts.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

stop a running task. Cooperative and cross-worker (sets a flag the loop checks at its next step boundary); idempotent — cancelling a finished run is a no-op that returns its terminal status.

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

edit the recents entry: title, archived, favorited, or move it project_id (a null project_id moves it out).

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

delete a run from history (its steps cascade). Cancel a running run first.

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

download every artifact the run produced as a single .zip.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

mint / revoke a read-only public replay link (body: optional expires_in_days).

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

answer a dangerous-local-action approval (body: {approved: true|false}), the kind surfaced by an approval_request event.

Run status

run_end.status (and GET …/runs/{run_id}) is one of pending, running, succeeded, failed, cancelled, or partial (the task finished with a partial result that is still useful). The terminal states are succeeded, failed, cancelled and partial.

Files the agent produces (documents, sheets, slides, charts, web apps) come back as artifacts on the run. A run is bounded by both budget_usd and the workspace balance, so it can never run away.