Sessions and runs

Sessions​

Create a session with agent_slug or deployment_id.

The session stays pinned to its selected deployment snapshot.

Pass user_id when you know which of your end users is on the other end. It decides whose agent memory the conversation reads, so read Agent memory before you leave it out.

Sandbox status​

Runs​

From this release, run_id is 32 hex characters in responses and stream events alike.

Start one run at a time. Stream until the run becomes terminal or waits for input.

Record integrity​

The record_integrity field describes whether the run's history was recorded, separately from its status.

Get one run​

Send GET to /v1/sessions/{session_id}/runs/{run_id} to read a run without streaming. Requires sessions:read and runs:read.

curl -sS "$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/runs/$RUN_ID" -H "Authorization: Bearer $PANTHEON_API_KEY"

The response contains id, session_id, status, record_integrity, model_used, usage, error, created_at and completed_at, using the same shape as cancel. Nullable fields are returned as null when unavailable.

Use the run_id returned by create or wait. Both compact and hyphenated UUIDs are accepted; the response id is compact. Missing sessions, missing runs and resources in another workspace return HTTP 404.

Recover from SESSION_BUSY​

A second run returns HTTP 409 with SESSION_BUSY.

{
  "error": {
    "code": "SESSION_BUSY",
    "message": "Session 'session_123' has an active run '0123456789abcdef0123456789abcdef' in status 'waiting_for_input'.",
    "request_id": "request_123",
    "active_run_id": "0123456789abcdef0123456789abcdef",
    "active_run_status": "waiting_for_input",
    "recovery": [
      "cancel the active run via POST /v1/sessions/session_123/runs/0123456789abcdef0123456789abcdef/cancel",
      "or resume it via POST /v1/sessions/session_123/runs/0123456789abcdef0123456789abcdef/resume"
    ]
  }
}

Resume the active run when it waits for a tool. Otherwise wait or cancel it.

curl -sS -X POST \
  "$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/runs/$ACTIVE_RUN_ID/cancel" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

Agent memory​

An agent has a small store of notes, separate from the conversation transcript. It is a folder at /memories/ that the model can read and edit with its own file tools, seeded with a template that asks it to keep preferences such as a preferred name, language, tone or time zone, and the task in progress.

How it is scoped​

Memory belongs to one end user. Which one depends on how the session was created.

A session created without user_id gets a memory of its own, not a shared one. Two of your end users can never read each other's notes, and an unidentified visitor cannot read an identified user's notes. The cost of that default is that memory does not carry from one of that visitor's conversations to the next. Send user_id at session creation and it will, once durable memory is switched on.

Memory never crosses a workspace.

What is stored and for how long​

Whatever the agent chose to write, as text, in PostgreSQL on Alethi infrastructure. It is not an encrypted or hidden store: your workspace can read its shape through the routes below, and Alethi operators can access it for support like any other stored data. Today the durable store holds only the seeded template for each scope, because agents write to the session sandbox instead.

There is no expiry. Memory lives until you delete it, until the session or the end user it belongs to is deleted, or until the workspace is deleted. Tell your end users what your agent remembers about them, and instruct your agent through its system prompt if you want it to keep less.

A long conversation does not thin memory out. Pantheon compacts a conversation that grows past its token threshold, replacing older turns with a summary, but memory is not part of that history: it is re-sent in full on every model call. A fact the agent wrote down is still in front of the model after a compaction, even when the exchange that produced it is no longer in the transcript. Erasing is the way to remove it.

An agent's declared tools list does not govern memory. It governs the built-in tools named in Core concepts; memory is read and written with the agent harness file tools, alongside the sandbox, and follows requires_sandbox. An agent that declares no tools still keeps notes.

See what an agent holds​

Send GET to /v1/users/{user_id}/memory for one end user, or /v1/sessions/{session_id}/memory for one conversation. The response reports the scope, whether anything is stored, and the path, size and timestamps of each entry. It does not return the stored text.

curl -sS "$PANTHEON_BASE_URL/v1/users/$USER_ID/memory" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

The session route reports the memory that session actually reads. For a session bound to a user_id that is the user's memory, and the response says so.

Erase it​

Send DELETE to the same path. The entries are removed, not hidden, and the count of removed entries comes back. The next session in that scope starts from the stock template with nothing learned about the person.

curl -sS -X DELETE "$PANTHEON_BASE_URL/v1/users/$USER_ID/memory" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

Deleting a session erases that session's memory. Deleting an end user erases theirs. Neither touches the other scope.

Every erase that removed something is recorded in your audit log as memory.erased, whichever of the three routes reached it. The record names the scope and how many entries went, never what they said.

Archive a session​

Archive finished sessions. Pantheon then destroys the attached sandbox.

curl -sS -X POST "$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/archive" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

Publish updates​

Roll back a deployment​

Send POST to /v1/deployments/{id}/activate with the earlier published deployment id.

This makes that deployment active for new sessions created by agent slug. Existing pinned sessions stay unchanged.

Only published deployments can be activated. Legacy snapshots return HTTP 409.

An active deployment takes precedence over newer publications until you activate another deployment.

Use agent_id to filter GET /v1/deployments.

Each returned deployment includes an active boolean. Activation returns the deployment with this flag set to true.

Pitfalls​