Capture your first agent run

When you ask the Wonder Toys shopping agent to find a toy, you see its answer in the chat. To understand how it reached that answer, you’ll add instrumentation, code that records its model and tool calls so you can inspect them in Phoenix. We’ll start with the uninstrumented Wonder Toys agent, add tracing, and send a shopping request. Then we’ll open its trace in Phoenix to see what happened.

Follow along with Wonder Toys, or use your own agent. For your own agent, use the integration guide for your framework to enable tracing, then send a request and inspect its trace in Phoenix. The setup commands and file paths below are for Wonder Toys.

Before you start

For the Wonder Toys walkthrough, you’ll need:

Git and Node.js 22 installed.
uv to run Phoenix and the Python backend.
An Anthropic API key for the default model. An OpenAI alternative is shown in Step 2.

For this walkthrough, we’ll use the LangChain Python version of Wonder Toys, though Phoenix also supports other frameworks. Keep 2 terminals open: one for Phoenix and one for the app.

Step 1: Start Phoenix

If Phoenix is already running, use that instance. Otherwise, start Phoenix locally in the first terminal:

uvx --python 3.11 arize-phoenix serve

Open the Web UI address shown in the terminal. Phoenix uses http://localhost:6006 by default. Leave Phoenix running for the following steps.

Step 2: Prepare the practice app

With Phoenix running, let’s prepare the app that will send it traces. In the second terminal, get the uninstrumented Wonder Toys app and install its frontend dependencies:

git clone https://github.com/Arize-ai/project-rosetta-stone.git
cd project-rosetta-stone/no-observability/langchain-py
npm install
cp env.example .env.local

Next, open .env.local to configure the app and tell it where Phoenix is running. Set these values, replacing the key placeholder with your Anthropic key:

ANTHROPIC_API_KEY=your-anthropic-api-key
ANTHROPIC_OPEN_TELEMETRY=false
BACKEND_SECRET=academy-local-demo
BACKEND_URL=http://localhost:8001
CHROMA_URL=http://localhost:8000
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PHOENIX_PROJECT_NAME=wonder-toys

If your Phoenix address differs from the example, use it for PHOENIX_COLLECTOR_ENDPOINT. LangChain will record the model calls in Step 3. The Anthropic setting prevents its SDK from recording a second copy. Keep working in no-observability/langchain-py; the file paths below start from this folder.

Use OpenAI for this lesson instead

You can use OpenAI for this lesson if you prefer. Later lessons use Anthropic, so keep the default model if you want to follow those commands unchanged.You can use ChatOpenAI with the same LangChain instrumentation. Add langchain-openai to backend/requirements.txt, then replace the Anthropic key in .env.local with your OpenAI API key:

OPENAI_API_KEY=your-openai-api-key

In backend/agent.py, replace the ChatAnthropic import with:

from langchain_openai import ChatOpenAI

Replace the entire _build_agent function, including its Anthropic key check, with:

def _build_agent():
    model = ChatOpenAI(model="gpt-4.1-mini")
    return create_react_agent(model, all_tools, prompt=SYSTEM_PROMPT)

ChatOpenAI reads your OPENAI_API_KEY automatically.

Step 3: Record the model and tool calls

With the app configured, let’s enable auto instrumentation to record its model and tool calls. You can add the setup code yourself or ask a coding assistant to do it.

Add the code yourself
Use a coding assistant

Add these packages to backend/requirements.txt to record calls and send them to Phoenix:

arize-phoenix-otel
openinference-instrumentation-langchain

Then create backend/tracing.py to connect to Phoenix and enable auto instrumentation:

from phoenix.otel import register
from openinference.instrumentation.langchain import LangChainInstrumentor

_tracer_provider = register(protocol="http/protobuf")
LangChainInstrumentor().instrument(tracer_provider=_tracer_provider)

register uses the Phoenix address and project name you set in Step 2.To load this setup before the agent starts, add this import before all other imports in backend/main.py:

import backend.tracing

If you have a coding assistant such as Claude Code or Codex installed, you can use Phoenix’s setup command to add tracing. Run it from no-observability/langchain-py:

npx -y @arizeai/phoenix-cli setup \
  --endpoint http://localhost:6006 \
  --project wonder-toys \
  --language python

Use your Phoenix address for --endpoint if it differs from the example.

Choose your assistant and follow the prompts to add tracing. Setup checks that a trace arrives and may send a test request using your model API key.
Ask it to keep registration in backend/tracing.py, with the provider named _tracer_provider.
Review its changes: check those names, confirm tracing starts before the agent, and verify the project is wonder-toys.

We chose tracing.py and _tracer_provider for these lessons; the next lesson reuses those names.

Step 4: Send a shopping request

With tracing in place, start the app from no-observability/langchain-py in the second terminal. If your coding assistant already started it, stop the app before running this command so it loads your changes:

UV_PYTHON=3.11 npm run dev

This command runs the startup script, which installs the Python dependencies and starts the app. On its first run, it also downloads the product-search model. When the app is ready, you’ll see its address next to Local in your terminal. Open that address in your browser and send this request:

Find dinosaur toys for a 6-year-old under $25. Recommend at most 3 options.

Wonder Toys in light mode with the dinosaur toy request entered in the chat box and the purple Send button beside it. — Enter the request in the chat box, then select Send.

Wait for the reply, then return to Phoenix. Keep both terminals running.

Step 5: Find your first trace

Now let’s see what happened when the agent handled your request. A trace is the record of one request, from start to finish. Each span records a step within that trace, such as a model call or a tool call.

LangGraph contains an agent step with a model call, a tools step with a tool call, and another agent step with a model call. — LangGraph's agent and tools steps contain the model and tool calls. Each row is a span; other intermediate spans and repeated calls are omitted.

In Phoenix:

Open wonder-toys → Traces and select the chat request you just sent, usually named POST /chat or LangGraph.
Expand the span tree and find LangGraph, which contains the agent’s workflow.
Select a ChatAnthropic model span, or ChatOpenAI if you used that option. Under Info, look for your shopping request in Input and the model’s reply in Output.
If the agent searched for products, select search-products to see its arguments and returned products.

Phoenix trace with LangGraph and its child spans visible on the left, ChatAnthropic selected, and the shopper's dinosaur toy request expanded under Info and Input on the right. — Select ChatAnthropic in the span tree to see the shopper's request under Info → Input.

You’ve completed this lesson when you can find your request in a model span and inspect the recorded calls.

Next: Make the complete interaction easier to review

You can now inspect individual model and tool calls. In Add an agent span, you’ll put the shopper’s request and the complete answer together, making it easier to check whether the agent answered what was asked.

Start here

Understand behavior

Find failures

Design evaluations

Test a change

Ship and repeat

Capture your first agent run

Before you start

Step 1: Start Phoenix

Step 2: Prepare the practice app

Step 3: Record the model and tool calls

Step 4: Send a shopping request

Step 5: Find your first trace

Next: Make the complete interaction easier to review

​Before you start

​Step 1: Start Phoenix

​Step 2: Prepare the practice app

​Step 3: Record the model and tool calls

​Step 4: Send a shopping request

​Step 5: Find your first trace

​Next: Make the complete interaction easier to review

Before you start

Step 1: Start Phoenix

Step 2: Prepare the practice app

Step 3: Record the model and tool calls

Step 4: Send a shopping request

Step 5: Find your first trace

Next: Make the complete interaction easier to review