[FEATURE] Agent- Metrics - Report Local Traces in Result

[lizradway]

Summary

Provide lightweight, in-memory execution traces on AgentResult that track the timing and hierarchy of operations within the agent loop. Each invocation collects a tree of LocalTrace objects representing cycles, model calls, and tool executions — always available regardless of whether OpenTelemetry is configured. Traces are returned via result.traces for programmatic performance analysis and debugging.

Usage

⚠️ Agent-generated example - This is a preliminary API sketch and has not been finalized.

import { Agent } from '@strands-agents/sdk'

const agent = new Agent({
  tools: [myTool],
})

const result = await agent.invoke('Summarize this document')

// Access local traces from the result
console.log(result.traces)

Output:

Stop reason: endTurn
Traces: [
  LocalTrace {
    id: '71e7a8ef-7e57-4256-852f-f7f3e28def55',
    name: 'Cycle 1',
    rawName: 'cycle-1',
    parentId: null,
    startTime: 1772833466576,
    endTime: 1772833468451,
    duration: 1875,
    children: [ [LocalTrace], [LocalTrace] ],
    metadata: {},
    message: null
  },
  LocalTrace {
    id: '06242284-bce2-47d8-8e7b-e6d227a24b54',
    name: 'Cycle 2',
    rawName: 'cycle-2',
    parentId: null,
    startTime: 1772833468451,
    endTime: 1772833470576,
    duration: 2125,
    children: [ [LocalTrace] ],
    metadata: {},
    message: null
  }
]

Documentation

https://strandsagents.com/latest/documentation/docs/user-guide/observability-evaluation/metrics/

Reference

https://github.com/strands-agents/sdk-python/blob/main/src/strands/telemetry/metrics.py

Usage

No response

Documentation

https://strandsagents.com/latest/documentation/docs/user-guide/observability-evaluation/traces/

Reference

https://github.com/strands-agents/sdk-python/blob/main/src/strands/telemetry/metrics.py#L21