> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-roger-ci-skip-release-prs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# PXI
> PXI (Phoenix Intelligence) is the AI engineering agent built into Phoenix. Hand it an investigation instead of digging through traces, prompts, evaluations, and experiments yourself. It understands the context you are already looking at.
PXI is in **beta**. It can and will make mistakes, and it should be used with
care — especially on production data. Agent assistance is **opt-in and
controllable**: see [You stay in control](#you-stay-in-control).
**PXI** (pronounced *"pixie"*, short for **Phoenix Intelligence**) is an AI
engineering agent built into Phoenix. Instead of manually digging through traces,
prompts, evaluations, and experiments, you hand the investigation to an agent that
already understands the context you are looking at — the trace you opened, the
prompt you are editing, the filters you applied.
Think of it as a coding agent, but pointed at your observability data instead of a
codebase. It inspects traces, investigates failures, iterates on prompts, runs
experiments, authors evaluators, annotates spans, and navigates Phoenix for you.
## Get started
PXI needs a model to talk to. Set credentials for at least one provider
(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, AWS Bedrock
credentials, or a custom provider under **Settings → Models**). See
[Setup](#setup) for the validated model list.
Open the assistant from any Phoenix page — click the assistant button or
press ⌘I (Ctrl+I on Windows and Linux). The first time,
you review the session-trace settings and acknowledge to enable the chat
surface for your browser.
From a failing trace, try *"why did this fail?"* From the prompt playground,
try *"make this prompt more robust to empty input."* PXI uses the page you
are on as context. No need to paste IDs or copy data.
## Conversations
Your chats with PXI are saved on the Phoenix server, not in the browser tab. A
conversation survives a reload, follows you to another browser, and is the same
session whether you opened it in the in-browser panel or the `pxi` terminal
client. The chat panel keeps a session list in its header: pick a past chat to
continue it, rename one (Phoenix seeds a title from the opening turn), or delete
the ones you no longer need. Older sessions load as you scroll.
Temporary chats are the exception. A chat you mark temporary is never written to
your history and carries an ephemerality badge. Toggle it per chat before you
send the first message, or make it the default under **Settings → Assistant →
Personal settings → Start new chats as temporary**.
**Rewind and branch.** Every message carries a control to change course from that
point:
* **Rewind** drops the message and everything after it. On one of your own
messages the text drops back into the input so you can edit and re-send it; on
a response the chat reverts to that answer and discards what came after.
* **Branch** forks a new chat from that point and leaves the current one
untouched — a way to try an alternative without losing the thread you came
from.
Persisted chats are subject to retention limits an administrator sets under
**Settings → Assistant**, and temporary chats are swept after a day of
inactivity. See [agent session retention](/docs/phoenix/settings/data-retention#agent-session-retention)
for the defaults and how to change them.
### Over the API
The same sessions are exposed as REST routes under `/v1/agent_sessions` — create,
list, get, patch, compact, chat, submit tool outputs, and fetch messages — the
endpoints the browser panel and the terminal client both use. See the
[Agent Sessions API reference](/docs/phoenix/sdk-api-reference/rest-api/api-reference/agent-sessions/list-sessions).
The TypeScript client `@arizeai/phoenix-client` exports an `AGENT_SESSION_*`
capability requirement for each route so a program can check server support
before calling.
**Rewind, branch, and delete are GraphQL-only.** The REST routes cover create,
chat, and compaction, but the operations behind the rewind and branch controls
above have no `/v1/agent_sessions` equivalent. The browser panel performs them
through the `truncateAgentSession` (rewind), `branchAgentSession` (branch), and
`deleteAgentSession` mutations on the Phoenix GraphQL API. A client that needs to
reproduce that UX has to call GraphQL.
One turn runs against a session at a time. A streaming turn holds a lock that it
refreshes with a periodic heartbeat; a lock whose heartbeat goes stale (roughly a
minute without a refresh) can be reclaimed by the next turn. A request that
collides with another client comes back as `409 Conflict` with a code that says
what to do:
| `409` conflict code | Meaning |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `agent_session_busy` | Another turn holds the session's lock. Wait for it to finish, or retry once its heartbeat goes stale. |
| `agent_session_messages_stale` | Another client appended to the transcript. Refetch the messages and retry. |
| `agent_session_model_stale` | The session's model was switched. Refetch the session and retry. |
| `agent_session_tool_outputs_conflict` | The submitted tool outputs don't match the pending tool calls — fix the request rather than retry. |
| `agent_session_compaction_conflict` | The conversation changed mid-compaction. Retry. |
| `agent_session_already_compact` | Nothing left to compact. Not retryable. |
## Use PXI from the terminal
PXI is also available as an interactive terminal chat, shipped with the
[Phoenix CLI](/docs/phoenix/tracing/how-to-tracing/importing-and-exporting-traces/retrieve-traces-via-cli)
(`@arizeai/phoenix-cli`). It is the same server-side agent that powers the
in-browser experience. The CLI connects to a running Phoenix instance, so model
credentials, skills, and permissions are configured on the server exactly as
described under [Setup](#setup).
Run it without installing:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx -y @arizeai/phoenix-cli pxi
```
Or install the CLI globally and use the `pxi` command directly:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install -g @arizeai/phoenix-cli
pxi
```
Point it at your Phoenix instance with the `PHOENIX_ENDPOINT` (and `PHOENIX_API_KEY`
if your deployment requires auth) environment variables, or pass `--endpoint` /
`--api-key` flags:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export PHOENIX_ENDPOINT=http://localhost:6006
pxi
```
Pick the model with `--provider` and `--model` (defaults to Anthropic
`claude-opus-5`):
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
pxi --endpoint http://localhost:6006 --provider OPENAI --model gpt-5.4
```
The terminal client talks to the same `/v1/agent_sessions` endpoints as the
browser agent (sending `headless: true` on its chat turns), so it
requires a running Phoenix server with a configured model provider.
On launch it runs a preflight check against the server's model catalog and
credentials, surfacing configuration problems as a clean error before the chat
opens. It also requires a Phoenix server on **20.0.0 or newer** — the release
that introduced persisted agent sessions — and exits at startup with an upgrade
message when the connected server is older, rather than failing on the first
send.
| Flag | Effect |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--endpoint ` | Phoenix endpoint URL (overrides `PHOENIX_ENDPOINT`). |
| `--api-key ` | Phoenix API key (overrides `PHOENIX_API_KEY`). |
| `--profile ` | Use a saved Phoenix CLI profile. |
| `--provider ` | Built-in model provider (e.g. `ANTHROPIC`, `OPENAI`, `GOOGLE`). |
| `--model ` | Model name (defaults to `claude-opus-5`). |
| `--custom-provider-id ` | Use a custom provider configured under **Settings → Models** (requires `--model`). |
| `--bypass-edits` | Apply edits without manual approval (see [You stay in control](#you-stay-in-control)). |
| `--enable-web-access` | Allow PXI to consult the web for grounding. |
| `--enable-subagents` | Allow the server to attach subagents (including the server-side bash tool). |
| `--enable-graphql-mutations` | Allow PXI to run state-changing GraphQL mutations. |
| `--ingest-traces` | Persist this session's PXI traces locally in Phoenix. |
| `--export-remote-traces` | Export this session's PXI traces to a configured remote collector. |
| `--attach-user-id` | Attach the authenticated Phoenix user to PXI traces (opt-in; see the **Privacy, safety & configuration** section below). |
| `--skip-model-preflight` | Skip the model catalog and credential checks before launch. |
Each capability flag is still subject to the server's own settings — for
example, `--enable-subagents` has no effect when
`PHOENIX_AGENTS_DISABLE_BASH=true`, and `--export-remote-traces` requires a
configured collector and an administrator who has allowed export.
## Slash commands
Inside the terminal chat, lines beginning with `/` are handled locally by the
client and never sent to the model.
| Command | Effect |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/help` | List the available slash commands. |
| `/clear` | Clear the conversation history and start a fresh session (alias for `/new`). |
| `/new` | Start a new persisted session. |
| `/temporary` | Start a new temporary session. |
| `/sessions` | Browse and restore persisted sessions. |
| `/model` | Switch models for this session. |
| `/compact` | Compact older conversation context into a checkpoint summary. Text after the command (e.g. `/compact keep going`) is sent as a follow-up message once compaction finishes. |
| `/exit` | Exit the terminal client. |
`/compact` asks the model to summarize every completed turn into a durable
checkpoint; later turns load history from the checkpoint onward, freeing
context for long-running sessions. Compaction is rejected while the session is
in use elsewhere (for example, a turn streaming in the browser). The chat
shows the busy indicator and refreshes when the other turn completes.
## Status line
While a turn streams, the terminal client shows a live **thinking indicator**,
and once the response settles a bottom-right **context-usage line** reports the
size of the context PXI is currently carrying — the tokens retained after the
latest response, not a running total for the turn — preceded by a cache-activity
summary when the provider reports cache reads or writes. The active model name
sits next to the input prompt so you always know which provider and model the
session is talking to.
In the browser the same usage appears under the chat as a compact total you can
expand into a prompt-versus-completion breakdown. When the provider caches part
of the prompt, the prompt figure splits further into uncached, cache-read, and
cache-write tokens.
## What it does
* **Drives the product** — navigates, filters, and pivots through your Phoenix
data the same way you would.
* **Investigates failures** — walks failing traces and proposes root causes
instead of leaving you to grep through spans.
* **Iterates on prompts** — reads, edits, and tests playground prompts, with
every change shown as a diff you approve.
* **Reasons over your data** — a sandboxed runtime lets PXI query your Phoenix
instance to answer questions evals and dashboards cannot.
* **Knows the product** — Phoenix's own documentation is wired in as a
first-class source, so answers are grounded rather than guessed.
PXI is **context-aware**: it has access to the history already in Phoenix —
prompt versions, experiment results, datasets, evaluations, annotations, and
trace data — and its capabilities adapt to the page you are on. What it can do on
a trace differs from what it can do in the prompt playground.
## Skills
A **skill** is a reusable, multi-step procedure for one Phoenix workflow — what to
look at, in what order, and what the output should be. PXI loads the matching
skill on demand rather than improvising each investigation from scratch.
The library is under active development and grows each release. Track progress on
the [Phoenix roadmap milestone](https://github.com/Arize-ai/phoenix/milestone/13).
Walk failing traces against a failure-mode checklist and return prioritized
root-cause hypotheses.
Open-code spans with working notes, then group them into failure categories
and promote the stable ones into structured annotations — a way to build a
taxonomy before one exists.
Annotate spans and apply labels in bulk across a trace or project, and draft
the annotation config itself — categorical, continuous, or freeform. Config
writes are shown for approval before they replace anything.
Co-author and optimize prompts, with every edit shown as a diff to approve.
Draft and refine LLM-as-a-judge and code evaluators against your data.
Turn the failures you find into curated datasets, splits, and labels for
experiments and evals.
Run and read experiments over a dataset to compare prompt or model changes.
Query the Phoenix API with GraphQL for custom analysis, or get working queries
for your own scripts — built on schema patterns that skip introspection.
Because skills are context-aware, PXI surfaces the right one for the page and
task you are on.
## You stay in control
Agent assistance is opt-in. PXI can be turned off completely, runs under an
explicit permission model, and only reaches the internet when you let it.
* **Turn it fully off.** Disable PXI per deployment
(`PHOENIX_DISABLE_AGENT_ASSISTANT=true`), per instance
(**Settings → Assistant → System settings**), or per browser
(**Settings → Assistant → Personal settings → Use assistant**).
* **State-changing actions are gated by approval.** Saving a prompt, creating or
replacing an annotation config, writing dataset examples, submitting an
evaluator — each is proposed as a reviewable diff or card and applied only when
you accept, under an edit-approval mode you pick from the chat input (or cycle
with `Ctrl+T`). Read-only actions run freely. There is one deliberate
exception: while open-coding spans, PXI writes its working notes straight to
the span (a single note tagged `pxi`, updated in place) without a prompt, so it
can iterate without asking on every observation — see the span-coding skill
under [Skills](#skills).
* **Add web grounding when you want it.** Toggle **web access** with the globe
button in the chat input to let PXI consult the live internet for additional
grounding. The toggle is per session and only appears when an administrator
allows it; leave it off to keep the session entirely inside your Phoenix
instance.
* **Choose where it lives.** Keep the assistant pinned to the top navigation bar
or switch it to a draggable floating button under **Settings → Assistant →
Personal settings → Floating assistant button**.
| Edit-approval mode | Behavior |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Manual Approval** *(default)* | PXI proposes the change as a reviewable diff and waits. Nothing is applied until you click **Accept**. |
| **Bypass Approval** | Edits are applied without asking. The selector shows a warning treatment while active. |
## Setup
Configure credentials for at least one provider via environment variables or
Phoenix secrets (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, AWS
Bedrock credentials, or a custom provider under **Settings → Models**). The
consent gate shown the first time you open PXI enables the chat surface for that
browser; it does not override system settings.
PXI relies heavily on **tool calling** — almost every action it takes is a tool
call. Models that are weak at tool use produce broken sessions even if they
handle free-form chat well. Pick one of these validated models unless you have a
specific reason not to:
* **Anthropic** — `claude-opus-5`, `claude-opus-4-8`, `claude-opus-4-6`, `claude-sonnet-4-6`
* **OpenAI** — `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`
* **Google** — `gemini-3.7-flash`, `gemini-3.1-pro-preview`
Other built-in or custom-provider models can be selected from the model menu,
but they are untested with PXI and may fail to invoke tools correctly.
## How it works
PXI is split between the Phoenix server, which owns everything the model sees
(tool definitions, system prompt, skills, capability guidance), and the browser,
which executes tool calls that touch the page. Capabilities are gated by
**context** — PXI only advertises a tool when the required Phoenix UI context is
present, so it does not offer an action that cannot succeed on your current page.
```mermaid theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
flowchart LR
User((User))
subgraph Browser["Browser"]
direction TB
ChatUI["Chat UI"]
PageTools["Page tool calls (filters, nav, playground)"]
ChatUI ~~~ PageTools
end
subgraph Server["Phoenix Server"]
direction TB
Agent["PXI Agent"]
Tools["Tools"]
Skills["Skills"]
Bash["bash virtual shell"]
GraphQL["GraphQL API"]
MCP["MCP client"]
Agent --> Tools
Agent --> Skills
Agent --> Bash
Bash --> GraphQL
Agent --> MCP
end
LLM["LLM Provider"]
Docs["Mintlify Docs MCP"]
User <--> ChatUI
ChatUI <--> Agent
Agent -->|page actions| PageTools
Agent <--> LLM
MCP --> Docs
```
The server hosts the agent and everything the model sees — its **tools**,
**skills**, an **MCP** client, and a sandboxed **bash** shell. Bash runs in an
in-process virtual shell on the server with networking disabled; inside it the
**phoenix-gql** builtin queries the Phoenix **GraphQL API** directly — the same
schema a logged-in user hits. The browser owns the chat UI and runs the tool
calls that touch the page you are on: applying filters, navigating, and driving
the playground. The server calls your LLM provider with your API key and, when
external resources are allowed, reaches the Mintlify-hosted Phoenix docs MCP.
PXI runs **inside the Phoenix process you are already running**:
* Tool calls execute against your Phoenix server and your data — no separate
Arize service is involved.
* The LLM is **your model provider**, called with **your API key**. Arize is
not in the request path.
* Documentation lookups go to the **Mintlify-hosted Phoenix docs MCP server**
when external resources are allowed — the same public docs you can read in a
browser, serving docs only.
* Remote trace export happens **only if every gate is enabled**: a remote
collector is configured, an administrator allows export in system settings,
and the user enables it in personal settings.
## Privacy, safety & configuration
PXI can capture conversations as Phoenix traces, controlled by both system
settings and per-browser preferences. From **Settings → Assistant**,
administrators can turn assistant access on or off for everyone, allow users to
save session traces locally, and allow export to a configured remote collector;
each user can show or hide the assistant and opt into local or remote trace
recording when allowed.
By default the system settings allow **neither** local persistence nor remote
export. Local traces are written to the `assistant_agent` project (override
with `PHOENIX_AGENTS_ASSISTANT_PROJECT_NAME`). When recording is enabled, tool
inputs and outputs are recorded on the corresponding spans, so you can audit
what PXI did and evaluate it like any other agent in Phoenix.
**Attach your identity (opt-in).** Session traces are anonymous by default. If
you want to associate a session with the signed-in user — for example to
attribute recorded sessions to a specific person — enable **Attach your email
to session traces** under **Settings → Assistant → Personal settings**. From
the terminal client the same opt-in is the `--attach-user-id` flag. It is off
unless you turn it on.
**Session identity in traces.** Recorded sessions carry an OpenTelemetry
`session.id` so a conversation's spans group together in the `assistant_agent`
project. As of Phoenix 20 that id has the shape
`{project}:{session-global-id}:{fingerprint}`, where the fingerprint is derived
from the session's creation time. The format changed in this release, so any
saved view, filter, or dashboard that matched the previous `session.id` shape
needs to be rebuilt against the new one.
* **Verify before you act.** PXI can apply filters, edit prompts, and run
bash. Review proposed changes — especially prompt edits — before accepting.
* **Bash runs on the server.** PXI's bash tool executes in an in-process
virtual shell on the Phoenix server, with networking disabled and scoped to a
scratch workspace — it does not reach a host machine, a container, or the
internet. Set `PHOENIX_AGENTS_DISABLE_BASH=true` to remove it (see the
configuration reference below).
* **Don't point it at sensitive production data without controls.** PXI sees
whatever the signed-in user can see.
* **Treat outputs as suggestions.** PXI hallucinates, especially on long
traces or unfamiliar frameworks.
| Environment variable | Effect |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PHOENIX_DISABLE_AGENT_ASSISTANT=true` | Disable PXI for the whole deployment (requires restart). |
| `PHOENIX_ALLOW_EXTERNAL_RESOURCES=false` | Disable external resource access, including the Phoenix docs MCP lookups. |
| `PHOENIX_AGENTS_DISABLE_WEB_ACCESS=true` | Disable PXI's web search/fetch tools while leaving other external resources available. |
| `PHOENIX_AGENTS_DISABLE_BASH=true` | Remove PXI's server-side bash tool. This strips bash from the assistant, disables subagents (and hides the subagents toggle in **Settings → Assistant**), and rejects the headless terminal agent, which depends on it. To turn PXI off entirely use `PHOENIX_DISABLE_AGENT_ASSISTANT`. |
| `PHOENIX_AGENTS_FORCE_TRACING=true` | Force local PXI tracing, remote trace export, and signed-in user email attribution for every user, regardless of workspace or browser settings. Configure the remote collector variables below before enabling it. |
| `PHOENIX_AGENTS_COLLECTOR_ENDPOINT` | Remote collector endpoint for assistant trace export. |
| `PHOENIX_AGENTS_COLLECTOR_API_KEY` | API key for the remote collector, if required. |
| `PHOENIX_AGENTS_ASSISTANT_PROJECT_NAME` | Project name for locally recorded assistant traces (default `assistant_agent`). |
When `phoenix serve` starts, it prints the assistant's effective configuration
as part of the boot banner — whether the agent is enabled, the trace project,
local and remote trace settings, web access, and whether server-side bash is
on — so you can confirm what a deployment resolved to. A malformed
`PHOENIX_AGENTS_*` value fails the server at startup, before migrations run,
rather than surfacing later at request time.
## Feedback
PXI is in beta and will make mistakes. If you hit a rough edge or want to suggest
new capabilities, open an issue or start a discussion on
[GitHub](https://github.com/Arize-ai/phoenix).