From 1bebcf0c8d2d53b629f1e27be5470f058e8a5d49 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 4 Nov 2026 12:48:35 +0100 Subject: [PATCH 1/2] chore(ai-sdks): Describe relationships between GenAI spans --- .../sdk/telemetry/traces/modules/ai-agents.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index f03cfcb071e34..443cb32d6faea 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -20,6 +20,16 @@ Sentry Conventions is the single source of truth. + +## Span Relationships + +An agent invocation span has tool execution and chat span children, but chat spans need not have an agent invocation parent (not all chat requests are triggered by an agent). +Agents can have other children such as extraction, decision and memory spans, depending on what's considered part of an agent execution in a given application. +Automatic instrumentation considers an agent execution to be one run of the agent as represented by the supported library. + +All span types can be children of a tool execution span because tools can be arbitrary functions (including starting subagents and performing handoffs). +Chat, extraction and decision spans are basic building blocks and should not have GenAI spans as children. + ## Invoke Agent Span Describes AI agent invocation. From c24b28e5dfc42a8c07525fb601d8d4ad1a4c89d8 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 4 Nov 2026 15:08:08 +0100 Subject: [PATCH 2/2] add some diagrams --- .../telemetry/traces/modules/ai-agents.mdx | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 2b5b0f1645afa..af92d7395c8ee 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -30,6 +30,47 @@ Automatic instrumentation considers an agent execution to be one run of the agen All span types can be children of a tool execution span because tools can be arbitrary functions (including starting subagents and performing handoffs). Chat, extraction and decision spans are basic building blocks and should not have GenAI spans as children. +Valid examples: + +### Agent execution with extraction, decision and memory children + +``` +gen_ai.invoke_agent +├── gen_ai.chat +├── gen_ai.memory +├── gen_ai.extraction +├── gen_ai.chat +├── gen_ai.execute_tool +├── gen_ai.chat +└── gen_ai.decide +``` + +### Chat, memory, decision, and extraction spans outside of an agent execution + +``` +gen_ai.chat +gen_ai.extraction +gen_ai.invoke_agent +├── gen_ai.chat +├── gen_ai.execute_tool +└── gen_ai.chat +gen_ai.decide +gen_ai.memory +``` + +### Subagent + +``` +gen_ai.invoke_agent +├── gen_ai.chat +├── gen_ai.execute_tool +│ └── gen_ai.invoke_agent +│ ├── gen_ai.chat +│ ├── gen_ai.execute_tool +│ └── gen_ai.chat +└── gen_ai.chat +``` + ## Invoke Agent Span Describes AI agent invocation.