agent

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.

post/v1/agent/run

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

threadIdstring required

The opaque Snowflake thread id (agent_threads.threadId).

parentMessageIdstring nullable

Digits only. Omit/null on the first turn of a thread.

messagestring required
purpose'popup' | 'block' required

Independent turn budgets per purpose.

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.