Core concepts

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.

Sandbox status​

Run​

A run processes one turn in a session.

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​

List responses​

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

Cursor-based lists return this shape:

{"data": [], "next_cursor": null}

Page-based lists return this shape:

{"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 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​