04.03.2026 ATIF Trajectory Upload

Available in arize-phoenix-client 2.3.0+ (Python)

Phoenix now ingests ATIF (Agent Trajectory Interchange Format) trajectories directly. upload_atif_trajectories_as_spans converts ATIF JSON files into OpenTelemetry-compatible span trees and uploads them to any Phoenix project, letting you visualize offline agent runs alongside live instrumented traces.

Trace Structure#

Each trajectory becomes one trace. The span hierarchy follows the causal model used by real-time instrumentors — TOOL spans are siblings of the LLM spans under the AGENT, not children:

AGENT (root)  LLM    ← decides to call a tool  TOOL   ← agent runtime executes the tool  LLM    ← processes the result

Multi-turn conversations get nested per-turn AGENT spans. Trajectories that reference each other via subagent_trajectory_ref are linked into a single trace when uploaded together.

Usage#

import jsonfrom phoenix.client import Clientfrom phoenix.client.helpers.atif import upload_atif_trajectories_as_spansclient = Client()with open("trajectory.json") as f:    trajectory = json.load(f)result = upload_atif_trajectories_as_spans(    client,    [trajectory],    project_name="my-agent-project",)# {"total_received": 5, "total_queued": 5}

Upload multiple trajectories in a single call to enable subagent linking:

with open("parent.json") as f:    parent = json.load(f)with open("child.json") as f:    child = json.load(f)# Parent and child are linked into one trace automaticallyresult = upload_atif_trajectories_as_spans(    client,    [parent, child],    project_name="my-agent-project",)

Key Details#

• Supported versions: ATIF schema v1.0 through v1.6
• Deterministic IDs: trace and span IDs are derived from session_id via SHA-256 — re-uploading the same trajectory is idempotent
• Multimodal content (v1.6+): image content parts are stored using the OpenInference message.contents array format
• Continuation merging: sessions split across files (session_id ending in -cont-N) are automatically merged into one trace
• Attribute mapping: token counts, cost, model name, tool definitions, and reasoning content are mapped to standard OpenInference attributes