[FEATURE] Track agent.messages token size

[kmukher-amz]

Problem Statement

Currently strands has accumulated token usage which keeps track of all the tokens used in the current turn. However, it is often useful to know what the token size of the current agent context (agent.messages) is. This value can be used for proactive conversation management (current tokens > threshold) or just to expose to a downstream user.
Today one option is to use count_tokens provided by bedrock but this tends to eat up TPM limits pretty fast as well as adding to the latency of the over-all turn.

Proposed Solution

Add another tracked metric in event logs that keeps track of current agent context token size.

Use Case

For proactive memory/context management (to trigger summarization) and to expose this information to a downstream user.

Alternatives Solutions

Today one option is to use count_tokens provided by bedrock but this tends to eat up TPM limits pretty fast as well as adding to the latency of the over-all turn.

Additional Context

No response

[kevmyung]

Proposed Design: Context Size Metrics via Existing Cycle Usage Data

Hi, I'd like to propose a design for this feature and would appreciate feedback before submitting a PR.

Approach

• We can leverage the existing cycles[].usage data that's already captured in EventLoopMetrics. Each LLM call returns inputTokens in its response metadata, and this is already stored per-cycle.

The key insight is:

- cycles[0].usage["inputTokens"] = initial context size (before any tool executions)
- cycles[-1].usage["inputTokens"] = final context size (after all tool executions)

Proposed API

• Add properties to AgentInvocation:

@property
def initial_input_tokens(self) -> int:
    """Input tokens from the first LLM call (initial context size)."""
    return self.cycles[0].usage["inputTokens"] if self.cycles else 0

@property
def final_input_tokens(self) -> int:
    """Input tokens from the last LLM call (final context size).
    
    This is the actual context size, useful for compaction threshold decisions.
    """
    return self.cycles[-1].usage["inputTokens"] if self.cycles else 0

@property
def context_growth_tokens(self) -> int:
    """Context growth during this invocation (final - initial)."""
    return self.final_input_tokens - self.initial_input_tokens

• Add convenience properties to EventLoopMetrics for quick access to the latest invocation's metrics.

Benefits

1. No additional API calls: Uses values already returned by the LLM in response metadata
2. No latency impact: Zero overhead since data is already captured
3. Model agnostic: Works across all providers (Bedrock, OpenAI, Gemini, Anthropic, etc.) since all providers normalize to the standard Usage type with
   inputTokens
4. No external dependencies: Unlike token estimation approaches, this uses exact values from the model
5. Backward compatible: Adds properties without changing existing data structures

Use Case Example

agent = Agent(tools=[...])
result = agent("Do something with tools")

# Get actual context size for threshold decisions
context_size = agent.event_loop_metrics.final_input_tokens

if context_size > COMPACTION_THRESHOLD:
    trigger_summarization()

Verification

• I've verified that all major providers (Bedrock, OpenAI, Gemini) normalize their usage responses to the same Usage TypedDict format, ensuring this approach works consistently across models.

Would this design align with what you had in mind? Happy to submit a PR if this looks good.