invocationcontext

Chapter 9: InvocationContext

In the previous chapter, we explored BaseLlmFlow, the engine that orchestrates the complex interaction between an Agent (BaseAgent / LlmAgent) and the BaseLlm, especially when handling Tools (BaseTool). We saw that the flow logic often needs access to the current session, services, agent configuration, and more. Passing all these elements individually down the call stack (Runner -> Agent -> Flow -> Processors -> Callbacks -> Tools) would be cumbersome and error-prone. This chapter introduces InvocationContext, the object designed to solve this by encapsulating all necessary information for a single agent turn (invocation).

Motivation and Use Case

Consider a single turn initiated by a user message. Processing this message might involve:

• Retrieving the Session (Session / BaseSessionService) history and State.
• Knowing which specific Agent (BaseAgent / LlmAgent) is currently active (especially in hierarchical setups).
• Accessing services like artifact_service or session_service.
• Applying runtime configurations (RunConfig).
• Tracking unique identifiers for logging and tracing.
• Signaling when the turn should end prematurely.

Instead of passing numerous parameters through every function call, InvocationContext acts as a "carrier" object. It bundles all this context together and is passed down through the execution hierarchy. This promotes cleaner code, ensures necessary information is available where needed without relying on global state, and simplifies the interfaces of core components like agents, flows, and tools.

Central Use Case: The Runner receives a user message for a specific session.

1. The Runner creates an InvocationContext instance, populating it with the fetched Session, references to the configured services (session_service, etc.), the root agent, the user_content, a unique invocation_id, and the RunConfig.
2. The Runner determines the correct agent to run (e.g., agent_A) and calls agent_A.run_async(invocation_context).
3. Inside agent_A, if it needs to call a sub-agent (agent_B), it creates a new InvocationContext (usually a copy of the parent's, updating agent to agent_B and appending to branch) and calls agent_B.run_async(sub_context).
4. If agent_B (an LlmAgent) uses its internal BaseLlmFlow, it passes its InvocationContext (sub_context) to the flow.
5. If the flow triggers a Tool (BaseTool), it creates a ToolContext (which wraps the InvocationContext) and passes it to the tool's run_async.
6. Throughout this flow, any component (agent, flow, tool, callback) can access, for example, ctx.session.state or ctx.session_service via the context object it received.