feat: added agent_invocations

[poshinchen]

Description

Currently, our AgentResult only contains accumulated_metrics, which is the total token count across all requests. This change adds the ability to track metrics for individual agent invocations, allowing users to access metrics for the latest request as well as historical invocations.

Users can access the metrics via the AgentResult once it's returned:

# Your agent
response = agent("calculate 10+2*10")

# Access the current (latest) invocation metrics
latest_invocation = response.metrics.latest_agent_invocation
if latest_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(response.metrics.get_summary())

Updated Metrics

1. agent_invocations: A list of AgentInvocation objects, where each invocation contains:

• cycles: List of metrics for each event loop cycle within that invocation
• Each cycle contains:
  • event_loop_cycle_id: Unique identifier for the event loop cycle
  • usage: Total token usage within that specific event loop cycle
• usage: Total token usage for the entire invocation (sum of all cycles)

3. latest_agent_invocation Property
   Convenient property to access the most recent (latest) agent invocation without needing to use agent_invocations[-1]

Related Issues

#1144

Documentation PR

TBD

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Example Output

The example below shows the agentResult.metrics (only the related fields) from three requests.

"agent_invocations": [
    {
      "cycles": [
        {
          "event_loop_cycle_id": "da707ee3-04a0-41e6-84e7-e6ba8a57053d",
          "usage": {
            "inputTokens": 1081,
            "outputTokens": 85,
            "totalTokens": 1166
          }
        },
        {
          "event_loop_cycle_id": "64a8b2b2-a677-4d47-9a1e-35ec737aae44",
          "usage": {
            "inputTokens": 1578,
            "outputTokens": 78,
            "totalTokens": 1656
          }
        }
      ],
      "usage": {
        "inputTokens": 2659,
        "outputTokens": 163,
        "totalTokens": 2822
      }
    },
    {
      "cycles": [
        {
          "event_loop_cycle_id": "51c214cc-8cd4-426b-a210-723cffdfc5c6",
          "usage": {
            "inputTokens": 1666,
            "outputTokens": 79,
            "totalTokens": 1745
          }
        },
        {
          "event_loop_cycle_id": "6d85ce7d-dd08-4efd-9665-12b8508b7c63",
          "usage": {
            "inputTokens": 2173,
            "outputTokens": 116,
            "totalTokens": 2289
          }
        }
      ],
      "usage": {
        "inputTokens": 3839,
        "outputTokens": 195,
        "totalTokens": 4034
      }
    }
  ],

[codecov]

Codecov Report

❌ Patch coverage is 88.23529% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/telemetry/metrics.py	87.87%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!