Phoenix

AgentV keeps completed runs, traces, transcripts, experiments, and indexes in AgentV-owned local or Git-backed artifacts. The supported zero-infra inspection path is the local Dashboard and result artifact tools. Phoenix is optional external trace infrastructure, not the storage or projection target for AgentV artifacts.

Supported Boundary

AgentV does not export or project completed AgentV runs, traces, transcripts, datasets, experiments, or indexes into Phoenix.

Phoenix can still appear in AgentV workflows in two narrow ways:

• As UI inspiration for local trace and session review.
• As an optional external trace database when Codex, Arize, or another hook already emitted spans independently.

When an AgentV run artifact includes safe external_trace metadata, AgentV may link to that external Phoenix session. Dashboard can also read the linked session through Phoenix GraphQL/API from the AgentV server process and show a compact session panel. AgentV must not write AgentV artifacts into Phoenix as part of that flow.

Local Inspection

Use Dashboard for AgentV-owned run and trace review:

agentv dashboard

Dashboard reads configured project run sources, local .agentv/results/runs/ workspaces, remote results repositories, trace sidecars, transcripts, and artifact manifests. It does not require Phoenix, the px CLI, Phoenix database tables, or any Phoenix runtime process.

If a run has external_trace metadata and the Dashboard server has a Phoenix endpoint configured, the run detail page can show the linked Phoenix session summary, turns, trace IDs, root span input/output, timing, token usage, costs, annotations, a trace tree, and selected span details. Missing configuration, unreachable Phoenix, schema mismatches, or no matching session render as recoverable empty/error states; AgentV run detail still loads from AgentV artifacts.

Configure the Dashboard server with one of:

AGENTV_PHOENIX_ENDPOINT=https://phoenix.example
PHOENIX_HOST=https://phoenix.example

Optional server-side auth can be supplied with:

AGENTV_PHOENIX_API_KEY=...
AGENTV_PHOENIX_AUTHORIZATION="Bearer ..."
PHOENIX_CLIENT_HEADERS='{"Authorization":"Bearer ..."}'

These credentials stay server-side and are not written to AgentV artifacts or sent to the browser.

External Trace Metadata

AgentV artifacts may carry metadata such as:

{
  "external_trace": {
    "provider": "phoenix",
    "source": "codex",
    "endpoint": "https://phoenix.example",
    "project": "agentv-dogfood",
    "session_node_id": "UHJvamVjdFNlc3Npb246MQ==",
    "session_id": "codex-session-123",
    "trace_id": "phoenix-trace-456",
    "traceparent": "00-11111111111111111111111111111111-2222222222222222-01",
    "ui_url": "https://phoenix.example/projects/agentv-dogfood/traces/phoenix-trace-456"
  }
}

Only safe link and identity fields should be surfaced. Secrets, API keys, authorization headers, raw tool payloads, and local filesystem paths should stay out of external_trace metadata.

Transcript Boundary

AgentV transcript artifacts are not Phoenix-native conversation inputs. Model-call spans may carry cumulative input messages, so treating Phoenix span inputs as a linear transcript can duplicate prior turns and distort the conversation. Keep transcript, index, and storage semantics in AgentV artifacts; use Phoenix only as optional external context when safe metadata points at an already-existing session.

Non-Goals

• No AgentV-to-Phoenix export or projection of completed runs, traces, transcripts, datasets, experiments, or indexes.
• No Phoenix-owned AgentV transcript, index, or storage model.
• No Dashboard runtime dependency on Phoenix or px.
• No direct Dashboard access to Phoenix database tables.
• No Phoenix dataset or experiment creation as part of the zero-infra local path.
• No browser-side exposure of Phoenix API keys, authorization headers, cookies, or tokens.