Add availableTools to agent span attributes for observability (#14550)

## Description

This PR adds the `availableTools` attribute to agent tracing spans in
the prepare-tools step of the modern agent loop. This ensures that
observability integrations (such as Datadog LLM Observability) can
correctly receive tool definitions on `AGENT_RUN` spans when using
streaming methods.

The change updates the agent span with the list of available tool names
after tools are converted, making this information available for
downstream observability platforms.

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes #123 -->

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [X] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

https://claude.ai/code/session_01RhF8cPu2ooEeY8s8rBJw1h

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Agent run tracing during streaming now includes available tool
definitions in run spans.

* **New Features**
* Observability exporters now receive agent tool lists on agent run
spans for improved trace visibility.

* **Tests**
* Integration tests updated to assert available tool identifiers are
present in agent run spans.

* **Chores**
  * Trace snapshots updated to reflect the included available tools.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 3 people

.changeset/happy-walls-follow.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed missing tool lists in agent traces for streaming runs. Exporters like Datadog LLM Observability now receive the tools available to the agent.

observability/mastra/src/__snapshots__/agent-tool-call-trace.json

@@ -23,7 +23,8 @@
         "entityId": "test-agent",
         "attributes": {
           "conversationId": "test-thread-id",
-          "instructions": "You are a test agent"
+          "instructions": "You are a test agent",
+          "availableTools": ["calculator", "apiCall", "workflowExecutor"]
         },
         "metadata": {
           "runId": "<runId-1>",

observability/mastra/src/__snapshots__/agent-workflow-direct-trace.json

@@ -24,7 +24,8 @@
         "entityType": "agent",
         "entityId": "workflow-agent",
         "attributes": {
-          "instructions": "You can execute workflows that exist in your config"
+          "instructions": "You can execute workflows that exist in your config",
+          "availableTools": ["workflow-simpleWorkflow"]
         },
         "metadata": {
           "runId": "<runId-1>"

observability/mastra/src/__snapshots__/agent-workflow-tool-trace.json

@@ -24,7 +24,8 @@
         "entityType": "agent",
         "entityId": "workflow-agent",
         "attributes": {
-          "instructions": "You can execute workflows using the workflow executor tool"
+          "instructions": "You can execute workflows using the workflow executor tool",
+          "availableTools": ["workflowExecutor"]
         },
         "metadata": {
           "runId": "<runId-1>",

observability/mastra/src/__snapshots__/multi-step-text-accumulation-trace.json

@@ -23,7 +23,8 @@
         "entityType": "agent",
         "entityId": "multi-step-agent",
         "attributes": {
-          "instructions": "You are a helpful calculator assistant that announces what you will do before doing it."
+          "instructions": "You are a helpful calculator assistant that announces what you will do before doing it.",
+          "availableTools": ["calculator"]
         },
         "metadata": {
           "runId": "<runId-1>"

observability/mastra/src/__snapshots__/tool-child-spans-trace.json

@@ -23,7 +23,8 @@
         "entityType": "agent",
         "entityId": "child-span-agent",
         "attributes": {
-          "instructions": "You use tools that create child spans"
+          "instructions": "You use tools that create child spans",
+          "availableTools": ["childSpanTool"]
         },
         "metadata": {
           "runId": "<runId-1>"

observability/mastra/src/__snapshots__/tool-metadata-trace.json

@@ -22,7 +22,8 @@
         "entityType": "agent",
         "entityId": "metadata-agent",
         "attributes": {
-          "instructions": "You use tools and add metadata"
+          "instructions": "You use tools and add metadata",
+          "availableTools": ["metadataTool"]
         },
         "metadata": {
           "runId": "<runId-1>"

observability/mastra/src/integration-tests.test.ts

@@ -823,6 +823,12 @@ describe('Tracing Integration Tests', () => {
         expect(llmGenerationSpan?.endTime).toBeDefined();
         expect(agentRunSpan?.endTime).toBeDefined();
         expect(llmGenerationSpan?.endTime!.getTime()).toBeLessThanOrEqual(agentRunSpan?.endTime!.getTime());
+
+        // Verify availableTools is populated on the AGENT_RUN span
+        expect(agentRunSpan?.attributes?.availableTools).toBeDefined();
+        expect(agentRunSpan?.attributes?.availableTools).toEqual(
+          expect.arrayContaining(['calculator', 'apiCall', 'workflowExecutor']),
+        );
       });
     },
   );

packages/core/src/agent/workflows/prepare-stream/index.ts

@@ -24,7 +24,7 @@ interface CreatePrepareStreamWorkflowOptions<OUTPUT = undefined> {
   resourceId?: string;
   runId: string;
   requestContext: RequestContext;
-  agentSpan: Span<SpanType.AGENT_RUN>;
+  agentSpan?: Span<SpanType.AGENT_RUN>;
   methodType: AgentMethodType;
   instructions: SystemMessage;
   memoryConfig?: MemoryConfigInternal;

packages/core/src/agent/workflows/prepare-stream/map-results-step.ts

@@ -24,7 +24,7 @@ interface MapResultsStepOptions<OUTPUT = undefined> {
   requestContext: RequestContext;
   memory?: MastraMemory;
   memoryConfig?: MemoryConfigInternal;
-  agentSpan: Span<SpanType.AGENT_RUN>;
+  agentSpan?: Span<SpanType.AGENT_RUN>;
   agentId: string;
   methodType: AgentMethodType;
   saveQueueManager?: SaveQueueManager;