Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt

Use this file to discover all available pages before exploring further.

A session is a single, isolated execution of an agent. When you create a session, the platform boots a Kubernetes sandbox pod, clones the agent’s configured repository, injects environment variables, and starts the harness process. The session lives until it is explicitly deleted or until it has been idle for 24 hours, at which point the reconciler reaps it automatically.

​
Session lifecycle

Every session moves through a status field that reflects its coarse state.
1

creating

The platform has accepted the request and is provisioning the sandbox pod. This state covers everything from pod scheduling through harness startup.
2

ready

The harness is running and accepting work. For API harnesses, you can send messages via POST /sessions/{id}/message. For TUI harnesses, you can attach a terminal via lap or the browser.
3

dead

The session ended cleanly — either you deleted it, or the idle timeout elapsed and the reconciler reaped it.
4

failed

The session could not reach the ready state. The failure_reason field explains why. Common causes include image pull errors, pod scheduling failures, and harness startup crashes.

​
Bring-up phases

While a session’s status is creating, the phase field gives you fine-grained visibility into exactly where in the startup sequence it is. The platform owns the first six phases; the harness inside the sandbox reports the last three.
PhaseOwnerWhat is happening
creating_sandboxPlatformSandbox CR is being submitted to Kubernetes.
pod_pendingPlatformPod is scheduled but containers have not started yet.
pod_runningPlatformAll containers are running; waiting for the harness HTTP endpoint to respond.
injecting_filesPlatformSandbox files from the agent configuration are being written into the container.
waiting_harnessPlatformHTTP health probe is polling the harness until it accepts connections.
harness_readyPlatformHarness HTTP endpoint responded; the platform can now create the harness session.
cloning_repoHarnessHarness is running git clone for the configured repo_url.
installing_depsHarnessHarness is installing packages from AGENT_REQUIREMENTS.
harness_listeningHarnessHarness process is fully initialized and ready to accept the first message.
ready—Session status flips to ready.
The phase_detail field carries an optional human-readable subtitle for the current phase. The web UI renders it below the active step in the spawn-progress card.

​
Session fields

The API returns sessions as ApiSession objects.
FieldTypeDescription
idstringUnique session identifier.
agent_idstringThe agent this session belongs to.
statusstringCoarse lifecycle state: creating, ready, dead, or failed.
phasestring | nullFine-grained bring-up phase (see table above). null on sessions created before the phase column existed.
phase_detailstring | nullOptional subtitle for the current phase.
sandbox_urlstring | nullCluster-internal HTTP URL for the harness. null until the pod is running.
tty_urlstring | nullBrowser-accessible WebSocket base URL for TUI harnesses. null for API harnesses and during startup.
tty_tokenstring | nullBearer token for the harness /tty WebSocket. Passed as ?token=… by lap and the browser terminal.
responseobject | nullLatest harness reply blob. Populated after the first message.
last_seen_atstring | nullISO 8601 timestamp of the last POST /message. null until the first message.
idle_timeout_msnumberMilliseconds of inactivity after which the reconciler reaps a ready session. Currently 86,400,000 ms (24 hours).
failure_reasonstring | nullHuman-readable reason why status flipped to failed.
created_atstringISO 8601 creation timestamp.

​
Creating a session

curl -s https://your-lap-instance/api/v1/managed_agents/agents/$AGENT_ID/session \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "fix issue #1234",
    "initial_prompt": "Reproduce the bug described in issue #1234 and write a failing test."
  }'
initial_prompt is optional. Omit it to bring up the sandbox without sending any message — useful when you want to attach a TUI terminal and drive the agent interactively.

​
Per-session env vars

Pass env_vars when creating a session to inject short-lived secrets into the sandbox at launch time. These are forwarded directly into the container environment and are never persisted to the database and never logged by value. 
curl -s https://your-lap-instance/api/v1/managed_agents/agents/$AGENT_ID/session \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "open a PR",
    "env_vars": {
      "GITHUB_TOKEN": "ghp_...",
      "CIRCLECI_TOKEN": "cci_..."
    }
  }'

​
Constraints

All of the following are enforced at POST /session time. Any violation returns 400.
  • Maximum 50 keys.
  • Total JSON-encoded size ≤ 16 KB.
  • Key names must match ^[A-Za-z_][A-Za-z0-9_]*$.
  • Keys cannot overlap the reserved set.
Per-session values take precedence over agent-level env_vars when the same key appears in both.
GIT_TOKEN is reserved — the entrypoint erases it after git clone so the agent cannot read it back. To pass a token that survives into the agent shell (for gh pr create, git push, etc.), use GITHUB_TOKEN or GH_TOKEN instead.

​
Idle timeout and session reaping

A ready session that receives no POST /message traffic for 24 hours is automatically stopped by the background reconciler. The session status flips to dead and the sandbox pod is deleted. The idle_timeout_ms field in the session response carries the exact threshold so the UI can show an accurate countdown. The countdown resets on every POST /message. Press Ctrl-D in the lap CLI to detach from a TUI session without stopping it. The session stays alive and you can reconnect by running lap <agent-name> again.