Sandbox SDK

Two ways to run an agent

Route	Best for
Typed procedures on the Studio API (`agent.runs.*`)	TypeScript backends already using the Studio client
Session gateway (plain HTTP + SSE)	Any language, any frontend, embedding a chat surface

The session gateway

{STUDIO_URL}/api/agents/{agentId}/eve/v1/session

A preview variant exists for unpublished agents, used by the builder:

{STUDIO_URL}/api/agents/{agentId}/preview/eve/v1/session

Authentication is the same as the rest of the API: a session cookie, or a studio_ API key.

The lifecycle

Loading diagram...

1. Send a message

POST /api/agents/{agentId}/eve/v1/session
Content-Type: application/json
 
{
  "message": "Summarise the Q3 revenue report."
}

Or send structured parts:

{ "message": [{ "type": "text", "text": "Summarise the Q3 revenue report." }] }

Send either a message or an inputResponses array, never both.

2. Stream the events

The response is a server sent event stream.

Event	Carries	Do
`started`	`sessionId`, `runId`	Store both
`text-delta`	`delta`	Append to the visible answer
`input-requested`	`requestId`, `input`	Show a prompt and wait for the human
`completed`	`output`	Render the final result
`failed`	`code`, `message`	Show the error, link to the trace
`cancelled`		Mark the run stopped

Every event carries an index. Reconnect with a start index to resume without replaying the whole stream.

3. Answer an input request

{
  "inputResponses": [
    { "requestId": "req_123", "optionId": "approve" }
  ]
}

Or with free text:

{
  "inputResponses": [
    { "requestId": "req_123", "text": "Use the January figures." }
  ]
}

A paused turn is durable. It survives a disconnect and stays paused until someone answers.

4. Cancel

{ "turnId": "turn_456" }

Sessions and continuity

Omit the session id on the first send and a session is created for you. Reuse it to continue the conversation.
Sessions are private to the person who created them.
Re open a session at any time and read its history from the stream.

Idempotency

Every run start carries an idempotency key. Send the same key twice and you get the same run back, not a duplicate. A network retry is therefore always safe.

What the runtime enforces for you

You do not implement any of this. It happens on every run:

Access to the agent is re checked, live.
The effective configuration is resolved and frozen onto the run.
The input guardrail is applied and memory is retrieved.
The turn executes, calling models, tools and knowledge bases.
The output guardrail is applied.
Memory is written and every step is projected into the trace.

Errors

Status	Meaning
`401`	Missing or invalid credential
`403`	No access to this agent
`404`	Agent or session not found, or not reachable by you
`409`	A turn is already active on this session
`429`	Rate limited

A run blocked by a guardrail is not an HTTP error. It arrives as a failed event carrying the guardrail code, so your UI can present it as a policy message rather than a crash.

Embedding checklist

Authenticate server side and never expose an API key to the browser
Keep the session id so conversations continue
Handle input-requested, or human in the loop agents will appear to hang
Handle failed distinctly from a network failure
Offer a cancel control
Track the event index so a reconnect resumes cleanly
Link support staff to the run's trace for diagnosis