Skip to content

docs(js): Clarify when agent tracing sets the conversation ID - #20894

Open
sentry-junior[bot] wants to merge 2 commits into
masterfrom
docs/js-agent-tracing-conversation-ids
Open

sentry-junior[bot] wants to merge 2 commits into
masterfrom
docs/js-agent-tracing-conversation-ids

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

DESCRIBE YOUR PR

Conversations needs a conversation ID, but the JS agent tracing docs only said that "some integrations infer it". Every integration page linked to the same generic paragraph, so users couldn't tell whether they had to call setConversationId(). This PR states the behavior of each integration in getsentry/sentry-javascript 11.12.0.

  • Agent Tracing → Tracking Conversations: a table of which integrations set the ID always, only in some cases, or never, and where the ID comes from. Notes cover minimum SDK versions and which ID wins over setConversationId(). A new "Set the Conversation ID Yourself" section covers:
    • when you need it
    • which ID to use and which to avoid
    • setting it on every request before the first AI call
    • that only gen_ai.* spans get the ID
    • examples for a request handler, a queue job (withIsolationScope), and several conversations in one request (withScope)
  • Integration pages:
    • OpenAI, Vercel AI, Anthropic, LangChain and LangGraph get a "Conversation IDs" section that says exactly when the ID is inferred.
    • Google Gen AI, Mistral, Groq, Together AI and TypeSafe say they don't set one.
    • Workers AI says the ID is automatic only inside the Agents SDK.
  • Manual instrumentation: a "Group Spans Into a Conversation" section with an example.
  • Stale claims fixed:

Open questions for SDK reviewers

  • The table says Eve, Flue, Mastra, and Pi Durable reset the ID from the framework on every turn, so users should change the framework's ID instead of calling setConversationId(). This is confirmed in code for Eve and Flue. For Mastra and Pi Durable it's inferred.
  • Vercel AI SDK inference is only covered by tests on AI SDK v6/v7, so the page says "AI SDK v6 or later".
  • includes/agent-tracing/manual-instrumentation.mdx looks unused and is left unchanged.

IS YOUR CHANGE URGENT?

  • Urgent deadline (GA date, etc.): YYYY-MM-DD
  • Other deadline: YYYY-MM-DD
  • No deadline: Not urgent, can wait up to 1 week+

PRE-MERGE CHECKLIST

  • Checked Vercel preview for correctness, including links
  • PR was reviewed and approved by any necessary SMEs (subject matter experts)
  • PR was reviewed and approved by a member of the Sentry docs team

via shannon.anahata.

--

View Session [Sentry]

Add a per-integration table of which JavaScript AI integrations set
gen_ai.conversation.id automatically, conditionally, or never, and
expand the manual setConversationId guidance with scope rules and
examples. Fix stale claims for the Cloudflare Agents SDK (random
persisted ID, not the instance name) and Pi Durable (stored session ID).

Co-Authored-By: Shannon Anahata <shannon.anahata@sentry.io>
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sentry-docs Ready Ready Preview Nov 19, 2026 1:42am UTC
1 Skipped Deployment
Project Deployment Actions Updated
develop-docs Ignored Ignored Preview Nov 19, 2026 1:42am UTC

Request Review

@github-actions github-actions Bot added the Priority: Normal Docs review has no urgent deadline label Nov 18, 2026
@sfanahata
sfanahata marked this pull request as ready for review November 19, 2026 01:33
@cursor

cursor Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Getting ready to monitor this change · Rollout details

Status Service Environment
⏳ Getting ready to monitor this change

This branch was successfully deployed

1 active deployment
Preview – sentry-docs — 9a62c7a1 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Priority: Normal Docs review has no urgent deadline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants