Agent
An agent stores instructions, a model, tool requirements, and requires_sandbox.
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.
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
- 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.