Run one turn of a Cortex Agent conversation.
Streams the raw Cortex Agent SSE response back with no retry (ADR-0082 D6: a turn is never silently re-sent to the LLM) — exactly one upstream attempt. dvt does not parse frame content; the forwarded response is a pass-through (minus one internal SSE comment line, : dvt-usage {...}, the engine appends and this endpoint strips before forwarding, used only to record token-usage telemetry — agent_turns, never the transcript). In snowflake mode every frame is additionally persisted for up to ~48 hours for resume — see below. Subject to a per-org, per-purpose turn budget (30/hour); exceeding it returns 429.
DVT-4436: the underlying Cortex Agent call is detached from this HTTP request — it keeps running to completion (bounded by a 15-minute ceiling, or an explicit POST /v1/agent/runs/{runId}/cancel) regardless of whether this response stays open, in every edition. The first frame is always event: dvt.run (AgentRunFrame), written before any engine byte; every following frame (including the final event: dvt.done, AgentRunDone) carries an SSE id: <seq> line. The resume half of this contract — the response closing CLEANLY (normal EOF, no error) after at most ~75s with a final event: dvt.resume (AgentRunResume) frame naming a cursor to reconnect with via GET /v1/agent/runs/{runId}/events?since=<cursor> — is gated by editionCapabilities.agentRunResume (true in snowflake mode only): off editions stream to completion instead, exactly this route's pre-DVT-4436 shape. As a deliberate, bounded deviation from ADR-0082 D6 ("dvt holds no transcript"), SNOWFLAKE MODE ONLY additionally persists every frame of a run server-side SOLELY to make that resume possible — frames MAY include tool results (warehouse-derived content, e.g. a response.tool_result frame's query rows), organization-scoped, never logged, and purged by the daily retention sweep once older than 24 hours (at most ~48 hours at rest; requires RETENTION_ENABLED, default true, and not RETENTION_DRY_RUN) — see the agent_turn_events migration header and DVT-4544 for the tracked ADR-0082 amendment.
Request
- Base URL: http://localhost:8080
- URL: http://localhost:8080/v1/agent/run
- Auth: one of:
- API key in cookie dvt_session
- HTTP bearer
Request body
Response
The raw Cortex Agent SSE stream (text/event-stream), usage comment line stripped. The proxy also injects SSE comment lines : keepalive (no data, no trailing blank line) at a fixed interval while the upstream is silent; conformant clients ignore them.
Changes
No recorded changes to this operation across all 1 revision of this API.