feat(ai): instrument tool execution spans and definitions

[constantinius]

Add execute_tool span lifecycle around InvokingTool and ToolInvoked events, and propagate serialized tool definitions onto invoke_agent and chat spans. This isolates tool-level monitoring while leaving message payload capture and embeddings for later stacked branches.

Included

• Implements tool lifecycle handlers:
  • InvokingTool -> start gen_ai.execute_tool span
  • ToolInvoked -> finish gen_ai.execute_tool span
• Captures tool metadata:
  • tool name/type/description
  • tool call arguments/result (when default PII is enabled)
• Adds and propagates serialized tool definitions:
  • on invoke_agent span
  • on chat spans
• Extends conversation-id propagation to tool spans.
• Adds tracing.gen_ai_execute_tool toggle.

Made-with: Cursor

Issues

• Contributes to https://linear.app/getsentry/issue/TET-2064/split-current-pr
• Contributes to https://linear.app/getsentry/issue/TET-1971/laravel-ai-integration

[linear-code]

TET-2064 Split current PR

TET-1971 Laravel AI integration

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: TestAgent missing HasTools interface breaks tool definitions assertions
  • I added a guarded HasTools test stub and made TestAgent implement it so resolveToolDefinitions() now includes tool definitions for the asserted spans.

Or push these changes by commenting:

@cursor push 9024ee0ae4

Preview (9024ee0ae4)

diff --git a/test/Sentry/Features/AiIntegrationTest.php b/test/Sentry/Features/AiIntegrationTest.php
--- a/test/Sentry/Features/AiIntegrationTest.php
+++ b/test/Sentry/Features/AiIntegrationTest.php
@@ -8,6 +8,12 @@
     }
 }
 
+if (!interface_exists(HasTools::class)) {
+    interface HasTools
+    {
+    }
+}
+
 if (!interface_exists(Tool::class)) {
     interface Tool
     {
@@ -290,6 +296,7 @@
 use Laravel\Ai\Attributes\MaxTokens;
 use Laravel\Ai\Attributes\Temperature;
 use Laravel\Ai\Contracts\Agent;
+use Laravel\Ai\Contracts\HasTools;
 use Laravel\Ai\Contracts\Providers\EmbeddingProvider;
 use Laravel\Ai\Contracts\Providers\TextProvider;
 use Laravel\Ai\Contracts\Tool;
@@ -297,7 +304,7 @@
 use Laravel\Ai\Responses\QueuedAgentResponse;
 use Laravel\Ai\Responses\StreamableAgentResponse;
 
-class TestAgent implements Agent
+class TestAgent implements Agent, HasTools
 {
     public function instructions(): string
     {

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Provider prefix overmatches unrelated HTTP requests

Medium Severity

findMatchingInvocation matches any request under the provider base URL, so unrelated calls (for example tool-triggered requests to other provider endpoints) are treated as gen_ai.chat. This creates spurious chat spans, changes the hub’s current span unexpectedly, and pollutes chatSpans ordering used for step-to-span enrichment.

Additional Locations (1)

• src/Sentry/Laravel/Features/AiIntegration.php#L167-L221

 

[cursor]

Conversation ID write to agent span is immediately overwritten

Low Severity

setConversationIdOnSpans includes the agent span ($invocation->span) in the set of spans it updates with the conversation ID. However, the caller handleAgentPromptedForTracing already adds the conversation ID to its local $data array (line 153) and then overwrites the agent span's entire data with $agentSpan->setData($data) (line 157), immediately after calling setConversationIdOnSpans (line 154). The modification setConversationIdOnSpans made to the agent span is discarded. The agent span could be excluded from the loop in setConversationIdOnSpans to avoid the wasted read-modify-write cycle.

Additional Locations (1)

• src/Sentry/Laravel/Features/AiIntegration.php#L130-L157

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Provider name normalization inconsistency across code paths

Low Severity

The gen_ai.provider.name attribute is set with inconsistent casing. In handlePromptingAgentForTracing, $provider->name() is stored as-is, but in handleAgentPromptedForTracing, the fallback from $event->response->meta->provider is wrapped in strtolower(). If a provider's name() method returns a mixed-case string (e.g., "OpenAI"), the primary path stores it verbatim while the fallback path lowercases it, leading to inconsistent attribute values across traces for the same provider.

Additional Locations (1)

• src/Sentry/Laravel/Features/AiIntegration.php#L80-L81