Skip to content

docs(develop): Update AI Agents module span conventions - #20033

Draft
cleptric wants to merge 4 commits into
masterfrom
cleptric/ai-agents-develop-docs
Draft

cleptric wants to merge 4 commits into
masterfrom
cleptric/ai-agents-develop-docs

Conversation

@cleptric

Copy link
Copy Markdown
Member

No description provided.

List only the gen_ai attributes Sentry and Relay read, with a description
of each. Drop requirement levels, deprecated attributes, and attributes
Relay derives during ingestion.

Add decision, memory, and handoff spans, the span hierarchy, and common
rules for conversation IDs, errors, and data collection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
develop-docs Ready Ready Preview Oct 19, 2026 4:58am UTC
1 Skipped Deployment
Project Deployment Actions Updated
sentry-docs Ignored Ignored Preview Oct 19, 2026 4:58am UTC

Request Review

@github-actions github-actions Bot added sdk-develop-docs PRs touching develop-docs/sdk Priority: Needs Triage The PR description is missing valid priority information labels Oct 16, 2026
Comment thread develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx Outdated
Comment thread develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx Outdated
| `gen_ai.agent.name` | string | The agent's name. Powers the agent filter and grouping in Agents insights, the agent flow in Conversations, and span titles. | `"Weather Agent"` |
| `gen_ai.input.messages` | string | The messages the agent received. Sentry uses them for the conversation preview and transcript when the child model spans don't carry messages. **[0]** | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` |
| `gen_ai.output.messages` | string | The agent's final response. Used the same way as the input messages. **[0]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` |
| `gen_ai.tool.definitions` | string | The tools available to the agent, as a JSON array of name and description objects. Shown as **Available Tools** in the span details. Omit it when the agent has no tools. | `'[{"name": "get_weather", "description": "..."}]'` |

@alexander-alderman-webb alexander-alderman-webb Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not doing a full review now.
This immediately stands out because available tools are provided on a per-call basis.
A similar caveat to what OTel has for setting gen_ai.request.model on Invoke Agent spans applies

This attribute SHOULD be populated if and only if the instrumented library allows to set only a single model per agent. . It SHOULD NOT be populated for agents that support multiple models or dynamic selection.

All libraries we instrument in Python allow dynamic tool configuration during an agent execution.
As a result, we don't set gen_ai.tool.definitions on Invoke Agent spans in Python.

I know that this doesn't work nicely with the product today, so we should discuss how to resolve this conflict.

Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com>
@cleptric cleptric removed the Priority: Needs Triage The PR description is missing valid priority information label Oct 19, 2026
SDKs no longer drop earlier messages from gen_ai.input.messages. Replace the
trimming rule with guidance to send every message the model received.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

This branch was successfully deployed

2 active (1 outdated) deployments
Preview – develop-docs — bb26a6a7 Deployed Oct 19, 2026 by vercel[bot]
Preview – sentry-docs — 1db73bac Deployed Oct 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

sdk-develop-docs PRs touching develop-docs/sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants