Agent Session Management#

Agent session management is a cross-cutting feature area in Phoenix (PXI) covering the persistence, REST API, GraphQL API, web UI picker, and CLI integration for agent chat sessions. The core goal is that conversations survive backend restarts, work across multiple Phoenix replicas, and remain consistent across all client surfaces — web UI, pxi CLI, and Slack 1.

All engineering work is tracked under the 🗺️ agent session persistence epic (#14206), which had 24 of 25 engineering items complete as of 2026-07-31 1.

Important distinction: Agent sessions use ownership-based SQL scoping — not the project-level session filter DSL. These are two separate, non-overlapping surfaces 2.

Session Persistence and Data Model#

Sessions are stored with a temporary flag distinguishing short-lived chats from persisted ones. Key session fields include: title, created_at, updated_at, user, first_input, latest_output, and messages.

The session lifecycle encompasses creation, compaction (#14583), expiry, and the distinction between temporary and persisted states. REST endpoints only return non-temporary, non-expired sessions 2.

The AgentSession GraphQL type is defined in src/phoenix/server/api/types/AgentSession.py, with every field gated by the CanAccessAgentSession permission class 2.

REST API#

All agent session REST routes live in src/phoenix/server/api/routers/agents.py 2:

Authorization behavior 2:

• Auth enabled: list/get queries are scoped to user_id == <request user>; another user's session returns 404
• Auth disabled: all persisted sessions for the agent are returned
• Viewers receive 403; missing sessions return 404
• _get_request_user_id(request) extracts the authenticated user ID or returns None

OpenAPI schemas (in schemas/openapi.json) 3: AgentSessionSummary, AgentSessionData, ListAgentSessionsResponseBody, GetAgentSessionResponseBody. Generated typed bindings are kept in sync across app/src/api/__generated__/v1.ts, js/packages/phoenix-client/src/__generated__/api/v1.ts, and the Python client.

POST /agents/{agent_id}/sessions was introduced in PR #14581 4; GET routes were added in PR #14711 3.

GraphQL API and Authorization#

Authorization is enforced via the CanAccessAgentSession Strawberry permission class in src/phoenix/server/api/agent_helpers.py 2:

• Non-admin: access denied if owner_id != viewer_id
• Admin: unrestricted access
• get_agent_session_owner_filter() returns a SQL WHERE user_id == viewer_id predicate for non-admins, or None for admins

The agentSessions query supports a viewerOnly: Boolean! = false argument (added in PR #14898), which restricts results to the viewer's own sessions regardless of role 5. This is resolved in src/phoenix/server/api/queries.py.

Web UI Session Picker#

The web UI surfaces agent sessions in two places with different scoping:

PR #14898 fixed the chat picker to pass viewerOnly: true so admins no longer see every user's session in their own picker 5.

SessionListMenu.tsx uses a store-and-network fetch strategy — it loads instantly from the Relay store cache, then refetches in the background when the menu opens, so sessions created in other tabs appear without a stale view (PR #14857) 6.

Additional UX fixes in PR #14857: the thinking indicator now appears immediately on first send and persists until content streams; the chat empty state is suppressed during background polling 6.

CLI Session Management (pxi)#

The pxi terminal UI in js/packages/phoenix-cli/src/pxi/ 7 supports full session lifecycle management via slash commands:

Tab completion is available for all slash commands 3.

client.ts (js/packages/phoenix-cli/src/pxi/client.ts) 7:

• Builds persisted route URLs via buildAgentChatUrl({ endpoint })
• Implements a legacy fallback: if the persisted endpoint returns 404/405, retries against the legacy URL (for compatibility with older Phoenix versions)
• Parses session metadata from data-session-created and data-session-summary stream chunks to capture session identity and update titles

Session picker UX (PR #14857): The /sessions picker loads instantly with cached data and refreshes in the background, preserving filter queries and selections 6.

PR history:

• PR #14581 — established the stateful POST /agents/{agent_id}/sessions route foundation 4
• PR #14469 — migrated PXI CLI to use persisted sessions with legacy fallback 8
• PR #14711 — added /sessions picker and wired GET REST routes 3
• PR #14857 — improved picker responsiveness and cache behavior 6

Known Issues and Ongoing Work#

As of 2026-07-31, the following work remains open under the #14206 epic 1:

• CLI session picker pagination (#14951): listSessions hardcodes limit: 20 and discards the next_cursor token, so users with more than 20 sessions cannot see older ones.
• Engineering: 1 item pending (#14817) 1
• Dogfooding feedback: ~9 items pending (#14880–#14895 range) 1
• Review findings (7-31): 6 open items (#14948–#14953) 1
• Stretch: #14885 1
• Post-merge: #14623 1
• Punted: #14451 1

Key Source Files#