Skip to content

strands.types.event_loop

Event loop-related type definitions for the SDK.

class Usage(TypedDict)

Defined in: src/strands/types/event_loop.py:8

Token usage information for model interactions.

Providers differ on whether inputTokens includes cached tokens. Some count cache reads and writes inside inputTokens; others count them only in cacheReadInputTokens and cacheWriteInputTokens. totalTokens always includes cached tokens, so for a single model call: if inputTokens + outputTokens == totalTokens, inputTokens already includes the cache fields; otherwise, total input is inputTokens + cacheReadInputTokens + cacheWriteInputTokens. Adding the cache fields to an inputTokens that already includes them counts cached tokens twice.

Custom model providers should include cached tokens in inputTokens (matching the OpenTelemetry GenAI conventions), so that totalTokens == inputTokens + outputTokens.

Attributes:

  • inputTokens - Number of input tokens, as the model provider counts them. May or may not include cached tokens, depending on the provider.
  • outputTokens - Number of tokens that the model generated for the request.
  • totalTokens - Total number of tokens processed, including any cached input tokens.
  • cacheReadInputTokens - Number of input tokens read from cache (optional).
  • cacheWriteInputTokens - Number of input tokens written to cache (optional).
class Metrics(TypedDict)

Defined in: src/strands/types/event_loop.py:37

Performance metrics for model interactions.

Attributes:

  • latencyMs int - Latency of the model request in milliseconds.
  • timeToFirstByteMs int - Latency from sending model request to first content chunk (contentBlockDelta or contentBlockStart) from the model in milliseconds.

Reason for the model ending its response generation.

  • “cancelled”: Agent execution was cancelled via agent.cancel()
  • “checkpoint”: Agent paused for durable checkpoint persistence
  • “content_filtered”: Content was filtered due to policy violation
  • “end_turn”: Normal completion of the response
  • “guardrail_intervened”: Guardrail system intervened
  • “interrupt”: Agent was interrupted for human input
  • “limit_output_tokens”: Agent loop stopped because the limits["output_tokens"] cap was reached
  • “limit_structured_output_attempts”: Agent loop stopped because the limits["structured_output_attempts"] cap was reached
  • “limit_total_tokens”: Agent loop stopped because the limits["total_tokens"] cap was reached
  • “limit_turns”: Agent loop stopped because the limits["turns"] cap was reached
  • “max_tokens”: The model provider’s per-call output cap was reached
  • “stop_sequence”: Stop sequence encountered
  • “tool_use”: Model requested to use a tool