docs(agents): adopt gen_ai.decide for decision spans

[ArthurKnaus]

DESCRIBE YOUR PR

Follows sentry-conventions#696, which deprecates gen_ai.evaluate in favor of gen_ai.decide. Renames "evaluation spans" to "decision spans" and updates the span operation, name, and gen_ai.operation.name values in all code snippets. The old evaluate names stay documented as deprecated but still recognized, since the product continues to support them.

• Manual instrumentation (JS + Python): "Decision Span" section, gen_ai.decide op, decide {model} name, gen_ai.operation.name: "decide"
• Shared attributes include: new decide values plus a deprecation note (inner type: "evaluation" JSON field unchanged, matching the convention)
• Conversations product doc: "Decision Spans" section, updated example, predicate added to answer types, anchors updated to #decision-span(s)
• php/laravel cross-link retargeted to #decision-spans
• Agents index: added decisions keyword
• Replaced the two span-detail screenshots with gen_ai.decide versions

Part of TET-3102

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

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

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• 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

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
sentry-docs	Ready	Preview	Oct 13, 2026 12:38pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Oct 13, 2026 12:38pm UTC

[linear-code]

TET-3102

[cursor]

The plan checks page loads, not-found counts, and client errors on the rewritten pages. An issue escalates when those pages stop loading or those errors appear. Telemetry cannot show the new wording.

Monitoring in production

Services: sentry-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

Published pages now describe decision spans. Code samples now use gen_ai.decide for the span op, name, and operation name. The old gen_ai.evaluate names stay documented as deprecated.

sentry-docs must deploy before this change is live. The files sit under docs/ and includes/. develop-docs does not ship this content.

Risk

Readers can copy deprecated span names if the new samples fail to render. A broken include or heading can 404 those agent pages or skip the decision section. Old links to #evaluation-span no longer jump to the heading. This blast stays on the agent documentation pages.

Intended effect

This change rewrites documentation copy and code samples. No metric records the new span names on the published pages. The executor cannot set intended_effect from telemetry. Mark intended_effect unknown.

If the executor opens the live pages, confirmed means the Decision Span heading and gen_ai.decide samples are present. Absent means those pages still show Evaluation Span and gen_ai.evaluate as the current names.

Regression watch

Watch the changed agent pages for missing loads, new 404s, and client errors. A drop to zero loads on the conversations page while the agents index still loads is a page break. A rise in product/agents not-found counts is a 404. New errors on those URLs are a client crash.

Signal	Baseline	Window	Rule	Source
docs.page.load for path /product/agents/	50-90 loads	2026-10-12T11:45:00Z to 2026-10-13T11:45:00Z	Hold the band. Fall to 0 is a break.	Sentry sentry/docs. Query sentry.environment:production path:"/product/agents/". Sum docs.page.load.
docs.page.load for path /product/agents/conversations/	8-20 loads	2026-10-12T11:45:00Z to 2026-10-13T11:45:00Z	Hold the band. Fall to 0 while /product/agents/ holds is a break.	Sentry sentry/docs. Query sentry.environment:production path:"/product/agents/conversations/". Sum docs.page.load.
docs.page.load for paths *agent-tracing/manual-instrumentation* and *laravel/agent-tracing*	9-24 loads across those paths	2026-10-12T11:45:00Z to 2026-10-13T11:45:00Z	Hold above 0 on the python manual, laravel, and node manual paths.	Sentry sentry/docs. Query sentry.environment:production (path:*agent-tracing/manual-instrumentation* OR path:*laravel/agent-tracing*). Sum docs.page.load grouped by path. Measured rows: laravel 5, python manual 3, nextjs manual 2, node manual 2, fastify manual 1, azure-functions manual 1.
docs.page.not_found for requested_path product/agents	0-2 counts, about 1.2% of the 86 agents-index plus conversations loads	2026-10-12T11:45:00Z to 2026-10-13T11:45:00Z	Hold 0-2. Rise above 2 is a 404 regression.	Sentry sentry/docs. Query environment:production requested_path:"product/agents". Sum docs.page.not_found.
Client errors on the changed URLs	0 events	2026-10-12T11:45:00Z to 2026-10-13T11:45:00Z	Hold at 0. Any rise is a crash on these pages.	Sentry sentry/docs errors. Query environment:production AND (url:*product/agents* OR url:*agent-tracing*).

Site-wide docs errors were 209 in the same window. Those events are mostly search and widget fetch noise on the catch-all /:path*? route. Do not use that fleet count for this change.

Not observable

Live page wording after deploy. No metric stores the heading or sample text.

In-page jumps to the old #evaluation-span and #evaluation-spans hashes. The server does not see URL fragments. There is no redirect for those hashes.

Client errors that only tag the catch-all /:path*? route. The URL filter above can miss them.

Get Slack DMs about this change: cursor.com/automations/rollouts

[cursor]

Issue detected in production

Python and Node tracing guides still tell readers to use Evaluation Span

This change was supposed to publish Decision Span headings and gen_ai.decide samples on the agent docs. One hour after the ship, the conversations page shows Decision Spans, but the live Python and Node manual pages still load and still present Evaluation Span and gen_ai.evaluate as the current names. Readers of those guides can still copy the old span names.

[cursor]

Verified in production

• The Python and Node guides now show Decision Span and gen_ai.decide samples.