Follow a conversation with sessions

In this lesson, you’ll learn to use sessions in Phoenix to review the traces from one conversation together. You’ll practice with Wonder Toys, a shopping assistant agent, and check whether its follow-up answers match earlier messages.

A session with a shared session ID contains three traces, one for an initial request and one for each follow-up. Each trace has its own agent and model spans, with tool spans when tools are called. — A shared session.id groups the traces. Each card lists example spans from one request.

Before you start

Continue with the browser app from Add an agent span. Keep Phoenix running and work in the same no-observability/langchain-py folder. The screenshots show one example conversation; your products and answers may be different.

Step 1: Connect requests from the same conversation

Let’s make Wonder Toys create a conversation ID automatically and send it with each message. You don’t need to choose an ID or paste one into Phoenix.

First message: the app creates an ID for the chat.
Follow-ups: it reuses that ID so Phoenix groups the traces together.
New chat: it creates a new ID for the next conversation.

In backend/agent.py, using_session goes around the agent span you added earlier:

Key change in backend/agent.py

with using_session(session_id), _tracer.start_as_current_span(
    "Wonder Toys", openinference_span_kind="agent"
) as root_span:
    root_span.set_input(question)
    # The existing streaming code continues here.

The app supplies session_id for the current chat. using_session records it as session.id on the spans. Choose one setup method below to connect the chat to this function.

Add the code yourself
Use a coding assistant

The instrumented Wonder Toys app uses the same pattern. Expand the setup below to make all 4 file changes.

Set up session tracking in Wonder Toys

Create the ID in the chat. In src/components/Chat.tsx, find fetchResponse. Add these lines inside its try block, before fetch:

const sessionId = sessionStorage.getItem("chat-session-id") ?? crypto.randomUUID();
sessionStorage.setItem("chat-session-id", sessionId);

This creates an ID on the first request and reuses it for follow-ups. Replace that fetch call’s existing headers line with:

headers: { "Content-Type": "application/json", "x-session-id": sessionId },

In the same file, find the Wonder Toys logo’s onClick handler. Add this after sessionStorage.removeItem("chat-messages") so a new chat gets a new ID:

sessionStorage.removeItem("chat-session-id");

Pass the ID to Python. The web app forwards messages to the Python backend. It needs to forward the ID too. In src/app/api/chat/route.ts, add this after const { messages } = await req.json():

const sessionId = req.headers.get("x-session-id") || crypto.randomUUID();

Add this field to the existing backend fetch call’s headers object:

"X-Session-ID": sessionId,

In backend/main.py, add this import with the existing imports:

from uuid import uuid4

In chat, read the ID after the existing user_id line. The fallback creates an ID for requests sent directly to Python:

session_id = request.headers.get("x-session-id") or str(uuid4())

In that function’s StreamingResponse, update the agent call to pass the ID:

stream_agent(messages, user_id, session_id=session_id),

Attach the ID to the spans. In backend/agent.py, add these imports:

from uuid import uuid4
from phoenix.otel import using_session

Update the stream_agent signature to accept the ID:

async def stream_agent(
    messages: list[dict], user_id: str, session_id: str | None = None
) -> AsyncIterator[str]:

Add this at the start of the function. It also supports calls made outside the web app:

session_id = session_id or str(uuid4())

Replace the opening of the existing with block with this code. Keep its body at the same indentation:

with using_session(session_id), _tracer.start_as_current_span(
    "Wonder Toys", openinference_span_kind="agent"
) as root_span:

Inside agent.astream_events, replace the existing config argument with:

config={"recursion_limit": 25, "metadata": {"session_id": session_id}},

using_session tags the agent span and its calls. The LangChain metadata also carries the ID through the workflow.

Use an assistant with the Phoenix tracing skill installed. Open the app folder and paste:

Add conversation tracking to the Wonder Toys app using the Phoenix tracing skill.
Inspect src/components/Chat.tsx, src/app/api/chat/route.ts, backend/main.py, backend/agent.py, and the existing tracing setup. Show the proposed changes first.

- Store a conversation ID in browser sessionStorage as chat-session-id.
- Reuse it for follow-ups and reset it when the Wonder Toys logo starts a new chat.
- Send it as x-session-id through the web app to the Python backend.
- Pass it to stream_agent. Use using_session around the existing Wonder Toys span and include session_id in the LangChain metadata.
- Reuse the existing tracer provider and preserve the agent's streaming behavior.
- Verify that follow-ups share a session and a new chat starts a different session.

Restart the app to load your changes:

UV_PYTHON=3.11 npm run dev

Step 2: Start a conversation and ask a follow-up

Open the app in your browser using the Local address shown in the terminal. Select the Wonder Toys logo to start a new chat, then send the original request again:

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

This request starts your session. Earlier traces won’t gain a session ID retroactively. If the first answer didn’t recommend a product, ask “What age and budget did I ask you to use?” instead. Check that reply against your original request for the rest of this exercise. If it recommended a product, send these follow-ups in the same chat:

Tell me more about the cheapest one you recommended. What is its product ID and age range?

Wait for the answer, then ask about the same toy without naming it:

Would that same toy suit a 2-year-old? Use its listed age range.

Step 3: Open the session in Phoenix

A turn is one shopper message and the agent’s answer. Wonder Toys records each turn as a trace and groups them in the same session. To open your conversation:

Open wonder-toys → Sessions in Phoenix.
Find your shopper’s request in the first input column.
Select that row’s session id.

Phoenix project with the Sessions tab and the session ID outlined in blue, alongside the dinosaur toy request in the first input column — Select Sessions, then select the session ID for your conversation. Both click targets are outlined in blue.

Under Turns, select each request on the left to read its message and answer on the right. Check that your original request and follow-ups appear together.

Step 4: Compare the follow-up answers

Read the replies in order, using these checks for the toy questions:

Product: Did the first follow-up identify the cheapest recommendation?
Age range: Did the next reply refer to that same toy and use the age range given earlier?

In the example below, the final reply still names the Insect & Bug Collection and explains that its age range of 3 to 8 years excludes a 2-year-old.

Phoenix session with three turns listed on the left and the final follow-up and answer about the Insect and Bug Collection on the right — Turn 03 answers the follow-up about the toy discussed in Turn 02.

The conversation shows whether the replies agree with each other. Next, check which earlier messages the model actually received.

Step 5: Check the model’s conversation history

To inspect the messages sent with the final follow-up:

Select Trace beside the final turn.
Select the first ChatAnthropic model call.
Under Info → Input, expand the earlier message that the follow-up refers to.

Phoenix session trace with ChatAnthropic selected and its Input section showing the earlier assistant reply naming the Insect and Bug Collection and its age range of 3 to 8 years — The earlier assistant reply appears in the model's input, including the toy's age range.

Use the message history to explain what happened:

Message missing: The model didn’t receive that earlier part of the conversation.
Message present: Check whether the follow-up answer agrees with it.

Wonder Toys supplies this history, while the session ID groups the traces in Phoenix. In this example:

The model received the earlier reply naming the Insect & Bug Collection for ages 3 to 8. It then referred to the same toy and said it wasn’t suitable for a 2-year-old.

Use your own trace to explain whether the follow-up answer matched the earlier messages in the model’s input.

Session IDs and user IDs

A session.id identifies one conversation, while a user.id identifies the person. If the same shopper starts a new chat, give it a new session ID and keep the same user ID.

Now that you can inspect individual requests and conversations, review traces and feedback to find problems that recur across runs.

Start here

Understand behavior

Find failures

Design evaluations

Test a change

Ship and repeat

Follow a conversation with sessions

Before you start

Step 1: Connect requests from the same conversation

Step 2: Start a conversation and ask a follow-up

Step 3: Open the session in Phoenix

Step 4: Compare the follow-up answers

Step 5: Check the model’s conversation history

Next

​Before you start

​Step 1: Connect requests from the same conversation

​Step 2: Start a conversation and ask a follow-up

​Step 3: Open the session in Phoenix

​Step 4: Compare the follow-up answers

​Step 5: Check the model’s conversation history

​Next

Before you start

Step 1: Connect requests from the same conversation

Step 2: Start a conversation and ask a follow-up

Step 3: Open the session in Phoenix

Step 4: Compare the follow-up answers

Step 5: Check the model’s conversation history

Next