Metrics are essential for understanding agent performance, optimizing behavior, and monitoring resource usage. The Strands Agents SDK provides comprehensive metrics tracking capabilities that give you visibility into how your agents operate.

## Overview

(( tab "Python" ))
The Strands Agents SDK automatically tracks key metrics during agent execution:

-   **Token usage**: Input tokens, output tokens, total tokens consumed, and cache metrics
-   **Performance metrics**: Latency and execution time measurements
-   **Tool usage**: Call counts, success rates, and execution times for each tool
-   **Event loop cycles**: Number of reasoning cycles and their durations

All these metrics are accessible through the [`AgentResult`](/pr-cms-3708/docs/api/python/strands.agent.agent_result#AgentResult) object that’s returned whenever you invoke an agent. They are available for local analysis. To export them to an observability backend, configure Strands telemetry as described in the [Traces](/pr-cms-3708/docs/user-guide/observability-evaluation/traces/index.md) documentation:

```python
from strands import Agent
from strands_tools import calculator

# Create an agent with tools
agent = Agent(tools=[calculator])

# Invoke the agent with a prompt and get an AgentResult
result = agent("What is the square root of 144?")

# Access metrics through the AgentResult
print(f"Total tokens: {result.metrics.accumulated_usage['totalTokens']}")
print(f"Execution time: {sum(result.metrics.cycle_durations):.2f} seconds")
print(f"Tools used: {list(result.metrics.tool_metrics.keys())}")

# Cache metrics (when available)
if 'cacheReadInputTokens' in result.metrics.accumulated_usage:
    print(f"Cache read tokens: {result.metrics.accumulated_usage['cacheReadInputTokens']}")
if 'cacheWriteInputTokens' in result.metrics.accumulated_usage:
    print(f"Cache write tokens: {result.metrics.accumulated_usage['cacheWriteInputTokens']}")
```

The `metrics` attribute of `AgentResult` (an instance of [`EventLoopMetrics`](/pr-cms-3708/docs/api/python/strands.telemetry.metrics)) provides comprehensive performance metric data about the agent’s execution, while other attributes like `stop_reason`, `message`, and `state` provide context about the agent’s response. This document explains the metrics available in the agent’s response and how to interpret them.
(( /tab "Python" ))

(( tab "TypeScript" ))
The TypeScript SDK automatically tracks key metrics during agent execution through the `AgentMetrics` class:

-   **Token usage**: Input tokens, output tokens, total tokens consumed, and cache metrics
-   **Performance metrics**: Latency and execution time measurements
-   **Tool usage**: Call counts, success rates, and execution times for each tool
-   **Event loop cycles**: Number of reasoning cycles and their durations

All these metrics are accessible through the `AgentResult` object returned when you invoke an agent:

```typescript
const agent = new Agent({
  tools: [notebook],
})

const result = await agent.invoke('What is the square root of 144?')

// Access metrics through the AgentResult
if (result.metrics) {
  console.log(`Total tokens: ${result.metrics.accumulatedUsage.totalTokens}`)
  console.log(`Total duration: ${result.metrics.totalDuration}ms`)
  console.log(`Tools used: ${Object.keys(result.metrics.toolMetrics)}`)

  // Cache metrics (when available)
  if (result.metrics.accumulatedUsage.cacheReadInputTokens) {
    console.log(
      `Cache read tokens: ${result.metrics.accumulatedUsage.cacheReadInputTokens}`
    )
  }
  if (result.metrics.accumulatedUsage.cacheWriteInputTokens) {
    console.log(
      `Cache write tokens: ${result.metrics.accumulatedUsage.cacheWriteInputTokens}`
    )
  }
}
```

The `metrics` property on `AgentResult` is an instance of `AgentMetrics` that provides comprehensive performance data about the agent’s execution.
(( /tab "TypeScript" ))

## Agent Loop Metrics

(( tab "Python" ))
The [`EventLoopMetrics`](/pr-cms-3708/docs/api/python/strands.telemetry.metrics#EventLoopMetrics) class aggregates metrics across the entire event loop execution cycle, providing a complete picture of your agent’s performance. It tracks cycle counts, tool usage, execution durations, and token consumption across all model invocations.

Key metrics include:

-   **Cycle tracking**: Number of event loop cycles and their individual durations
-   **Tool metrics**: Detailed performance data for each tool used during execution
-   **Agent invocations**: List of agent invocations, each containing cycles and usage data for that specific invocation
-   **Accumulated usage**: Aggregated token counts (input, output, total, and cache metrics) across all agent invocations
-   **Accumulated metrics**: Latency measurements in milliseconds for all model requests
-   **Execution traces**: Detailed trace information for performance analysis

**Agent Invocations**

The `agent_invocations` property is a list of [`AgentInvocation`](/pr-cms-3708/docs/api/python/strands.telemetry.metrics#AgentInvocation) objects that track metrics for each agent invocation (request). Each `AgentInvocation` contains:

-   **cycles**: A list of `EventLoopCycleMetric` objects, each representing a single event loop cycle with its ID and token usage
-   **usage**: Accumulated token usage for this specific invocation across all its cycles

This allows you to track metrics at both the individual invocation level and across all invocations:

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])

# First invocation
result1 = agent("What is 5 + 3?")

# Second invocation
result2 = agent("What is the square root of 144?")

# Access metrics for the latest invocation
latest_invocation = result2.metrics.latest_agent_invocation
cycles = latest_invocation.cycles
usage = latest_invocation.usage

# Or access all invocations
for invocation in response.metrics.agent_invocations:
    print(f"Invocation usage: {invocation.usage}")
    for cycle in invocation.cycles:
        print(f"  Cycle {cycle.event_loop_cycle_id}: {cycle.usage}")

# Or print the summary (includes all invocations)
print(result2.metrics.get_summary())
```

For a complete list of attributes and their types, see the [`EventLoopMetrics` API reference](/pr-cms-3708/docs/api/python/strands.telemetry.metrics#EventLoopMetrics).
(( /tab "Python" ))

(( tab "TypeScript" ))
The `AgentMetrics` class aggregates metrics across the entire agent loop execution, providing a complete picture of your agent’s performance. It tracks cycle counts, tool usage, execution durations, and token consumption across all model invocations.

Key metrics include:

-   **Cycle tracking**: Number of event loop cycles and their individual durations via `cycleCount`, `totalDuration`, and `averageCycleTime`
-   **Tool metrics**: Detailed performance data for each tool used during execution
-   **Agent invocations**: List of agent invocations, each containing cycles and usage data for that specific invocation
-   **Accumulated usage**: Aggregated token counts (input, output, total, and cache metrics) across all agent invocations
-   **Accumulated metrics**: Latency measurements in milliseconds for all model requests

**Agent Invocations**

The `agentInvocations` property is a list of `InvocationMetricsData` objects that track metrics for each agent invocation (request). Each invocation contains:

-   **cycles**: A list of `AgentLoopMetricsData` objects, each representing a single event loop cycle with its ID, duration, and token usage
-   **usage**: Accumulated token usage for this specific invocation across all its cycles

This allows you to track metrics at both the individual invocation level and across all invocations:

```typescript
const agent = new Agent({
  tools: [notebook],
})

// First invocation
const _result1 = await agent.invoke('What is 5 + 3?')

// Second invocation
const result2 = await agent.invoke('What is the square root of 144?')

// Access metrics for the latest invocation
if (result2.metrics) {
  const latest = result2.metrics.latestAgentInvocation
  if (latest) {
    console.log(`Invocation usage: ${JSON.stringify(latest.usage)}`)
    for (const cycle of latest.cycles) {
      console.log(`  Cycle ${cycle.cycleId}: ${JSON.stringify(cycle.usage)}`)
    }
  }

  // Access all invocations
  for (const invocation of result2.metrics.agentInvocations) {
    console.log(`Invocation usage: ${JSON.stringify(invocation.usage)}`)
    for (const cycle of invocation.cycles) {
      console.log(`  Cycle ${cycle.cycleId}: ${JSON.stringify(cycle.usage)}`)
    }
  }

  // Computed metrics
  console.log(`Cycle count: ${result2.metrics.cycleCount}`)
  console.log(`Total duration: ${result2.metrics.totalDuration}ms`)
  console.log(`Average cycle time: ${result2.metrics.averageCycleTime}ms`)
}
```
(( /tab "TypeScript" ))

## Tool Metrics

(( tab "Python" ))
For each tool used by the agent, detailed metrics are collected in the `tool_metrics` dictionary. Each entry is an instance of [`ToolMetrics`](/pr-cms-3708/docs/api/python/strands.telemetry.metrics#ToolMetrics) that tracks the tool’s performance throughout the agent’s execution.

Tool metrics provide insights into:

-   **Call statistics**: Total number of calls, successful executions, and errors
-   **Execution time**: Total and average time spent executing the tool
-   **Success rate**: Percentage of successful tool invocations
-   **Tool reference**: Information about the specific tool being tracked

These metrics help you identify performance bottlenecks, tools with high error rates, and opportunities for optimization. For complete details on all available properties, see the [`ToolMetrics` API reference](/pr-cms-3708/docs/api/python/strands.telemetry.metrics#ToolMetrics).
(( /tab "Python" ))

(( tab "TypeScript" ))
For each tool used by the agent, detailed metrics are collected in the `toolMetrics` dictionary. Each entry is a `ToolMetricsData` object that tracks the tool’s performance throughout the agent’s execution.

Tool metrics provide insights into:

-   **Call statistics**: Total number of calls, successful executions, and errors
-   **Execution time**: Total time spent executing the tool
-   **Computed statistics**: The `toolUsage` getter adds computed `averageTime` and `successRate` fields

These metrics help you identify performance bottlenecks, tools with high error rates, and opportunities for optimization.
(( /tab "TypeScript" ))

## Example Metrics Summary Output

(( tab "Python" ))
The Strands Agents SDK provides a convenient `get_summary()` method on the `EventLoopMetrics` class that gives you a comprehensive overview of your agent’s performance in a single call. This method aggregates all the metrics data into a structured dictionary that’s easy to analyze or export.

Let’s look at the output from calling `get_summary()` on the metrics from our calculator example from the beginning of this document:

```python
result = agent("What is the square root of 144?")
print(result.metrics.get_summary())
```

```python
{
  "total_cycles": 1,
  "total_duration": 2.6939949989318848,
  "average_cycle_time": 2.6939949989318848,
  "tool_usage": {},
  "traces": [{
      "id": "e1264f67-81c9-4bd7-8cab-8f69c53e85f1",
      "name": "Cycle 1",
      "raw_name": None,
      "parent_id": None,
      "start_time": 1767110391.614767,
      "end_time": 1767110394.308762,
      "duration": 2.6939949989318848,
      "children": [{
          "id": "0de6d280-14ff-423b-af80-9cc823c8c3a1",
          "name": "stream_messages",
          "raw_name": None,
          "parent_id": "e1264f67-81c9-4bd7-8cab-8f69c53e85f1",
          "start_time": 1767110391.614809,
          "end_time": 1767110394.308734,
          "duration": 2.693924903869629,
          "children": [],
          "metadata": {},
          "message": {
              "role": "assistant",
              "content": [{
                  "text": "The square root of 144 is 12.\n\nThis is because 12 × 12 = 144."
              }]
          }
      }],
      "metadata": {},
      "message": None
  }],
  "accumulated_usage": {
      "inputTokens": 16,
      "outputTokens": 29,
      "totalTokens": 45
  },
  "accumulated_metrics": {
      "latencyMs": 1799
  },
  "agent_invocations": [{
      "usage": {
          "inputTokens": 16,
          "outputTokens": 29,
          "totalTokens": 45
      },
      "cycles": [{
          "event_loop_cycle_id": "ed854916-7eca-4317-a3f3-1ffcc03ee3ab",
          "usage": {
              "inputTokens": 16,
              "outputTokens": 29,
              "totalTokens": 45
          }
      }]
  }]
}
```

This summary provides a complete picture of the agent’s execution, including cycle information, token usage, tool performance, and detailed execution traces.
(( /tab "Python" ))

(( tab "TypeScript" ))
The `AgentMetrics` class implements `toJSON()`, so you can serialize the complete metrics snapshot with `JSON.stringify()`. This gives you a comprehensive overview of your agent’s performance in a single call:

```typescript
const agent = new Agent({
  tools: [notebook],
})

const result = await agent.invoke('What is the square root of 144?')

// Serialize metrics to JSON
console.log(JSON.stringify(result?.metrics, null, 2))
```

```json
{
  "cycleCount": 1,
  "accumulatedUsage": {
    "inputTokens": 16,
    "outputTokens": 29,
    "totalTokens": 45
  },
  "accumulatedMetrics": {
    "latencyMs": 1799
  },
  "agentInvocations": [
    {
      "usage": {
        "inputTokens": 16,
        "outputTokens": 29,
        "totalTokens": 45
      },
      "cycles": [
        {
          "cycleId": "cycle-1",
          "duration": 2694,
          "usage": {
            "inputTokens": 16,
            "outputTokens": 29,
            "totalTokens": 45
          }
        }
      ]
    }
  ],
  "toolMetrics": {}
}
```

This summary provides a complete picture of the agent’s execution, including cycle information, token usage, and tool performance.
(( /tab "TypeScript" ))

## Local Execution Traces

(( tab "Python" ))
In addition to aggregate metrics, the Strands Agents SDK automatically collects **local execution traces** — lightweight, in-memory timing trees that capture the hierarchy and duration of operations within the agent loop. These traces are always collected regardless of OpenTelemetry configuration and are returned directly in the `AgentResult`.

Each trace represents a cycle in the agent loop, with child traces for model invocations and tool calls:

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])
result = agent("What is 15 * 8 + 42?")

# Traces are included in the summary output
print(result.metrics.get_summary())
```

Each trace contains:

-   **name**: Human-readable label (e.g., “Cycle 1”, “stream\_messages”, “Tool: calculator”)
-   **duration**: Execution time in seconds
-   **children**: Nested traces for operations within the cycle
-   **metadata**: Associated data like `cycleId`, `toolUseId`, and `toolName`
-   **message**: The model output message (for model invocation traces)

Traces are included in the `get_summary()` output, giving you a complete hierarchical view of agent execution alongside aggregate metrics.
(( /tab "Python" ))

(( tab "TypeScript" ))
In addition to aggregate metrics, the Strands Agents SDK automatically collects **local execution traces** — lightweight, in-memory timing trees that capture the hierarchy and duration of operations within the agent loop. These traces are always collected regardless of OpenTelemetry configuration and are returned directly in `AgentResult.traces`.

Each trace is an `AgentTrace` instance representing a cycle in the agent loop, with child traces for model invocations and tool calls:

```typescript
const agent = new Agent({
  tools: [notebook],
})

const result = await agent.invoke('What is 15 * 8 + 42?')

// Access traces directly from the result
console.log(JSON.stringify(result.traces))
```

Each `AgentTrace` contains:

-   **name**: Human-readable label (e.g., “Cycle 1”, “stream\_messages”, “Tool: calculator”)
-   **duration**: Execution time in milliseconds
-   **children**: Nested `AgentTrace` instances for operations within the cycle
-   **metadata**: Associated data like `cycleId`, `toolUseId`, and `toolName`
-   **message**: The model output message (for model invocation traces)

Traces are separate from `AgentMetrics` and are accessed via `result.traces`. Note that `AgentResult.toJSON()` excludes traces and metrics by default to keep API responses lean — access them directly via `result.traces` and `result.metrics`.
(( /tab "TypeScript" ))

## Best Practices

1.  **Monitor Token Usage**: Keep track of token usage to ensure you stay within limits and optimize costs. Set up alerts for when token usage approaches predefined thresholds to avoid unexpected costs.
    
2.  **Analyze Performance**: Review performance metrics across agents, tools, and execution stages to identify high error rates and latency bottlenecks. Calculate p50, p90, and p99 latency per stage and end-to-end over a rolling window aligned with your service level objectives (SLOs). Prioritize optimizing stages with both a significant contribution to end-to-end latency and meaningful optimization potential. For more information, see the [AWS Well-Architected Framework Agentic AI Lens AGENTPERF01-BP03](https://docs.aws.amazon.com/wellarchitected/latest/agentic-ai-lens/agentperf01-bp03.html).
    
3.  **Track Cycle Efficiency**: Monitor how many iterations the agent needed and how long each took. Agents that require many cycles may benefit from improved prompting or tool design.
    
4.  **Benchmark Latency Metrics**: Monitor latency values to establish performance baselines. Compare these metrics across different agent configurations to identify optimal setups.
    
5.  **Regular Metrics Reviews**: Schedule periodic reviews of agent metrics to identify trends and opportunities for optimization. Look for gradual changes in performance that might indicate drift in tool behavior or model responses.

## Related pages

- [Evaluating Remote Traces](/pr-cms-3708/docs/user-guide/evals-sdk/how-to/trace_providers/index.md) (1 shared tag)
- [Observability](/pr-cms-3708/docs/user-guide/observability-evaluation/observability/index.md) (1 shared tag)
- [Task Decorator](/pr-cms-3708/docs/user-guide/evals-sdk/how-to/eval_task/index.md) (1 shared tag)
- [Traces](/pr-cms-3708/docs/user-guide/observability-evaluation/traces/index.md) (1 shared tag)
- [Logging](/pr-cms-3708/docs/user-guide/observability-evaluation/logs/index.md) (1 shared tag)
- [Operating Agents in Production](/pr-cms-3708/docs/user-guide/deploy/operating-agents-in-production/index.md) (1 shared tag)
- [Root Cause Analysis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/root_cause_analysis/index.md) (1 shared tag)
- [Session Diagnosis](/pr-cms-3708/docs/user-guide/evals-sdk/detectors/diagnosis/index.md) (1 shared tag)
- [PII Redaction](/pr-cms-3708/docs/user-guide/safety-security/pii-redaction/index.md) (1 shared tag)
- [AgentCore Evaluation Dashboard Configuration](/pr-cms-3708/docs/user-guide/evals-sdk/how-to/agentcore_evaluation_dashboard/index.md) (1 shared tag)