runner

Chapter 1: Runner

Welcome to the google-adk tutorial! This first chapter introduces the Runner, a fundamental component responsible for managing the entire lifecycle of an agent interaction within the framework.

Motivation and Use Case

Imagine you have built an agent, perhaps using an LLM, that can interact with users. How do you actually run this agent? You need a system that can:

1. Receive user input.
2. Maintain the conversation history (Session).
3. Manage persistent state (State).
4. Handle file uploads/downloads (Artifacts).
5. Potentially retrieve relevant long-term memories.
6. Invoke the correct agent logic.
7. Stream back the agent's response (Events).
8. In complex systems with multiple agents, decide which agent should handle the current turn.

The Runner is the orchestrator that handles all these tasks. It acts as the main entry point for interacting with any agent built using google-adk.

Central Use Case: A user sends a message ("What's the weather in London?") to your weather agent via an application. The application uses a Runner instance. The Runner retrieves the ongoing conversation session, appends the new user message, determines the weather agent should handle it, calls the agent's execution logic, and streams the resulting events (like the agent thinking, calling a weather tool, and finally responding) back to the application.

Key Concepts

• Orchestration: The Runner coordinates the flow of information and control between the user, the agent(s), and various backing services.
• Agent Execution: It provides methods like run_async (asynchronous, recommended for production) and run (synchronous wrapper for testing) to execute an agent turn. It also supports an experimental run_live for real-time streaming interactions (e.g., voice).
• Service Integration: It requires and utilizes services for managing different aspects of the interaction:
  • BaseSessionService: Manages conversational Sessions, including history (Events) and State.
  • BaseArtifactService: Handles storage and retrieval of binary data (e.g., files uploaded by the user or generated by the agent). (Optional)
  • BaseMemoryService: Provides access to long-term memory for the agent. (Optional)
• Agent Selection: In systems with a hierarchy of agents (an agent containing sub-agents), the Runner determines which agent is best suited to handle the current turn based on the session history and agent capabilities (using _find_agent_to_run). It checks if the last responding agent can "transfer" control back up the hierarchy if needed.
• Input Processing: Before invoking the agent, the Runner processes the incoming user message (new_message). This includes potentially saving any attached binary data as artifacts (if save_input_blobs_as_artifacts is true in the RunConfig) and appending the user message as an Event to the Session.
• Event Streaming: The run_async and run_live methods are asynchronous generators that yield Events as they occur during the agent's execution (e.g., intermediate thoughts, tool calls, final response parts).