# Core concepts

> Learn how Pantheon objects fit together.

## Agent

An agent stores instructions, a model, tool requirements, and `requires_sandbox`.

Its `tools` list is an allowlist over exactly four built-in tools and it is enforced: `web_search`, `web_fetch`, `publish_artifact` and `list_session_artifacts`. One of those that the agent does not declare is never attached, and a call to it is refused before it runs and recorded as `tool.refused`.

Read the next sentence before you rely on that list to lock an agent down. It does not govern the sandbox. While `requires_sandbox` is true the agent also has a shell, `execute`, and the file tools, and the sandbox can reach the network. So an agent that declares no web tools can still fetch a URL from the shell. Set `requires_sandbox` to `false` to remove the shell, the file tools and that network path together.

The frozen agent revision a deployment pins is what governs a run, so editing an agent never changes what a running deployment may do.

Agents created before enforcement report `tool_policy` as `unrestricted` and still receive every built-in tool. Writing `tools` on one governs it from that revision onward.

Updating an agent creates a new version. Existing sessions do not change.

## Tool

A tool has a stable identity and immutable definition versions.

An application tool runs in your application. Its definition declares JSON input and output schemas.

## Deployment

A deployment pins one agent version and its tool definitions.

A session created by agent slug uses the active deployment. Without one, it uses the newest published deployment.

It uses a legacy deployment snapshot only as a fallback.

## Session

A session keeps conversation state and the deployment snapshot chosen at creation.

`deployment_snapshot_id` identifies the pinned deployment snapshot.

| deployment_source | Meaning                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `published`       | The slug selected the active deployment, or the newest published deployment when none is active. |
| `legacy`          | Pantheon used a legacy deployment snapshot.                                                      |

### Sandbox status

| Value     | Meaning                                    |
| --------- | ------------------------------------------ |
| `ready`   | The sandbox is available.                  |
| `stopped` | The sandbox exists but is stopped.         |
| `missing` | The recorded sandbox no longer exists.     |
| `none`    | This session does not require a sandbox.   |
| `unknown` | Pantheon could not determine availability. |

## Run

A run processes one turn in a session.

| Value               | Meaning                                   |
| ------------------- | ----------------------------------------- |
| `queued`            | The run is waiting for a worker.          |
| `running`           | The agent is processing the turn.         |
| `waiting_for_input` | The run needs an application tool result. |
| `completed`         | The run finished successfully.            |
| `failed`            | The run stopped with an error.            |
| `cancelled`         | A client cancelled the run.               |
| `expired`           | The run passed its wait deadline.         |

Only one run can be active. A second run returns `SESSION_BUSY`.

## Event

Durable events have an SSE id and sequence. Pantheon stores and replays them.

Ephemeral deltas have no SSE id. Pantheon does not replay them.

Event `content` is a block list or JSON object.

## Application tool

### Receive the call

Wait for `agent.custom_tool_use`.

### Execute the tool

Validate input, ask for approval when needed, then run the application tool.

### Resume the run

Send the result with the event id and a stable idempotency key.

## List responses

Every list endpoint returns an object. Read results from `data`, then follow its pagination field.

Cursor-based lists return this shape:

```json title="JSON"
{"data": [], "next_cursor": null}
```

Page-based lists return this shape:

```json title="JSON"
{"data": [], "next_page": null}
```

These examples show empty final pages. A `null` pagination value means there are no more results.

## Memory

An agent keeps notes separate from the conversation transcript and carries them into later turns.

They do not yet carry into later sessions: on the hosted runtime they live with the session sandbox. Durable cross-session memory is wired but not switched on.

Those notes belong to one end user. A session created with `user_id` will share them across that person's sessions. A session created without one keeps them inside that single session, so nothing an agent learns from one visitor can reach another.

There is no workspace-wide memory. See [Agent memory](https://pantheon-todo.alethiconsulting.com/docs/sessions-and-runs#memory) for what is stored, how long it lives, and how to erase it.

## Sandbox

Set `requires_sandbox` to `false` when every tool runs in your application.

If Pantheon replaces a missing sandbox, it emits `sandbox.recreated`. Unpublished files from the old workspace are lost.

## Pitfalls

> **Warning**
>
> - **Agent edits do not update existing sessions:** Create a new deployment and a new session.
> - **A waiting tool blocks the session:** Resume or cancel its run before starting another.
> - **MCP configuration does not run:** Pantheon stores MCP configuration but does not dispatch it. Use an application tool.
> - **Memory does not survive a session yet:** Agent memory lives with the session sandbox. Durable cross-session memory is not switched on.