Sessions and turns

A call to /services/agent/v0/invoke creates one turn. Reusing session_id associates later turns with the same conversation and sandbox workspace.

Start and continue

Omit session_id to let Agenta mint one, then store x-ag-session-id from the response. Supply that ID on every later invoke request.

When your client also uses /api/sessions, keep IDs to letters, numbers, underscores, and hyphens. The management API currently accepts a narrower character set than invoke.

Run in the background

Every run belongs to a session. When the request has no session_id, Agenta mints one. The run is tied to the session, not to the HTTP connection. If the client disconnects before the turn ends, the run continues and Agenta stores its records.

To start a run without waiting for it:

1. Send your own session_id, so you know where to read the result.

2. Request Accept: text/event-stream and set "flags": {"detached": true} in the body.

3. Read the first frame. A session-accepted frame confirms that the run started:

   data: {"type": "data", "data": {"type": "data", "name": "session-accepted", "data": {"sessionId": "019d952f-0000-0000-0000-000000000001", "turnId": "019d952f-0000-0000-0000-000000000005", "executionId": "019d952f-0000-0000-0000-000000000005"}, "transient": true}}

4. Close the connection.

curl -N -X POST \
  "https://eu.cloud.agenta.ai/services/agent/v0/invoke?project_id=019d952f-0000-0000-0000-000000000000" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "019d952f-0000-0000-0000-000000000001",
    "flags": {"detached": true},
    "references": {"workflow_revision": {"id": "019d952f-0000-0000-0000-000000000002"}},
    "data": {"inputs": {"messages": [{"role": "user", "content": "Research lead L-1042."}]}}
  }'

A request without detached also keeps running after a disconnect. The difference is that the client cannot tell whether the run started before the connection dropped. Check the session's records before you send the turn again.

To read the result later, use either endpoint:

Method and path	Returns
POST /api/sessions/records/query	The session's records for the body {"session_id": "<id>"}. A finished turn ends with the agent message and a done record.
GET /api/sessions/{session_id}/events	The durable events, replayed from after=<cursor>, then the live stream. See Session events.

Agenta does not call a webhook when a run ends. Poll the records, or keep the event stream open. A background turn that needs approval stores attributes.stopReason: "paused" on the final done record returned by records query. The events endpoint reports the same condition as execution.stopped.payload.reason: "paused". Answer it as described in Pause and resume.

Busy sessions

Set top-level on_busy when a session already has an active execution:

Value	Behavior
reject	Refuse overlapping work.
queue	Queue the new input behind the active execution.
steer	Deliver input to the active execution when the harness supports it.

on_busy requires an explicit session_id.

Pause and resume

A gated tool, user-input request, or client tool can end a turn with stop_reason: "paused". The response contains pending_interaction; durable session APIs also expose the interaction.

Resume in either way:

• replay the paused assistant message with the answer represented as a tool result; or
• call POST /api/sessions/interactions/{interaction_id}/respond with an Idempotency-Key header. It returns 202.

A retry with the same key and the same answer is safe. A different answer to an interaction that was already answered returns 409, and so does any answer to a resolved or cancelled interaction.

Stop an execution

POST /api/sessions/{session_id}/cancel
Authorization: ApiKey {API_KEY}

Stopping targets active work; it does not delete the session. Use the session management endpoints to archive or delete stored session data.

Warm state and replay

Agenta may retain a warm harness and sandbox between turns. If that state is unavailable, it reconstructs conversation history from session records. Applications should persist the session ID and complete message or interaction data, not assume a specific process remains alive.