Sandbox Sessions

Operations of the Interactive Session API. Paths are relative to your deployment's API host.

POST /api/agent-session-api/sessions/sandbox

Create an ephemeral Agent Studio sandbox session bound to a DRAFT composition. The session is throwaway, lifecycle-bounded by a TTL, and isolated from every project side-effect (no artifact emit, no deliverable harvest, no KB push, no git, no snapshot persistence). When toolMocks is supplied the per-tool canned responses are registered with the mcp-gateway test-mode mock bridge as part of create.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateSandboxSessionDto

DELETE /api/agent-session-api/sessions/sandbox/{id}

Dispose a sandbox session — release its worker and drive it terminal. Idempotent. Requires management of this session: its owner, or an admin of the organization that owns it (org-owned sessions only). Invited participants and editors may not.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/sandbox/{id}/debug

Debug / decision-trace view of a (sandbox) session: the resolved composition tree (sub-agent tree + per-node model), the Model Resolution Matrix decision trace for the primary agent, skill activation, the injected-context view, and the projected mount plan. Valid for any session; built for the Studio sandbox harness.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/sandbox/{id}/eval-turn

Drive ONE agent turn on a sandbox session to completion SYNCHRONOUSLY and return the captured assistant output + token/wall-clock timing. Unlike the SSE chat endpoint this blocks until the turn reaches its terminal state — built for the skill-registry-api eval harness, which is a service-to-service caller and cannot consume an event stream. Requires an Idempotency-Key header: it is the per-turn lock id, so a retried eval turn never double-drives the agent.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RunSandboxEvalTurnDto

GET /api/agent-session-api/sessions/sandbox/{id}/tool-mocks

List the canonical tool names a sandbox session currently has canned mock responses registered for.

Authentication: bearer token (Authorization: Bearer <token>)

PUT /api/agent-session-api/sessions/sandbox/{id}/tool-mocks

Register (replace) the full set of per-tool canned mock responses for a sandbox session. When the sandbox runs with mocked tools, the mcp-gateway bridge serves these canned results instead of invoking live MCP services. Authorized as the sandbox owner; forwarded to mcp-gateway-api service-to-service.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json SetSandboxToolMocksDto

DELETE /api/agent-session-api/sessions/sandbox/{id}/tool-mocks

Delete one mocked tool from a sandbox session, or every mock for the session when the toolName query parameter is omitted.

Authentication: bearer token (Authorization: Bearer <token>)