strands.agent.invocation_context
Handle to the request an agent call belongs to, carrying its limits and usage.
InvocationContextUsage
Section titled “InvocationContextUsage”class InvocationContextUsage(Usage)Defined in: src/strands/agent/invocation_context.py:16
What the work in an :class:InvocationContext has used.
Its turns and the token usage of every model call, including nested and auxiliary calls. The token keys
keep the provider casing of :class:~strands.types.event_loop.Usage.
Attributes:
turns_taken- Turns taken in the context, including its nested calls.
InvocationContext
Section titled “InvocationContext”class InvocationContext()Defined in: src/strands/agent/invocation_context.py:33
Handle to the request an object belongs to.
A top-level invoke_async() / stream_async() call starts a request, and the SDK
attaches its handle to the hook events, tool contexts, and extension points it hands out
and to the call’s result. Pass it as invocation_context to a later call to run that
call as a nested call in the same request, sharing its limits and usage, for example to
continue a previous call’s budget.
Every nested call that joins the request shares one instance. A nested call that sets its
own limits, and an auxiliary call, get a child instance instead. A child adds its usage
to its parent; a nested call’s child is also bound by the parent’s limits, while no limits
apply to an auxiliary call.
Notes:
Only the SDK creates instances; pass limits= to a top-level call to start a limited
request. Treat usage as read-only: mutating it is unsupported.
__init__
Section titled “__init__”def __init__() -> NoneDefined in: src/strands/agent/invocation_context.py:57
Reject direct construction.
Raises:
TypeError- Always; the SDK creates every instance.
@propertydef usage() -> InvocationContextUsageDefined in: src/strands/agent/invocation_context.py:66
What the work in this context has used so far.
It keeps growing while that work runs, including background tasks the request started.