From 518f6e2190d1e4e3179e41b95ebf27c1afbcceee Mon Sep 17 00:00:00 2001 From: Lavi Nigam Date: Thu, 10 Apr 2025 10:54:20 -0700 Subject: [PATCH] tutorial-update-and-fixes --- docs/get-started/tutorial.md | 794 ++++--- examples/python/notebooks/adk_tutorial.ipynb | 2099 ++++++++++++++++++ 2 files changed, 2552 insertions(+), 341 deletions(-) create mode 100644 examples/python/notebooks/adk_tutorial.ipynb diff --git a/docs/get-started/tutorial.md b/docs/get-started/tutorial.md index 69411d69f9..6530a5dc3a 100644 --- a/docs/get-started/tutorial.md +++ b/docs/get-started/tutorial.md @@ -1,8 +1,9 @@ # Build Your First Intelligent Agent Team: A Progressive Weather Bot with ADK -If you've completed the [Quickstart](quickstart.md), you've seen how ADK simplifies building basic LLM-powered applications. Now, you're ready to dive deeper and construct a more sophisticated, **multi-agent system**. -This tutorial takes your ADK skills to the next level. We'll embark on building a **Weather Bot agent team**, progressively layering advanced features onto a simple foundation. Starting with a single agent that can look up weather, we will incrementally add capabilities like: +This tutorial extends from the [Quickstart example](https://google.github.io/adk-docs/get-started/quickstart/) for [Agent Development Kit](https://google.github.io/adk-docs/get-started/). Now, you're ready to dive deeper and construct a more sophisticated, **multi-agent system**. + +We'll embark on building a **Weather Bot agent team**, progressively layering advanced features onto a simple foundation. Starting with a single agent that can look up weather, we will incrementally add capabilities like: * Leveraging different AI models (Gemini, GPT, Claude). * Designing specialized sub-agents for distinct tasks (like greetings and farewells). @@ -25,7 +26,6 @@ As a reminder, ADK is a Python framework designed to streamline the development * ✅ **Agent Delegation & Collaboration:** Designing specialized sub-agents and enabling automatic routing (`auto flow`) of user requests to the most appropriate agent within a team. * ✅ **Session State for Memory:** Utilizing `Session State` and `ToolContext` to enable agents to remember information across conversational turns, leading to more contextual interactions. * ✅ **Safety Guardrails with Callbacks:** Implementing `before_model_callback` and `before_tool_callback` to inspect, modify, or block requests/tool usage based on predefined rules, enhancing application safety and control. -* ⏳ *(Coming Soon)*: Techniques for providing contextual information to agents. **End State Expectation:** @@ -40,6 +40,83 @@ By completing this tutorial, you will have built a functional multi-agent Weathe **Ready to build your agent team? Let's dive in\!** +## Step 0: Setup and Installation + +### Library Installation + +``` + +!pip install google-adk -q +!pip install litellm -q + +print("Installation complete.") +``` + +### Import Library + +``` +import os +import asyncio +from google.adk.agents import Agent +from google.adk.models.lite_llm import LiteLlm # For multi-model support +from google.adk.sessions import InMemorySessionService +from google.adk.runners import Runner +from google.genai import types # For creating message Content/Parts + +import warnings +# Ignore all warnings +warnings.filterwarnings("ignore") + +import logging +logging.basicConfig(level=logging.ERROR) + +print("Libraries imported.") +``` + +### Setup API Keys + +``` + +# --- IMPORTANT: Replace placeholders with your real API keys --- + +# Gemini API Key (Get from Google AI Studio: https://aistudio.google.com/app/apikey) +os.environ["GOOGLE_API_KEY"] = "YOUR_GOOGLE_API_KEY" # <--- REPLACE + +# OpenAI API Key (Get from OpenAI Platform: https://platform.openai.com/api-keys) +os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY' # <--- REPLACE + +# Anthropic API Key (Get from Anthropic Console: https://console.anthropic.com/settings/keys) +os.environ['ANTHROPIC_API_KEY'] = 'YOUR_ANTHROPIC_API_KEY' # <--- REPLACE + + +# --- Verify Keys (Optional Check) --- +print("API Keys Set:") +print(f"Google API Key set: {'Yes' if os.environ.get('GOOGLE_API_KEY') and os.environ['GOOGLE_API_KEY'] != 'YOUR_GOOGLE_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}") +print(f"OpenAI API Key set: {'Yes' if os.environ.get('OPENAI_API_KEY') and os.environ['OPENAI_API_KEY'] != 'YOUR_OPENAI_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}") +print(f"Anthropic API Key set: {'Yes' if os.environ.get('ANTHROPIC_API_KEY') and os.environ['ANTHROPIC_API_KEY'] != 'YOUR_ANTHROPIC_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}") + +# Configure ADK to use API keys directly (not Vertex AI for this multi-model setup) +os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "False" + + +# @markdown **Security Note:** It's best practice to manage API keys securely (e.g., using Colab Secrets or environment variables) rather than hardcoding them directly in the notebook. Replace the placeholder strings above. + +``` + +### Define Model Constants for easier use + +``` + +MODEL_GEMINI_2_0_FLASH = "gemini-2.0-flash-exp" + +# Note: Specific model names might change. Refer to LiteLLM/Provider documentation. +MODEL_GPT_4O = "openai/gpt-4o" +MODEL_CLAUDE_SONNET = "anthropic/claude-3-sonnet-20240229" + + +print("\nEnvironment configured.") +``` + ## Step 1: Your First Agent \- Basic Weather Lookup Let's begin by building the fundamental component of our Weather Bot: a single agent capable of performing a specific task – looking up weather information. This involves creating two core pieces: @@ -49,7 +126,7 @@ Let's begin by building the fundamental component of our Weather Bot: a single a --- -**1\. Define the Tool (`get_weather`)** +### **1\. Define the Tool** In ADK, **Tools** are the building blocks that give agents concrete capabilities beyond just text generation. They are typically regular Python functions that perform specific actions, like calling an API, querying a database, or performing calculations. @@ -102,7 +179,7 @@ print(get_weather("Paris")) --- -**2\. Define the Agent (`weather_agent`)** +### **2\. Define the Agent** Now, let's create the **Agent** itself. An `Agent` in ADK orchestrates the interaction between the user, the LLM, and the available tools. @@ -141,7 +218,7 @@ print(f"Agent '{weather_agent.name}' created using model '{AGENT_MODEL}'.") --- -**3\. Setup Runner and Session Service** +### **3\. Setup Runner and Session Service** To manage conversations and execute the agent, we need two more components: @@ -181,7 +258,7 @@ print(f"Runner created for agent '{runner.agent.name}'.") --- -**4\. Interact with the Agent** +### **4\. Interact with the Agent** We need a way to send messages to our agent and receive its responses. Since LLM calls and tool executions can take time, ADK's `Runner` operates asynchronously. @@ -231,7 +308,7 @@ async def call_agent_async(query: str): --- -**5\. Run the Conversation** +### **5\. Run the Conversation** Finally, let's test our setup by sending a few queries to the agent. We wrap our `async` calls in a main `async` function and run it using `await`. @@ -285,22 +362,22 @@ In the next step, we'll explore how to easily switch the underlying Language Mod In Step 1, we built a functional Weather Agent powered by a specific Gemini model. While effective, real-world applications often benefit from the flexibility to use *different* Large Language Models (LLMs). Why? -* **Performance:** Some models excel at specific tasks (e.g., coding, reasoning, creative writing). -* **Cost:** Different models have varying price points. -* **Capabilities:** Models offer diverse features, context window sizes, and fine-tuning options. +* **Performance:** Some models excel at specific tasks (e.g., coding, reasoning, creative writing). +* **Cost:** Different models have varying price points. +* **Capabilities:** Models offer diverse features, context window sizes, and fine-tuning options. * **Availability/Redundancy:** Having alternatives ensures your application remains functional even if one provider experiences issues. ADK makes switching between models seamless through its integration with the [**LiteLLM**](https://github.com/BerriAI/litellm) library. LiteLLM acts as a consistent interface to over 100 different LLMs. **In this step, we will:** -1. Learn how to configure an ADK `Agent` to use models from providers like OpenAI (GPT) and Anthropic (Claude) using the `LiteLlm` wrapper. -2. Create new instances of our Weather Agent, each backed by a different LLM. +1. Learn how to configure an ADK `Agent` to use models from providers like OpenAI (GPT) and Anthropic (Claude) using the `LiteLlm` wrapper. +2. Define, configure (with their own sessions and runners), and immediately test instances of our Weather Agent, each backed by a different LLM. 3. Interact with these different agents to observe potential variations in their responses, even when using the same underlying tool. --- -**1\. Import `LiteLlm`** +### **1\. Import `LiteLlm`** We imported this during the initial setup (Step 0), but it's the key component for multi-model support: @@ -311,26 +388,36 @@ from google.adk.models.lite_llm import LiteLlm --- -**2\. Define Agents with Different Models** +### **2\. Define and Test Multi-Model Agents** -Instead of passing only a model name string (which defaults to Google's Gemini models, either directly or via Vertex AI depending on your environment setup), we wrap the desired model identifier string within the `LiteLlm` class. +Instead of passing only a model name string (which defaults to Google's Gemini models), we wrap the desired model identifier string within the `LiteLlm` class. * **Key Concept: `LiteLlm` Wrapper:** The `LiteLlm(model="provider/model_name")` syntax tells ADK to route requests for this agent through the LiteLLM library to the specified model provider. -Make sure you have configured the necessary API keys for OpenAI and Anthropic in Step 0\. +Make sure you have configured the necessary API keys for OpenAI and Anthropic in Step 0. We'll use the `call_agent_async` function (defined earlier, which now accepts `runner`, `user_id`, and `session_id`) to interact with each agent immediately after its setup. + +Each block below will: +* Define the agent using a specific LiteLLM model (`MODEL_GPT_4O` or `MODEL_CLAUDE_SONNET`). +* Create a *new, separate* `InMemorySessionService` and session specifically for that agent's test run. This keeps the conversation histories isolated for this demonstration. +* Create a `Runner` configured for the specific agent and its session service. +* Immediately call `call_agent_async` to send a query and test the agent. + +**Best Practice:** Use constants for model names (like `MODEL_GPT_4O`, `MODEL_CLAUDE_SONNET` defined in Step 0) to avoid typos and make code easier to manage. -**Best Practice:** Use constants for model names (like `MODEL_GPT_4O`, `MODEL_CLAUDE_SONNET` defined in Step 0\) to avoid typos and make code easier to manage. +**Error Handling:** We wrap the agent definitions in `try...except` blocks. This prevents the entire code cell from failing if an API key for a specific provider is missing or invalid, allowing the tutorial to proceed with the models that *are* configured. -**Error Handling:** We'll wrap the agent definitions in `try...except` blocks. This prevents the entire code cell from failing if an API key for a specific provider is missing or invalid, allowing the tutorial to proceed with the models that *are* configured. +First, let's create and test the agent using OpenAI's GPT-4o. ```py -# @title Define Agents with Different Models (GPT & Claude) +# @title Define and Test GPT Agent # Make sure 'get_weather' function from Step 1 is defined in your environment. +# Make sure 'call_agent_async' is defined from earlier. # --- Agent using GPT-4o --- weather_agent_gpt = None # Initialize to None runner_gpt = None # Initialize runner to None + try: weather_agent_gpt = Agent( name="weather_agent_gpt", @@ -343,20 +430,56 @@ try: tools=[get_weather], # Re-use the same tool ) print(f"Agent '{weather_agent_gpt.name}' created using model '{MODEL_GPT_4O}'.") - # Create a runner specific to this agent + + # InMemorySessionService is simple, non-persistent storage for this tutorial. + session_service_gpt = InMemorySessionService() # Create a dedicated service + + # Define constants for identifying the interaction context + APP_NAME_GPT = "weather_tutorial_app_gpt" # Unique app name for this test + USER_ID_GPT = "user_1_gpt" + SESSION_ID_GPT = "session_001_gpt" # Using a fixed ID for simplicity + + # Create the specific session where the conversation will happen + session_gpt = session_service_gpt.create_session( + app_name=APP_NAME_GPT, + user_id=USER_ID_GPT, + session_id=SESSION_ID_GPT + ) + print(f"Session created: App='{APP_NAME_GPT}', User='{USER_ID_GPT}', Session='{SESSION_ID_GPT}'") + + # Create a runner specific to this agent and its session service runner_gpt = Runner( agent=weather_agent_gpt, - app_name=APP_NAME, # Use the same app name - session_service=session_service # Re-use the same session service + app_name=APP_NAME_GPT, # Use the specific app name + session_service=session_service_gpt # Use the specific session service ) print(f"Runner created for agent '{runner_gpt.agent.name}'.") + # --- Test the GPT Agent --- + print("\n--- Testing GPT Agent ---") + # Ensure call_agent_async uses the correct runner, user_id, session_id + await call_agent_async(query = "What's the weather in Tokyo?", + runner=runner_gpt, + user_id=USER_ID_GPT, + session_id=SESSION_ID_GPT) + except Exception as e: - print(f"❌ Could not create GPT agent '{MODEL_GPT_4O}'. Check API Key and model name. Error: {e}") + print(f"❌ Could not create or run GPT agent '{MODEL_GPT_4O}'. Check API Key and model name. Error: {e}") + +``` + +Next, we'll do the same for Anthropic's Claude Sonnet. + +```py +# @title Define and Test Claude Agent + +# Make sure 'get_weather' function from Step 1 is defined in your environment. +# Make sure 'call_agent_async' is defined from earlier. # --- Agent using Claude Sonnet --- weather_agent_claude = None # Initialize to None runner_claude = None # Initialize runner to None + try: weather_agent_claude = Agent( name="weather_agent_claude", @@ -370,141 +493,57 @@ try: tools=[get_weather], # Re-use the same tool ) print(f"Agent '{weather_agent_claude.name}' created using model '{MODEL_CLAUDE_SONNET}'.") - # Create a runner specific to this agent - runner_claude = Runner( - agent=weather_agent_claude, - app_name=APP_NAME, # Use the same app name - session_service=session_service # Re-use the same session service - ) - print(f"Runner created for agent '{runner_claude.agent.name}'.") - -except Exception as e: - print(f"❌ Could not create Claude agent '{MODEL_CLAUDE_SONNET}'. Check API Key and model name. Error: {e}") -``` - ---- - -**3\. Interact with the Multi-Model Agents** - -Since each agent now has its own `Runner` instance, we need a way to direct our queries to the correct runner. Let's create a slightly modified interaction function `call_specific_agent_async` that accepts the `runner_instance` as an argument. - -```py -# @title Updated Agent Interaction Function (Accepts Runner) + # InMemorySessionService is simple, non-persistent storage for this tutorial. + session_service_claude = InMemorySessionService() # Create a dedicated service -# Make sure 'types' (google.genai.types) is imported and USER_ID, SESSION_ID are defined. + # Define constants for identifying the interaction context + APP_NAME_CLAUDE = "weather_tutorial_app_claude" # Unique app name + USER_ID_CLAUDE = "user_1_claude" + SESSION_ID_CLAUDE = "session_001_claude" # Using a fixed ID for simplicity -async def call_specific_agent_async(runner_instance: Runner, query: str): - """Sends a query to the agent via the specified runner and prints the final response.""" - if not runner_instance: - print(f"⚠️ Cannot run query '{query}'. Runner is not available (check agent creation and API keys).") - return - - agent_name = runner_instance.agent.name - print(f"\n>>> User Query to {agent_name}: {query}") + # Create the specific session where the conversation will happen + session_claude = session_service_claude.create_session( + app_name=APP_NAME_CLAUDE, + user_id=USER_ID_CLAUDE, + session_id=SESSION_ID_CLAUDE + ) + print(f"Session created: App='{APP_NAME_CLAUDE}', User='{USER_ID_CLAUDE}', Session='{SESSION_ID_CLAUDE}'") - content = types.Content(role='user', parts=[types.Part(text=query)]) - final_response_text = f"Agent {agent_name} did not produce a final response." # Default - - try: - # Use the specific runner passed to the function - async for event in runner_instance.run_async(user_id=USER_ID, session_id=SESSION_ID, new_message=content): - # print(f" [Event] Author: {event.author}, Type: {type(event).__name__}, Final: {event.is_final_response()}") # Debugging - if event.is_final_response(): - if event.content and event.content.parts: - final_response_text = event.content.parts[0].text - elif event.actions and event.actions.escalate: - final_response_text = f"Agent escalated: {event.error_message or 'No specific message.'}" - break # Exit loop once final response is found - except Exception as e: - # Catch potential errors during the run (e.g., API errors) - print(f"❌ Error during run for agent {agent_name}: {e}") - final_response_text = f"Error occurred while running agent {agent_name}." - - - print(f"<<< {agent_name} Response: {final_response_text}") - -# --- Example Usage --- -async def run_multi_model_conversation(): - print("\n--- Testing GPT Agent ---") - # Check if the runner was created successfully before calling - if runner_gpt: - await call_specific_agent_async(runner_gpt, "What's the weather in Tokyo?") - else: - print("Skipping GPT test as runner is not available.") + # Create a runner specific to this agent and its session service + runner_claude = Runner( + agent=weather_agent_claude, + app_name=APP_NAME_CLAUDE, # Use the specific app name + session_service=session_service_claude # Use the specific session service + ) + print(f"Runner created for agent '{runner_claude.agent.name}'.") + # --- Test the Claude Agent --- print("\n--- Testing Claude Agent ---") - # Check if the runner was created successfully - if runner_claude: - await call_specific_agent_async(runner_claude, "Weather in London please.") - else: - print("Skipping Claude test as runner is not available.") - - print("\n--- Testing Original Gemini Agent ---") - # Assuming 'runner' still holds the runner for the original Gemini agent (weather_agent_v1 from Step 1) - # Ensure the 'runner' variable from Step 1 is accessible here. - # If running steps independently, you might need to recreate the original runner. - if 'runner' in globals() and runner: - await call_specific_agent_async(runner, "How about New York?") - else: - print("Original Gemini agent runner ('runner') not found. Skipping test.") - -``` - ---- - -**4\. Run the Multi-Model Conversation** - -Now, execute the conversation. Ensure your API keys are correctly set in Step 0\! - -```py -# @title Execute the Multi-Model Conversation - -# Execute the conversation defined above -# Note: Requires API keys for Gemini, GPT, and Claude to be set correctly! -await run_multi_model_conversation() + # Ensure call_agent_async uses the correct runner, user_id, session_id + await call_agent_async(query = "Weather in London please.", + runner=runner_claude, + user_id=USER_ID_CLAUDE, + session_id=SESSION_ID_CLAUDE) +except Exception as e: + print(f"❌ Could not create or run Claude agent '{MODEL_CLAUDE_SONNET}'. Check API Key and model name. Error: {e}") ``` -**Expected Output:** +Observe the output carefully from both code blocks. You should see: -```console ---- Testing GPT Agent --- +1. Each agent (`weather_agent_gpt`, `weather_agent_claude`) is created successfully (if API keys are valid). +2. A dedicated session and runner are set up for each. +3. Each agent correctly identifies the need to use the `get_weather` tool when processing the query (you'll see the `--- Tool: get_weather called... ---` log). +4. The *underlying tool logic* remains identical, always returning our mock data. +5. However, the **final textual response** generated by each agent might differ slightly in phrasing, tone, or formatting. This is because the instruction prompt is interpreted and executed by different LLMs (GPT-4o vs. Claude Sonnet). ->>> User Query to weather_agent_gpt: What's the weather in Tokyo? ---- Tool: get_weather called for city: Tokyo --- -<<< weather_agent_gpt Response: The weather in Tokyo is currently experiencing light rain with a temperature of 18°C. - ---- Testing Claude Agent --- - ->>> User Query to weather_agent_claude: Weather in London please. ---- Tool: get_weather called for city: London --- -<<< weather_agent_claude Response: The weather in London is cloudy with a temperature of 15°C. - ---- Testing Original Gemini Agent --- - ->>> User Query to weather_agent_v1: How about New York? - ---- Tool: get_weather called for city: New York --- -<<< weather_agent_v1 Response: The weather in New York is sunny with a temperature of 25°C. - -``` +This step demonstrates the power and flexibility ADK + LiteLLM provide. You can easily experiment with and deploy agents using various LLMs while keeping your core application logic (tools, fundamental agent structure) consistent. -\*\* Ignore the warning +In the next step, we'll move beyond a single agent and build a small team where agents can delegate tasks to each other! --- -Observe the output carefully. You should see: - -1. Each agent (`weather_agent_gpt`, `weather_agent_claude`, `weather_agent_v1`) successfully receives the query. -2. Each agent correctly identifies the need to use the `get_weather` tool (you'll see the `--- Tool: get_weather called... ---` log). -3. The *underlying tool logic* remains identical, always returning our mock data. -4. However, the **final textual response** generated by each agent might differ slightly in phrasing, tone, or formatting. This is because the instruction prompt is interpreted and executed by different LLMs (GPT-4o vs. Claude Sonnet vs. Gemini Pro). - -This step demonstrates the power and flexibility ADK \+ LiteLLM provide. You can easily experiment with and deploy agents using various LLMs while keeping your core application logic (tools, session management) consistent. - -In the next step, we'll move beyond a single agent and build a small team where agents can delegate tasks to each other\! - ## Step 3: Building an Agent Team \- Delegation for Greetings & Farewells In Steps 1 and 2, we built and experimented with a single agent focused solely on weather lookups. While effective for its specific task, real-world applications often involve handling a wider variety of user interactions. We *could* keep adding more tools and complex instructions to our single weather agent, but this can quickly become unmanageable and less efficient. @@ -532,7 +571,7 @@ A more robust approach is to build an **Agent Team**. This involves: --- -**1\. Define Tools for Sub-Agents** +### **1\. Define Tools for Sub-Agents** First, let's create the simple Python functions that will serve as tools for our new specialist agents. Remember, clear docstrings are vital for the agents that will use them. @@ -568,7 +607,7 @@ print(say_goodbye()) --- -**2\. Define the Sub-Agents (Greeting & Farewell)** +### **2\. Define the Sub-Agents (Greeting & Farewell)** Now, create the `Agent` instances for our specialists. Notice their highly focused `instruction` and, critically, their clear `description`. The `description` is the primary information the *root agent* uses to decide *when* to delegate to these sub-agents. @@ -625,7 +664,7 @@ except Exception as e: --- -**3\. Define the Root Agent (Weather Agent v2) with Sub-Agents** +### **3\. Define the Root Agent with Sub-Agents** Now, we upgrade our `weather_agent`. The key changes are: @@ -646,9 +685,9 @@ runner_root = None # Initialize runner if greeting_agent and farewell_agent and 'get_weather' in globals(): # Let's use a capable Gemini model for the root agent to handle orchestration - root_agent_model = MODEL_GEMINI_2_5_PRO # Or MODEL_GEMINI_2_0_FLASH for potentially faster/cheaper routing + root_agent_model = MODEL_GEMINI_2_0_FLASH - root_agent = Agent( + weather_agent_team = Agent( name="weather_agent_v2", # Give it a new version name model=root_agent_model, description="The main coordinator agent. Handles weather requests and delegates greetings/farewells to specialists.", @@ -664,16 +703,7 @@ if greeting_agent and farewell_agent and 'get_weather' in globals(): # Key change: Link the sub-agents here! sub_agents=[greeting_agent, farewell_agent] ) - print(f"✅ Root Agent '{root_agent.name}' created using model '{root_agent_model}' with sub-agents: {[sa.name for sa in root_agent.sub_agents]}") - - # --- IMPORTANT: Create a Runner for this Root Agent --- - # This runner will manage the multi-agent flow starting from root_agent. - runner_root = Runner( - agent=root_agent, - app_name=APP_NAME, - session_service=session_service # Re-use the same session service - ) - print(f"✅ Runner created for the root agent '{runner_root.agent.name}'.") + print(f"✅ Root Agent '{weather_agent_team.name}' created using model '{root_agent_model}' with sub-agents: {[sa.name for sa in weather_agent_team.sub_agents]}") else: print("❌ Cannot create root agent because one or more sub-agents failed to initialize or 'get_weather' tool is missing.") @@ -681,77 +711,115 @@ else: if not farewell_agent: print(" - Farewell Agent is missing.") if 'get_weather' not in globals(): print(" - get_weather function is missing.") -``` ---- -**4\. Interact with the Agent Team** +``` -Let's test our new multi-agent setup. We'll use the `call_specific_agent_async` function created in Step 2, but this time we'll pass it the `runner_root` we just created for our agent team. +--- -We expect the following flow: +### **4\. Interact with the Agent Team** -1. User query ("Hello there\!") goes to `runner_root`. -2. `root_agent` (weather\_agent\_v2) receives the query. -3. Its LLM analyzes the query and the descriptions of its `sub_agents`. It decides the query matches `greeting_agent`'s description. -4. `root_agent` delegates to `greeting_agent`. -5. `greeting_agent` processes the query, calls its `say_hello` tool, and generates the final response. -6. Similar delegation happens for the farewell query to `farewell_agent`. -7. The weather query is *not* delegated and is handled directly by `root_agent` using `get_weather`. +Now that we've defined our root agent (`weather_agent_team` - *Note: Ensure this variable name matches the one defined in the previous code block, likely `# @title Define the Root Agent with Sub-Agents`, which might have named it `root_agent`*) with its specialized sub-agents, let's test the delegation mechanism. -```py -# @title Interact with the Agent Team +The following code block will: -# Ensure the runner for the root agent is available -if runner_root: - async def run_team_conversation(): - print("\n--- Testing Agent Team Delegation ---") - # Always interact via the root agent's runner - await call_specific_agent_async(runner_root, "Hello there!") - await call_specific_agent_async(runner_root, "What is the weather in New York?") - await call_specific_agent_async(runner_root, "Thanks, bye!") +1. Define an `async` function `run_team_conversation`. +2. Inside this function, create a *new, dedicated* `InMemorySessionService` and a specific session (`session_001_agent_team`) just for this test run. This isolates the conversation history for testing the team dynamics. +3. Create a `Runner` (`runner_agent_team`) configured to use our `weather_agent_team` (the root agent) and the dedicated session service. +4. Use our updated `call_agent_async` function to send different types of queries (greeting, weather request, farewell) to the `runner_agent_team`. We explicitly pass the runner, user ID, and session ID for this specific test. +5. Immediately execute the `run_team_conversation` function. - # Execute the conversation - # Note: This may require API keys for the models used by root and sub-agents! - await run_team_conversation() -else: - print("\n⚠️ Skipping agent team conversation as the root agent runner ('runner_root') is not available.") +We expect the following flow: -``` +1. The "Hello there!" query goes to `runner_agent_team`. +2. The root agent (`weather_agent_team`) receives it and, based on its instructions and the `greeting_agent`'s description, delegates the task. +3. `greeting_agent` handles the query, calls its `say_hello` tool, and generates the response. +4. The "What is the weather in New York?" query is *not* delegated and is handled directly by the root agent using its `get_weather` tool. +5. The "Thanks, bye!" query is delegated to the `farewell_agent`, which uses its `say_goodbye` tool. -**Expected Output:** -```console ---- Testing Agent Team Delegation --- +```py +# @title Interact with the Agent Team ->>> User Query to weather_agent_v2: Hello there! -<<< weather_agent_v2 Response: Hello, there! +# Ensure the root agent (e.g., 'weather_agent_team' or 'root_agent' from the previous cell) is defined. +# Ensure the call_agent_async function is defined. + +# Check if the root agent variable exists before defining the conversation function +root_agent_var_name = 'root_agent' # Default name from Step 3 guide +if 'weather_agent_team' in globals(): # Check if user used this name instead + root_agent_var_name = 'weather_agent_team' +elif 'root_agent' not in globals(): + print("⚠️ Root agent ('root_agent' or 'weather_agent_team') not found. Cannot define run_team_conversation.") + # Assign a dummy value to prevent NameError later if the code block runs anyway + root_agent = None + +if root_agent_var_name in globals() and globals()[root_agent_var_name]: + async def run_team_conversation(): + print("\n--- Testing Agent Team Delegation ---") + # InMemorySessionService is simple, non-persistent storage for this tutorial. + session_service = InMemorySessionService() + + # Define constants for identifying the interaction context + APP_NAME = "weather_tutorial_agent_team" + USER_ID = "user_1_agent_team" + SESSION_ID = "session_001_agent_team" # Using a fixed ID for simplicity + + # Create the specific session where the conversation will happen + session = session_service.create_session( + app_name=APP_NAME, + user_id=USER_ID, + session_id=SESSION_ID + ) + print(f"Session created: App='{APP_NAME}', User='{USER_ID}', Session='{SESSION_ID}'") ->>> User Query to weather_agent_v2: What is the weather in New York? ---- Tool: get_weather called for city: New York --- ---- Tool: get_weather called for city: New York --- -<<< weather_agent_v2 Response: The weather in New York is sunny with a temperature of 25°C. + # --- Get the actual root agent object --- + # Use the determined variable name + actual_root_agent = globals()[root_agent_var_name] ->>> User Query to weather_agent_v2: Thanks, bye! ---- Tool: say_goodbye called --- -<<< weather_agent_v2 Response: Goodbye! Have a great day. + # Create a runner specific to this agent team test + runner_agent_team = Runner( + agent=actual_root_agent, # Use the root agent object + app_name=APP_NAME, # Use the specific app name + session_service=session_service # Use the specific session service + ) + # Corrected print statement to show the actual root agent's name + print(f"Runner created for agent '{actual_root_agent.name}'.") + + # Always interact via the root agent's runner, passing the correct IDs + await call_agent_async(query = "Hello there!", + runner=runner_agent_team, + user_id=USER_ID, + session_id=SESSION_ID) + await call_agent_async(query = "What is the weather in New York?", + runner=runner_agent_team, + user_id=USER_ID, + session_id=SESSION_ID) + await call_agent_async(query = "Thanks, bye!", + runner=runner_agent_team, + user_id=USER_ID, + session_id=SESSION_ID) + + # Execute the conversation + # Note: This may require API keys for the models used by root and sub-agents! + await run_team_conversation() +else: + print("\n⚠️ Skipping agent team conversation as the root agent was not successfully defined in the previous step.") ``` -\*\* Ignore the warning - --- Look closely at the output logs, especially the `--- Tool: ... called ---` messages. You should observe: -* For "Hello there\!", the `say_hello` tool was called (indicating `greeting_agent` handled it). -* For "What is the weather in New York?", the `get_weather` tool was called (indicating `root_agent` handled it). -* For "Thanks, bye\!", the `say_goodbye` tool was called (indicating `farewell_agent` handled it). +* For "Hello there!", the `say_hello` tool was called (indicating `greeting_agent` handled it). +* For "What is the weather in New York?", the `get_weather` tool was called (indicating the root agent handled it). +* For "Thanks, bye!", the `say_goodbye` tool was called (indicating `farewell_agent` handled it). -This confirms successful **automatic delegation**\! The `root_agent`, guided by its instructions and the `description`s of its `sub_agents`, correctly routed user requests to the appropriate specialist agent within the team. +This confirms successful **automatic delegation**! The root agent, guided by its instructions and the `description`s of its `sub_agents`, correctly routed user requests to the appropriate specialist agent within the team. You've now structured your application with multiple collaborating agents. This modular design is fundamental for building more complex and capable agent systems. In the next step, we'll give our agents the ability to remember information across turns using session state. + ## Step 4: Adding Memory and Personalization with Session State So far, our agent team can handle different tasks through delegation, but each interaction starts fresh – the agents have no memory of past conversations or user preferences within a session. To create more sophisticated and context-aware experiences, agents need **memory**. ADK provides this through **Session State**. @@ -777,7 +845,7 @@ So far, our agent team can handle different tasks through delegation, but each i --- -**1\. Initialize New Session Service and State** +### **1\. Initialize New Session Service and State** To clearly demonstrate state management without interference from prior steps, we'll instantiate a new `InMemorySessionService`. We'll also create a session with an initial state defining the user's preferred temperature unit. @@ -810,7 +878,9 @@ session_stateful = session_service_stateful.create_session( print(f"✅ Session '{SESSION_ID_STATEFUL}' created for user '{USER_ID_STATEFUL}'.") # Verify the initial state was set correctly -retrieved_session = session_service_stateful.get_session(APP_NAME, USER_ID_STATEFUL, SESSION_ID_STATEFUL) +retrieved_session = session_service_stateful.get_session(app_name=APP_NAME, + user_id=USER_ID_STATEFUL, + session_id = SESSION_ID_STATEFUL) print("\n--- Initial Session State ---") if retrieved_session: print(retrieved_session.state) @@ -821,7 +891,7 @@ else: --- -**2\. Create State-Aware Weather Tool (`get_weather_stateful`)** +### **2. Create State-Aware Weather Tool** Now, we create a new version of the weather tool. Its key feature is accepting `tool_context: ToolContext` which allows it to access `tool_context.state`. It will read the `user_preference_temperature_unit` and format the temperature accordingly. @@ -831,12 +901,11 @@ Now, we create a new version of the weather tool. Its key feature is accepting ` ```py # @title 2. Create State-Aware Weather Tool - from google.adk.tools.tool_context import ToolContext def get_weather_stateful(city: str, tool_context: ToolContext) -> dict: """Retrieves weather, converts temp unit based on session state.""" - print(f"--- Tool: get_weather_stateful called for {city} (SessionID: {tool_context.session.id}) ---") + print(f"--- Tool: get_weather_stateful called for {city} ---") # --- Read preference from state --- preferred_unit = tool_context.state.get("user_preference_temperature_unit", "Celsius") # Default to Celsius @@ -880,11 +949,12 @@ def get_weather_stateful(city: str, tool_context: ToolContext) -> dict: return {"status": "error", "error_message": error_msg} print("✅ State-aware 'get_weather_stateful' tool defined.") + ``` --- -**3\. Redefine Sub-Agents and Update Root Agent** +### **3\. Redefine Sub-Agents and Update Root Agent** To ensure this step is self-contained and builds correctly, we first redefine the `greeting_agent` and `farewell_agent` exactly as they were in Step 3\. Then, we define our new root agent (`weather_agent_v4_stateful`): @@ -906,7 +976,7 @@ from google.adk.runners import Runner greeting_agent = None try: greeting_agent = Agent( - model=LiteLlm(model=MODEL_GPT_4O), + model=MODEL_GEMINI_2_0_FLASH, name="greeting_agent", instruction="You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.", description="Handles simple greetings and hellos using the 'say_hello' tool.", @@ -920,7 +990,7 @@ except Exception as e: farewell_agent = None try: farewell_agent = Agent( - model=LiteLlm(model=MODEL_GPT_4O), + model=MODEL_GEMINI_2_0_FLASH, name="farewell_agent", instruction="You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.", description="Handles simple farewells and goodbyes using the 'say_goodbye' tool.", @@ -937,7 +1007,7 @@ runner_root_stateful = None # Initialize runner # Check prerequisites before creating the root agent if greeting_agent and farewell_agent and 'get_weather_stateful' in globals(): - root_agent_model = MODEL_GEMINI_2_5_PRO # Choose orchestration model + root_agent_model = MODEL_GEMINI_2_0_FLASH # Choose orchestration model root_agent_stateful = Agent( name="weather_agent_v4_stateful", # New version name @@ -971,59 +1041,80 @@ else: --- -**4\. Interact and Test State Flow** +### **4\. Interact and Test State Flow** + +Now, let's execute a conversation designed to test the state interactions using the `runner_root_stateful` (associated with our stateful agent and the `session_service_stateful`). We'll use the `call_agent_async` function defined earlier, ensuring we pass the correct runner, user ID (`USER_ID_STATEFUL`), and session ID (`SESSION_ID_STATEFUL`). -Now, let's execute a conversation designed to test the state interactions: +The conversation flow will be: -1. Check weather: The `get_weather_stateful` tool reads the initial "Celsius" preference. The root agent's final response (the weather report) gets saved to `state['last_weather_report']` via `output_key`. -2. Manually update state: We directly modify the session state to set the preference to "Fahrenheit". (Note: In real applications, state changes are often triggered by tools or specific agent logic, usually via `EventActions(state_delta=...)`, but direct modification is useful for testing). -3. Check weather again: The tool now reads "Fahrenheit" from the state and converts the temperature. The root agent's *new* response overwrites the `state['last_weather_report']`. -4. Greet the agent: Verify that delegation to the `greeting_agent` still works correctly. -5. Inspect final state: Confirm the `user_preference_temperature_unit` is "Fahrenheit" and observe the content of `last_weather_report`. +1. **Check weather (London):** The `get_weather_stateful` tool should read the initial "Celsius" preference from the session state initialized in Section 1. The root agent's final response (the weather report in Celsius) should get saved to `state['last_weather_report']` via the `output_key` configuration. +2. **Manually update state:** We will *directly modify* the state stored within the `InMemorySessionService` instance (`session_service_stateful`). + * **Why direct modification?** The `session_service.get_session()` method returns a *copy* of the session. Modifying that copy wouldn't affect the state used in subsequent agent runs. For this testing scenario with `InMemorySessionService`, we access the internal `sessions` dictionary to change the *actual* stored state value for `user_preference_temperature_unit` to "Fahrenheit". *Note: In real applications, state changes are typically triggered by tools or agent logic returning `EventActions(state_delta=...)`, not direct manual updates.* +3. **Check weather again (New York):** The `get_weather_stateful` tool should now read the updated "Fahrenheit" preference from the state and convert the temperature accordingly. The root agent's *new* response (weather in Fahrenheit) will overwrite the previous value in `state['last_weather_report']` due to the `output_key`. +4. **Greet the agent:** Verify that delegation to the `greeting_agent` still works correctly alongside the stateful operations. This interaction will become the *last* response saved by `output_key` in this specific sequence. +5. **Inspect final state:** After the conversation, we retrieve the session one last time (getting a copy) and print its state to confirm the `user_preference_temperature_unit` is indeed "Fahrenheit", observe the final value saved by `output_key` (which will be the greeting in this run), and see the `last_city_checked_stateful` value written by the tool. ```py -# @title 4. Interact to Test State Flow and output_key +# Ensure the stateful runner (runner_root_stateful) is available from the previous cell +# Ensure call_agent_async, USER_ID_STATEFUL, SESSION_ID_STATEFUL, APP_NAME are defined -# Ensure the stateful runner is available -if runner_root_stateful: +if 'runner_root_stateful' in globals() and runner_root_stateful: async def run_stateful_conversation(): print("\n--- Testing State: Temp Unit Conversion & output_key ---") - # Define interaction helper using the stateful runner and session details - interaction_func = lambda query: call_specific_agent_async(runner_root_stateful, query) - # ^ Using the function from Step 2 - # Ensure USER_ID_STATEFUL, SESSION_ID_STATEFUL are used if modifying the helper - # 1. Check weather (Uses initial state: Celsius) - await interaction_func("What's the weather in London?") - - # 2. Manually update state preference to Fahrenheit + print("--- Turn 1: Requesting weather in London (expect Celsius) ---") + await call_agent_async(query= "What's the weather in London?", + runner=runner_root_stateful, + user_id=USER_ID_STATEFUL, + session_id=SESSION_ID_STATEFUL + ) + + # 2. Manually update state preference to Fahrenheit - DIRECTLY MODIFY STORAGE print("\n--- Manually Updating State: Setting unit to Fahrenheit ---") - current_session = session_service_stateful.get_session(APP_NAME, USER_ID_STATEFUL, SESSION_ID_STATEFUL) - if current_session: - current_session.state["user_preference_temperature_unit"] = "Fahrenheit" - print(f"--- Session state updated. Current 'user_preference_temperature_unit': {current_session.state['user_preference_temperature_unit']} ---") - else: - print("--- Error: Could not retrieve session to update state. ---") + try: + # Access the internal storage directly - THIS IS SPECIFIC TO InMemorySessionService for testing + stored_session = session_service_stateful.sessions[APP_NAME][USER_ID_STATEFUL][SESSION_ID_STATEFUL] + stored_session.state["user_preference_temperature_unit"] = "Fahrenheit" + # Optional: You might want to update the timestamp as well if any logic depends on it + # import time + # stored_session.last_update_time = time.time() + print(f"--- Stored session state updated. Current 'user_preference_temperature_unit': {stored_session.state['user_preference_temperature_unit']} ---") + except KeyError: + print(f"--- Error: Could not retrieve session '{SESSION_ID_STATEFUL}' from internal storage for user '{USER_ID_STATEFUL}' in app '{APP_NAME}' to update state. Check IDs and if session was created. ---") + except Exception as e: + print(f"--- Error updating internal session state: {e} ---") # 3. Check weather again (Tool should now use Fahrenheit) # This will also update 'last_weather_report' via output_key - await interaction_func("Tell me the weather in New York.") + print("\n--- Turn 2: Requesting weather in New York (expect Fahrenheit) ---") + await call_agent_async(query= "Tell me the weather in New York.", + runner=runner_root_stateful, + user_id=USER_ID_STATEFUL, + session_id=SESSION_ID_STATEFUL + ) # 4. Test basic delegation (should still work) - await interaction_func("Hi!") - + # This will update 'last_weather_report' again, overwriting the NY weather report + print("\n--- Turn 3: Sending a greeting ---") + await call_agent_async(query= "Hi!", + runner=runner_root_stateful, + user_id=USER_ID_STATEFUL, + session_id=SESSION_ID_STATEFUL + ) # Execute the conversation await run_stateful_conversation() # Inspect final session state after the conversation - final_session = session_service_stateful.get_session(APP_NAME, USER_ID_STATEFUL, SESSION_ID_STATEFUL) + print("\n--- Inspecting Final Session State ---") + final_session = session_service_stateful.get_session(app_name=APP_NAME, + user_id= USER_ID_STATEFUL, + session_id=SESSION_ID_STATEFUL) if final_session: - print("\n--- Final Session State ---") - print(f"Preference: {final_session.state.get('user_preference_temperature_unit')}") - print(f"Last Weather Report (from output_key): {final_session.state.get('last_weather_report')}") - print(f"Last City Checked (by tool): {final_session.state.get('last_city_checked_stateful')}") + print(f"Final Preference: {final_session.state.get('user_preference_temperature_unit')}") + print(f"Final Last Weather Report (from output_key): {final_session.state.get('last_weather_report')}") + print(f"Final Last City Checked (by tool): {final_session.state.get('last_city_checked_stateful')}") # Print full state for detailed view # print(f"Full State: {final_session.state}") else: @@ -1034,53 +1125,22 @@ else: ``` -**Expected Output:** - -```console ---- Testing State: Temp Unit Conversion & output_key --- - ->>> User Query to weather_agent_v4_stateful: What's the weather in London? ---- Tool: get_weather_stateful called for New York --- ---- Tool: Reading state 'user_preference_temperature_unit': Celsius --- ---- Tool: Generated report in Celsius. Result: {'status': 'success', 'report': 'The weather in New york is sunny with a temperature of 25°C.'} --- ---- Tool: Updated state 'last_city_checked_stateful': New York --- -<<< weather_agent_v4_stateful Response: The weather in New york is sunny with a temperature of 25°C. - - ---- Manually Updating State: Setting unit to Fahrenheit --- ---- Session state updated. Current 'user_preference_temperature_unit': Fahrenheit --- - ->>> User Query to weather_agent_v4_stateful: Tell me the weather in New York. ---- Tool: get_weather_stateful called for New York --- ---- Tool: Reading state 'user_preference_temperature_unit': Celsius --- ---- Tool: Generated report in Celsius. Result: {'status': 'success', 'report': 'The weather in New york is sunny with a temperature of 25°C.'} --- ---- Tool: Updated state 'last_city_checked_stateful': New York --- -<<< weather_agent_v4_stateful Response: The weather in New york is sunny with a temperature of 25°C. - - ->>> User Query to weather_agent_v4_stateful: Hi! -<<< weather_agent_v4_stateful Response: Hello, there! - +--- ---- Final Session State --- -Preference: Celsius -Last Weather Report (from output_key): None -Last City Checked (by tool): None +By reviewing the conversation flow and the final session state printout, you can confirm: -``` +* **State Read:** The weather tool (`get_weather_stateful`) correctly read `user_preference_temperature_unit` from state, initially using "Celsius" for London. +* **State Update:** The direct modification successfully changed the stored preference to "Fahrenheit". +* **State Read (Updated):** The tool subsequently read "Fahrenheit" when asked for New York's weather and performed the conversion. +* **Tool State Write:** The tool successfully wrote the `last_city_checked_stateful` ("New York" after the second weather check) into the state via `tool_context.state`. +* **Delegation:** The delegation to the `greeting_agent` for "Hi!" functioned correctly even after state modifications. +* **`output_key`:** The `output_key="last_weather_report"` successfully saved the root agent's *final* response for *each turn* where the root agent was the one ultimately responding. In this sequence, the last response was the greeting ("Hello, there!"), so that overwrote the weather report in the state key. +* **Final State:** The final check confirms the preference persisted as "Fahrenheit". -\*\* Ignore the warning +You've now successfully integrated session state to personalize agent behavior using `ToolContext`, manually manipulated state for testing `InMemorySessionService`, and observed how `output_key` provides a simple mechanism for saving the agent's last response to state. This foundational understanding of state management is key as we proceed to implement safety guardrails using callbacks in the next steps. --- -By reviewing the conversation flow and the final session state, you can confirm: - -* The weather tool (`get_weather_stateful`) correctly read the `user_preference_temperature_unit` from state and adjusted its output (Celsius then Fahrenheit). -* The delegation to the `greeting_agent` continued to function alongside the stateful operations. -* The `output_key="last_weather_report"` successfully saved the root agent's final weather response into the session state automatically. - -You've now successfully integrated session state to personalize agent behavior and used `output_key` for simple state persistence. This foundational understanding of state management is key as we proceed to implement safety guardrails using callbacks in the next steps. - ## Step 5: Adding Safety \- Input Guardrail with `before_model_callback` Our agent team is becoming more capable, remembering preferences and using tools effectively. However, in real-world scenarios, we often need safety mechanisms to control the agent's behavior *before* potentially problematic requests even reach the core Large Language Model (LLM). @@ -1118,7 +1178,7 @@ ADK provides **Callbacks** – functions that allow you to hook into specific po --- -**1\. Define the Guardrail Callback Function** +### **1\. Define the Guardrail Callback Function** This function will inspect the last user message within the `llm_request` content. If it finds "BLOCK" (case-insensitive), it constructs and returns an `LlmResponse` to block the flow; otherwise, it returns `None`. @@ -1177,11 +1237,12 @@ def block_keyword_guardrail( return None # Returning None signals ADK to continue normally print("✅ block_keyword_guardrail function defined.") + ``` --- -**2\. Update Root Agent to Use the Callback** +### **2\. Update Root Agent to Use the Callback** We redefine the root agent, adding the `before_model_callback` parameter and pointing it to our new guardrail function. We'll give it a new version name for clarity. @@ -1190,58 +1251,85 @@ We redefine the root agent, adding the `before_model_callback` parameter and poi ```py # @title 2. Update Root Agent with before_model_callback -# Ensure prerequisites are defined: -# - greeting_agent, farewell_agent (from Step 3/4) -# - get_weather_stateful tool (from Step 4) -# - block_keyword_guardrail callback (from previous cell) -# --- Redefine Sub-Agents and Tool if necessary (Ensure Self-Contained Execution) --- -# (Include the definitions for greeting_agent, farewell_agent, say_hello, say_goodbye, -# get_weather_stateful, ToolContext, Agent, LiteLlm, Runner, model constants etc. -# here or ensure they were executed in the notebook previously) -# Example placeholder check: -if 'greeting_agent' not in globals() or 'farewell_agent' not in globals() or 'get_weather_stateful' not in globals() or 'block_keyword_guardrail' not in globals(): - print("⚠️ Warning: Prerequisite agents, tools, or callbacks might be missing. Ensure previous steps were run or redefine them here.") - # Add full definitions if needed for standalone execution +# --- Redefine Sub-Agents (Ensures they exist in this context) --- +greeting_agent = None +try: + # Use a defined model constant + greeting_agent = Agent( + model=MODEL_GEMINI_2_0_FLASH, + name="greeting_agent", # Keep original name for consistency + instruction="You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.", + description="Handles simple greetings and hellos using the 'say_hello' tool.", + tools=[say_hello], + ) + print(f"✅ Sub-Agent '{greeting_agent.name}' redefined.") +except Exception as e: + print(f"❌ Could not redefine Greeting agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}") + +farewell_agent = None +try: + # Use a defined model constant + farewell_agent = Agent( + model=MODEL_GEMINI_2_0_FLASH, + name="farewell_agent", # Keep original name + instruction="You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.", + description="Handles simple farewells and goodbyes using the 'say_goodbye' tool.", + tools=[say_goodbye], + ) + print(f"✅ Sub-Agent '{farewell_agent.name}' redefined.") +except Exception as e: + print(f"❌ Could not redefine Farewell agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}") + # --- Define the Root Agent with the Callback --- root_agent_model_guardrail = None runner_root_model_guardrail = None -if 'greeting_agent' in globals() and 'farewell_agent' in globals() and 'get_weather_stateful' in globals() and 'block_keyword_guardrail' in globals(): +# Check all components before proceeding +if greeting_agent and farewell_agent and 'get_weather_stateful' in globals() and 'block_keyword_guardrail' in globals(): - root_agent_model = MODEL_GEMINI_2_5_PRO # Model for the root agent + # Use a defined model constant like MODEL_GEMINI_2_5_PRO + root_agent_model = MODEL_GEMINI_2_0_FLASH root_agent_model_guardrail = Agent( - name="weather_agent_v5_model_guardrail", # New version name + name="weather_agent_v5_model_guardrail", # New version name for clarity model=root_agent_model, - description="Main agent: Provides weather, delegates greetings/farewells, includes input keyword guardrail.", + description="Main agent: Handles weather, delegates greetings/farewells, includes input keyword guardrail.", instruction="You are the main Weather Agent. Provide weather using 'get_weather_stateful'. " - "Delegate greetings to 'greeting_agent' and farewells to 'farewell_agent'. " - "Handle only weather, greetings, and farewells.", - tools=[get_weather_stateful], # Still uses the stateful tool - sub_agents=[greeting_agent, farewell_agent], + "Delegate simple greetings to 'greeting_agent' and farewells to 'farewell_agent'. " + "Handle only weather requests, greetings, and farewells.", + tools=[get_weather], + sub_agents=[greeting_agent, farewell_agent], # Reference the redefined sub-agents output_key="last_weather_report", # Keep output_key from Step 4 - before_model_callback=block_keyword_guardrail # <<< Add the callback here + before_model_callback=block_keyword_guardrail # <<< Assign the guardrail callback ) print(f"✅ Root Agent '{root_agent_model_guardrail.name}' created with before_model_callback.") # --- Create Runner for this Agent, Using SAME Stateful Session Service --- - runner_root_model_guardrail = Runner( - agent=root_agent_model_guardrail, - app_name=APP_NAME, - session_service=session_service_stateful # <<< Use the SAME service from Step 4 - ) - print(f"✅ Runner created for guardrail agent '{runner_root_model_guardrail.agent.name}', using stateful session service.") + # Ensure session_service_stateful exists from Step 4 + if 'session_service_stateful' in globals(): + runner_root_model_guardrail = Runner( + agent=root_agent_model_guardrail, + app_name=APP_NAME, # Use consistent APP_NAME + session_service=session_service_stateful # <<< Use the service from Step 4 + ) + print(f"✅ Runner created for guardrail agent '{runner_root_model_guardrail.agent.name}', using stateful session service.") + else: + print("❌ Cannot create runner. 'session_service_stateful' from Step 4 is missing.") else: - print("❌ Cannot create root agent with model guardrail. Prerequisites missing.") + print("❌ Cannot create root agent with model guardrail. One or more prerequisites are missing or failed initialization:") + if not greeting_agent: print(" - Greeting Agent") + if not farewell_agent: print(" - Farewell Agent") + if 'get_weather_stateful' not in globals(): print(" - 'get_weather_stateful' tool") + if 'block_keyword_guardrail' not in globals(): print(" - 'block_keyword_guardrail' callback") ``` --- -**3\. Interact to Test the Guardrail** +### **3\. Interact to Test the Guardrail** Let's test the guardrail's behavior. We'll use the *same session* (`SESSION_ID_STATEFUL`) as in Step 4 to show that state persists across these changes. @@ -1258,10 +1346,9 @@ if runner_root_model_guardrail: print("\n--- Testing Model Input Guardrail ---") # Use the runner for the agent with the callback and the existing stateful session ID - interaction_func = lambda query: call_specific_agent_async(runner_root_model_guardrail, query) - # ^ Reusing the interaction function from Step 2 - # Ensure it uses USER_ID_STATEFUL, SESSION_ID_STATEFUL if needed - + interaction_func = lambda query: call_agent_async(query, + runner_root_model_guardrail, USER_ID_STATEFUL, SESSION_ID_STATEFUL # <-- Pass correct IDs + ) # 1. Normal request (Callback allows, should use Fahrenheit from Step 4 state change) await interaction_func("What is the weather in London?") @@ -1276,7 +1363,9 @@ if runner_root_model_guardrail: await run_guardrail_test_conversation() # Optional: Check state for the trigger flag set by the callback - final_session = session_service_stateful.get_session(APP_NAME, USER_ID_STATEFUL, SESSION_ID_STATEFUL) + final_session = session_service_stateful.get_session(app_name=APP_NAME, + user_id=USER_ID_STATEFUL, + session_id=SESSION_ID_STATEFUL) if final_session: print("\n--- Final Session State (After Guardrail Test) ---") print(f"Guardrail Triggered Flag: {final_session.state.get('guardrail_block_keyword_triggered')}") @@ -1288,6 +1377,7 @@ if runner_root_model_guardrail: else: print("\n⚠️ Skipping model guardrail test. Runner ('runner_root_model_guardrail') is not available.") + ``` --- @@ -1341,7 +1431,7 @@ ADK provides the `before_tool_callback` for this precise purpose. --- -**1\. Define the Tool Guardrail Callback Function** +### **1\. Define the Tool Guardrail Callback Function** This function targets the `get_weather_stateful` tool. It checks the `city` argument. If it's "Paris", it returns an error dictionary that looks like the tool's own error response. Otherwise, it allows the tool to run by returning `None`. @@ -1401,7 +1491,7 @@ print("✅ block_paris_tool_guardrail function defined.") --- -**2\. Update Root Agent to Use Both Callbacks** +### **2\. Update Root Agent to Use Both Callbacks** We redefine the root agent again (`weather_agent_v6_tool_guardrail`), this time adding the `before_tool_callback` parameter alongside the `before_model_callback` from Step 5\. @@ -1415,13 +1505,34 @@ We redefine the root agent again (`weather_agent_v6_tool_guardrail`), this time # MODEL constants, say_hello, say_goodbye, greeting_agent, farewell_agent, # get_weather_stateful, block_keyword_guardrail, block_paris_tool_guardrail) -# Example placeholder check: -if ('greeting_agent' not in globals() or not greeting_agent or - 'farewell_agent' not in globals() or not farewell_agent or - 'get_weather_stateful' not in globals() or - 'block_keyword_guardrail' not in globals() or - 'block_paris_tool_guardrail' not in globals()): - print("⚠️ Warning: Prerequisites missing. Ensure Steps 3, 4, 5 ran or redefine components.") +# --- Redefine Sub-Agents (Ensures they exist in this context) --- +greeting_agent = None +try: + # Use a defined model constant like MODEL_GPT_4O + greeting_agent = Agent( + model=MODEL_GEMINI_2_0_FLASH, + name="greeting_agent", # Keep original name for consistency + instruction="You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.", + description="Handles simple greetings and hellos using the 'say_hello' tool.", + tools=[say_hello], + ) + print(f"✅ Sub-Agent '{greeting_agent.name}' redefined.") +except Exception as e: + print(f"❌ Could not redefine Greeting agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}") + +farewell_agent = None +try: + # Use a defined model constant like MODEL_GPT_4O + farewell_agent = Agent( + model=MODEL_GEMINI_2_0_FLASH, + name="farewell_agent", # Keep original name + instruction="You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.", + description="Handles simple farewells and goodbyes using the 'say_goodbye' tool.", + tools=[say_goodbye], + ) + print(f"✅ Sub-Agent '{farewell_agent.name}' redefined.") +except Exception as e: + print(f"❌ Could not redefine Farewell agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}") # --- Define the Root Agent with Both Callbacks --- root_agent_tool_guardrail = None @@ -1433,7 +1544,7 @@ if ('greeting_agent' in globals() and greeting_agent and 'block_keyword_guardrail' in globals() and 'block_paris_tool_guardrail' in globals()): - root_agent_model = MODEL_GEMINI_2_5_PRO + root_agent_model = MODEL_GEMINI_2_0_FLASH root_agent_tool_guardrail = Agent( name="weather_agent_v6_tool_guardrail", # New version name @@ -1464,11 +1575,12 @@ if ('greeting_agent' in globals() and greeting_agent and else: print("❌ Cannot create root agent with tool guardrail. Prerequisites missing.") + ``` --- -**3\. Interact to Test the Tool Guardrail** +### **3\. Interact to Test the Tool Guardrail** Let's test the interaction flow, again using the same stateful session (`SESSION_ID_STATEFUL`) from the previous steps. @@ -1484,11 +1596,10 @@ if runner_root_tool_guardrail: async def run_tool_guardrail_test(): print("\n--- Testing Tool Argument Guardrail ('Paris' blocked) ---") - # Use the runner for the agent with both callbacks and the existing stateful session - interaction_func = lambda query: call_specific_agent_async(runner_root_tool_guardrail, query) - # ^ Reusing interaction helper from Step 2 - # Ensure it uses USER_ID_STATEFUL, SESSION_ID_STATEFUL - + # Use the runner for the agent with both callbacks and the existing stateful session + interaction_func = lambda query: call_agent_async(query, + runner_root_tool_guardrail, USER_ID_STATEFUL, SESSION_ID_STATEFUL + ) # 1. Allowed city (Should pass both callbacks, use Fahrenheit state) await interaction_func("What's the weather in New York?") @@ -1502,7 +1613,9 @@ if runner_root_tool_guardrail: await run_tool_guardrail_test() # Optional: Check state for the tool block trigger flag - final_session = session_service_stateful.get_session(APP_NAME, USER_ID_STATEFUL, SESSION_ID_STATEFUL) + final_session = session_service_stateful.get_session(app_name=APP_NAME, + user_id=USER_ID_STATEFUL, + session_id= SESSION_ID_STATEFUL) if final_session: print("\n--- Final Session State (After Tool Guardrail Test) ---") print(f"Tool Guardrail Triggered Flag: {final_session.state.get('guardrail_tool_block_triggered')}") @@ -1513,7 +1626,6 @@ if runner_root_tool_guardrail: else: print("\n⚠️ Skipping tool guardrail test. Runner ('runner_root_tool_guardrail') is not available.") - ``` (Run the code cell above to generate the output. Keep the output cell here in the markdown) diff --git a/examples/python/notebooks/adk_tutorial.ipynb b/examples/python/notebooks/adk_tutorial.ipynb new file mode 100644 index 0000000000..b107339818 --- /dev/null +++ b/examples/python/notebooks/adk_tutorial.ipynb @@ -0,0 +1,2099 @@ +{ + "nbformat": 4, + "nbformat_minor": 0, + "metadata": { + "colab": { + "provenance": [], + "toc_visible": true + }, + "kernelspec": { + "name": "python3", + "display_name": "Python 3" + }, + "language_info": { + "name": "python" + } + }, + "cells": [ + { + "cell_type": "markdown", + "source": [ + "# Build Your First Intelligent Agent Team: A Progressive Weather Bot with ADK\n", + "\n", + "This tutorial extends from the [Quickstart example](https://google.github.io/adk-docs/get-started/quickstart/) for [Agent Development Kit](https://google.github.io/adk-docs/get-started/). Now, you're ready to dive deeper and construct a more sophisticated, **multi-agent system**.\n", + "\n", + "We'll embark on building a **Weather Bot agent team**, progressively layering advanced features onto a simple foundation. Starting with a single agent that can look up weather, we will incrementally add capabilities like:\n", + "\n", + "* Leveraging different AI models (Gemini, GPT, Claude).\n", + "* Designing specialized sub-agents for distinct tasks (like greetings and farewells).\n", + "* Enabling intelligent delegation between agents.\n", + "* Giving agents memory using persistent session state.\n", + "* Implementing crucial safety guardrails using callbacks.\n", + "\n", + "**Why a Weather Bot Team?**\n", + "\n", + "This use case, while seemingly simple, provides a practical and relatable canvas to explore core ADK concepts essential for building complex, real-world agentic applications. You'll learn how to structure interactions, manage state, ensure safety, and orchestrate multiple AI \"brains\" working together.\n", + "\n", + "**What is ADK Again?**\n", + "\n", + "As a reminder, ADK is a Python framework designed to streamline the development of applications powered by Large Language Models (LLMs). It offers robust building blocks for creating agents that can reason, plan, utilize tools, interact dynamically with users, and collaborate effectively within a team.\n", + "\n", + "**In this advanced tutorial, you will master:**\n", + "\n", + "* ✅ **Tool Definition & Usage:** Crafting Python functions (`tools`) that grant agents specific abilities (like fetching data) and instructing agents on how to use them effectively.\n", + "* ✅ **Multi-LLM Flexibility:** Configuring agents to utilize various leading LLMs (Gemini, GPT-4o, Claude Sonnet) via LiteLLM integration, allowing you to choose the best model for each task.\n", + "* ✅ **Agent Delegation & Collaboration:** Designing specialized sub-agents and enabling automatic routing (`auto flow`) of user requests to the most appropriate agent within a team.\n", + "* ✅ **Session State for Memory:** Utilizing `Session State` and `ToolContext` to enable agents to remember information across conversational turns, leading to more contextual interactions.\n", + "* ✅ **Safety Guardrails with Callbacks:** Implementing `before_model_callback` and `before_tool_callback` to inspect, modify, or block requests/tool usage based on predefined rules, enhancing application safety and control.\n", + "\n", + "**End State Expectation:**\n", + "\n", + "By completing this tutorial, you will have built a functional multi-agent Weather Bot system. This system will not only provide weather information but also handle conversational niceties, remember the last city checked, and operate within defined safety boundaries, all orchestrated using ADK.\n", + "\n", + "**Prerequisites:**\n", + "\n", + "* ✅ **Solid understanding of Python programming.**\n", + "* ✅ **Familiarity with Large Language Models (LLMs), APIs, and the concept of agents.**\n", + "* ❗ **Crucially: Completion of the ADK Quickstart tutorial(s) or equivalent foundational knowledge of ADK basics (Agent, Runner, SessionService, basic Tool usage).** This tutorial builds directly upon those concepts.\n", + "* ✅ **API Keys** for the LLMs you intend to use (e.g., Google AI Studio for Gemini, OpenAI Platform, Anthropic Console).\n", + "\n", + "**Ready to build your agent team? Let's dive in!**" + ], + "metadata": { + "id": "Np0plMPXRvoq" + } + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "ARCoeUZCRNGi" + }, + "outputs": [], + "source": [ + "# @title Step 0: Setup and Installation\n", + "# Install ADK and LiteLLM for multi-model support\n", + "\n", + "!pip install google-adk -q\n", + "!pip install litellm -q\n", + "\n", + "print(\"Installation complete.\")" + ] + }, + { + "cell_type": "code", + "source": [ + "# @title Import necessary libraries\n", + "import os\n", + "import asyncio\n", + "from google.adk.agents import Agent\n", + "from google.adk.models.lite_llm import LiteLlm # For multi-model support\n", + "from google.adk.sessions import InMemorySessionService\n", + "from google.adk.runners import Runner\n", + "from google.genai import types # For creating message Content/Parts\n", + "\n", + "import warnings\n", + "# Ignore all warnings\n", + "warnings.filterwarnings(\"ignore\")\n", + "\n", + "import logging\n", + "logging.basicConfig(level=logging.ERROR)\n", + "\n", + "print(\"Libraries imported.\")" + ], + "metadata": { + "id": "sbwxKypOSBkN" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "source": [ + "# @title Configure API Keys (Replace with your actual keys!)\n", + "\n", + "# --- IMPORTANT: Replace placeholders with your real API keys ---\n", + "\n", + "# Gemini API Key (Get from Google AI Studio: https://aistudio.google.com/app/apikey)\n", + "os.environ[\"GOOGLE_API_KEY\"] = \"YOUR_GOOGLE_API_KEY\" # <--- REPLACE\n", + "\n", + "# OpenAI API Key (Get from OpenAI Platform: https://platform.openai.com/api-keys)\n", + "os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY' # <--- REPLACE\n", + "\n", + "# Anthropic API Key (Get from Anthropic Console: https://console.anthropic.com/settings/keys)\n", + "os.environ['ANTHROPIC_API_KEY'] = 'YOUR_ANTHROPIC_API_KEY' # <--- REPLACE\n", + "\n", + "\n", + "# --- Verify Keys (Optional Check) ---\n", + "print(\"API Keys Set:\")\n", + "print(f\"Google API Key set: {'Yes' if os.environ.get('GOOGLE_API_KEY') and os.environ['GOOGLE_API_KEY'] != 'YOUR_GOOGLE_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}\")\n", + "print(f\"OpenAI API Key set: {'Yes' if os.environ.get('OPENAI_API_KEY') and os.environ['OPENAI_API_KEY'] != 'YOUR_OPENAI_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}\")\n", + "print(f\"Anthropic API Key set: {'Yes' if os.environ.get('ANTHROPIC_API_KEY') and os.environ['ANTHROPIC_API_KEY'] != 'YOUR_ANTHROPIC_API_KEY' else 'No (REPLACE PLACEHOLDER!)'}\")\n", + "\n", + "# Configure ADK to use API keys directly (not Vertex AI for this multi-model setup)\n", + "os.environ[\"GOOGLE_GENAI_USE_VERTEXAI\"] = \"False\"\n", + "\n", + "\n", + "# @markdown **Security Note:** It's best practice to manage API keys securely (e.g., using Colab Secrets or environment variables) rather than hardcoding them directly in the notebook. Replace the placeholder strings above." + ], + "metadata": { + "id": "3mNsVI5eSDOi" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "code", + "source": [ + "# --- Define Model Constants for easier use ---\n", + "\n", + "MODEL_GEMINI_2_0_FLASH = \"gemini-2.0-flash-exp\"\n", + "\n", + "# Note: Specific model names might change. Refer to LiteLLM/Provider documentation.\n", + "MODEL_GPT_4O = \"openai/gpt-4o\"\n", + "MODEL_CLAUDE_SONNET = \"anthropic/claude-3-sonnet-20240229\"\n", + "\n", + "\n", + "print(\"\\nEnvironment configured.\")" + ], + "metadata": { + "id": "MI_qvZJrSJuR" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "## Step 1: Your First Agent \\- Basic Weather Lookup\n", + "\n", + "Let's begin by building the fundamental component of our Weather Bot: a single agent capable of performing a specific task – looking up weather information. This involves creating two core pieces:\n", + "\n", + "1. **A Tool:** A Python function that equips the agent with the *ability* to fetch weather data. \n", + "2. **An Agent:** The AI \"brain\" that understands the user's request, knows it has a weather tool, and decides when and how to use it.\n", + "\n", + "---\n", + "\n", + "**1\\. Define the Tool (`get_weather`)**\n", + "\n", + "In ADK, **Tools** are the building blocks that give agents concrete capabilities beyond just text generation. They are typically regular Python functions that perform specific actions, like calling an API, querying a database, or performing calculations.\n", + "\n", + "Our first tool will provide a *mock* weather report. This allows us to focus on the agent structure without needing external API keys yet. Later, you could easily swap this mock function with one that calls a real weather service.\n", + "\n", + "**Key Concept: Docstrings are Crucial\\!** The agent's LLM relies heavily on the function's **docstring** to understand:\n", + "\n", + "* *What* the tool does. \n", + "* *When* to use it. \n", + "* *What arguments* it requires (`city: str`). \n", + "* *What information* it returns.\n", + "\n", + "**Best Practice:** Write clear, descriptive, and accurate docstrings for your tools. This is essential for the LLM to use the tool correctly." + ], + "metadata": { + "id": "F7LZM3ysSOMu" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define the get_weather Tool\n", + "def get_weather(city: str) -> dict:\n", + " \"\"\"Retrieves the current weather report for a specified city.\n", + "\n", + " Args:\n", + " city (str): The name of the city (e.g., \"New York\", \"London\", \"Tokyo\").\n", + "\n", + " Returns:\n", + " dict: A dictionary containing the weather information.\n", + " Includes a 'status' key ('success' or 'error').\n", + " If 'success', includes a 'report' key with weather details.\n", + " If 'error', includes an 'error_message' key.\n", + " \"\"\"\n", + " print(f\"--- Tool: get_weather called for city: {city} ---\") # Log tool execution\n", + " city_normalized = city.lower().replace(\" \", \"\") # Basic normalization\n", + "\n", + " # Mock weather data\n", + " mock_weather_db = {\n", + " \"newyork\": {\"status\": \"success\", \"report\": \"The weather in New York is sunny with a temperature of 25°C.\"},\n", + " \"london\": {\"status\": \"success\", \"report\": \"It's cloudy in London with a temperature of 15°C.\"},\n", + " \"tokyo\": {\"status\": \"success\", \"report\": \"Tokyo is experiencing light rain and a temperature of 18°C.\"},\n", + " }\n", + "\n", + " if city_normalized in mock_weather_db:\n", + " return mock_weather_db[city_normalized]\n", + " else:\n", + " return {\"status\": \"error\", \"error_message\": f\"Sorry, I don't have weather information for '{city}'.\"}\n", + "\n", + "# Example tool usage (optional test)\n", + "print(get_weather(\"New York\"))\n", + "print(get_weather(\"Paris\"))" + ], + "metadata": { + "id": "ILy7YTCbSRAT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**2\\. Define the Agent (`weather_agent`)**\n", + "\n", + "Now, let's create the **Agent** itself. An `Agent` in ADK orchestrates the interaction between the user, the LLM, and the available tools.\n", + "\n", + "We configure it with several key parameters:\n", + "\n", + "* `name`: A unique identifier for this agent (e.g., \"weather\\_agent\\_v1\"). \n", + "* `model`: Specifies which LLM to use (e.g., `MODEL_GEMINI_2_5_PRO`). We'll start with a specific Gemini model. \n", + "* `description`: A concise summary of the agent's overall purpose. This becomes crucial later when other agents need to decide whether to delegate tasks to *this* agent. \n", + "* `instruction`: Detailed guidance for the LLM on how to behave, its persona, its goals, and specifically *how and when* to utilize its assigned `tools`. \n", + "* `tools`: A list containing the actual Python tool functions the agent is allowed to use (e.g., `[get_weather]`).\n", + "\n", + "**Best Practice:** Provide clear and specific `instruction` prompts. The more detailed the instructions, the better the LLM can understand its role and how to use its tools effectively. Be explicit about error handling if needed.\n", + "\n", + "**Best Practice:** Choose descriptive `name` and `description` values. These are used internally by ADK and are vital for features like automatic delegation (covered later)." + ], + "metadata": { + "id": "hAM0BqGWSTo5" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define the Weather Agent\n", + "# Use one of the model constants defined earlier\n", + "AGENT_MODEL = MODEL_GEMINI_2_0_FLASH # Starting with Gemini\n", + "\n", + "weather_agent = Agent(\n", + " name=\"weather_agent_v1\",\n", + " model=AGENT_MODEL, # Can be a string for Gemini or a LiteLlm object\n", + " description=\"Provides weather information for specific cities.\",\n", + " instruction=\"You are a helpful weather assistant. \"\n", + " \"When the user asks for the weather in a specific city, \"\n", + " \"use the 'get_weather' tool to find the information. \"\n", + " \"If the tool returns an error, inform the user politely. \"\n", + " \"If the tool is successful, present the weather report clearly.\",\n", + " tools=[get_weather], # Pass the function directly\n", + ")\n", + "\n", + "print(f\"Agent '{weather_agent.name}' created using model '{AGENT_MODEL}'.\")" + ], + "metadata": { + "id": "6Ho1COmKSUeV" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**3\\. Setup Runner and Session Service**\n", + "\n", + "To manage conversations and execute the agent, we need two more components:\n", + "\n", + "* `SessionService`: Responsible for managing conversation history and state for different users and sessions. The `InMemorySessionService` is a simple implementation that stores everything in memory, suitable for testing and simple applications. It keeps track of the messages exchanged. We'll explore state persistence more in Step 4\\. \n", + "* `Runner`: The engine that orchestrates the interaction flow. It takes user input, routes it to the appropriate agent, manages calls to the LLM and tools based on the agent's logic, handles session updates via the `SessionService`, and yields events representing the progress of the interaction." + ], + "metadata": { + "id": "Dvz7LDhbSZxL" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Setup Session Service and Runner\n", + "\n", + "# --- Session Management ---\n", + "# Key Concept: SessionService stores conversation history & state.\n", + "# InMemorySessionService is simple, non-persistent storage for this tutorial.\n", + "session_service = InMemorySessionService()\n", + "\n", + "# Define constants for identifying the interaction context\n", + "APP_NAME = \"weather_tutorial_app\"\n", + "USER_ID = \"user_1\"\n", + "SESSION_ID = \"session_001\" # Using a fixed ID for simplicity\n", + "\n", + "# Create the specific session where the conversation will happen\n", + "session = session_service.create_session(\n", + " app_name=APP_NAME,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID\n", + ")\n", + "print(f\"Session created: App='{APP_NAME}', User='{USER_ID}', Session='{SESSION_ID}'\")\n", + "\n", + "# --- Runner ---\n", + "# Key Concept: Runner orchestrates the agent execution loop.\n", + "runner = Runner(\n", + " agent=weather_agent, # The agent we want to run\n", + " app_name=APP_NAME, # Associates runs with our app\n", + " session_service=session_service # Uses our session manager\n", + ")\n", + "print(f\"Runner created for agent '{runner.agent.name}'.\")" + ], + "metadata": { + "id": "h30dNtqMSah5" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**4\\. Interact with the Agent**\n", + "\n", + "We need a way to send messages to our agent and receive its responses. Since LLM calls and tool executions can take time, ADK's `Runner` operates asynchronously.\n", + "\n", + "We'll define an `async` helper function (`call_agent_async`) that:\n", + "\n", + "1. Takes a user query string. \n", + "2. Packages it into the ADK `Content` format. \n", + "3. Calls `runner.run_async`, providing the user/session context and the new message. \n", + "4. Iterates through the **Events** yielded by the runner. Events represent steps in the agent's execution (e.g., tool call requested, tool result received, intermediate LLM thought, final response). \n", + "5. Identifies and prints the **final response** event using `event.is_final_response()`.\n", + "\n", + "**Why `async`?** Interactions with LLMs and potentially tools (like external APIs) are I/O-bound operations. Using `asyncio` allows the program to handle these operations efficiently without blocking execution." + ], + "metadata": { + "id": "5zKGVwRkSduA" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define Agent Interaction Function\n", + "\n", + "from google.genai import types # For creating message Content/Parts\n", + "\n", + "async def call_agent_async(query: str, runner, user_id, session_id):\n", + " \"\"\"Sends a query to the agent and prints the final response.\"\"\"\n", + " print(f\"\\n>>> User Query: {query}\")\n", + "\n", + " # Prepare the user's message in ADK format\n", + " content = types.Content(role='user', parts=[types.Part(text=query)])\n", + "\n", + " final_response_text = \"Agent did not produce a final response.\" # Default\n", + "\n", + " # Key Concept: run_async executes the agent logic and yields Events.\n", + " # We iterate through events to find the final answer.\n", + " async for event in runner.run_async(user_id=user_id, session_id=session_id, new_message=content):\n", + " # You can uncomment the line below to see *all* events during execution\n", + " # print(f\" [Event] Author: {event.author}, Type: {type(event).__name__}, Final: {event.is_final_response()}, Content: {event.content}\")\n", + "\n", + " # Key Concept: is_final_response() marks the concluding message for the turn.\n", + " if event.is_final_response():\n", + " if event.content and event.content.parts:\n", + " # Assuming text response in the first part\n", + " final_response_text = event.content.parts[0].text\n", + " elif event.actions and event.actions.escalate: # Handle potential errors/escalations\n", + " final_response_text = f\"Agent escalated: {event.error_message or 'No specific message.'}\"\n", + " # Add more checks here if needed (e.g., specific error codes)\n", + " break # Stop processing events once the final response is found\n", + "\n", + " print(f\"<<< Agent Response: {final_response_text}\")" + ], + "metadata": { + "id": "yZJr8lbkSebH" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**5\\. Run the Conversation**\n", + "\n", + "Finally, let's test our setup by sending a few queries to the agent. We wrap our `async` calls in a main `async` function and run it using `await`.\n", + "\n", + "Watch the output:\n", + "\n", + "* See the user queries. \n", + "* Notice the `--- Tool: get_weather called... ---` logs when the agent uses the tool. \n", + "* Observe the agent's final responses, including how it handles the case where weather data isn't available (for Paris)." + ], + "metadata": { + "id": "Z6DQSqrqk5ic" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Run the Initial Conversation\n", + "\n", + "# We need an async function to await our interaction helper\n", + "async def run_conversation():\n", + " await call_agent_async(\"What is the weather like in London?\",\n", + " runner=runner,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID)\n", + "\n", + " await call_agent_async(\"How about Paris?\",\n", + " runner=runner,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID) # Expecting the tool's error message\n", + "\n", + " await call_agent_async(\"Tell me the weather in New York\",\n", + " runner=runner,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID)\n", + "\n", + "# Execute the conversation using await in an async context (like Colab/Jupyter)\n", + "await run_conversation()" + ], + "metadata": { + "id": "mEd2QhHyUKY8" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "Congratulations\\! You've successfully built and interacted with your first ADK agent. It understands the user's request, uses a tool to find information, and responds appropriately based on the tool's result.\n", + "\n", + "In the next step, we'll explore how to easily switch the underlying Language Model powering this agent." + ], + "metadata": { + "id": "xbUzAGvsmB2a" + } + }, + { + "cell_type": "markdown", + "source": [ + "## Step 2: Going Multi-Model with LiteLLM\n", + "\n", + "In Step 1, we built a functional Weather Agent powered by a specific Gemini model. While effective, real-world applications often benefit from the flexibility to use *different* Large Language Models (LLMs). Why?\n", + "\n", + "* **Performance:** Some models excel at specific tasks (e.g., coding, reasoning, creative writing).\n", + "* **Cost:** Different models have varying price points.\n", + "* **Capabilities:** Models offer diverse features, context window sizes, and fine-tuning options.\n", + "* **Availability/Redundancy:** Having alternatives ensures your application remains functional even if one provider experiences issues.\n", + "\n", + "ADK makes switching between models seamless through its integration with the [**LiteLLM**](https://github.com/BerriAI/litellm) library. LiteLLM acts as a consistent interface to over 100 different LLMs.\n", + "\n", + "**In this step, we will:**\n", + "\n", + "1. Learn how to configure an ADK `Agent` to use models from providers like OpenAI (GPT) and Anthropic (Claude) using the `LiteLlm` wrapper.\n", + "2. Define, configure (with their own sessions and runners), and immediately test instances of our Weather Agent, each backed by a different LLM.\n", + "3. Interact with these different agents to observe potential variations in their responses, even when using the same underlying tool." + ], + "metadata": { + "id": "HEPaI-beSh8P" + } + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**1\\. Import `LiteLlm`**\n", + "\n", + "We imported this during the initial setup (Step 0), but it's the key component for multi-model support:" + ], + "metadata": { + "id": "OvfhdrCDnPMn" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 1. Import LiteLlm\n", + "from google.adk.models.lite_llm import LiteLlm" + ], + "metadata": { + "id": "mPBr56NSnMje" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "**2\\. Define and Test Multi-Model Agents**\n", + "\n", + "Instead of passing only a model name string (which defaults to Google's Gemini models), we wrap the desired model identifier string within the `LiteLlm` class.\n", + "\n", + "* **Key Concept: `LiteLlm` Wrapper:** The `LiteLlm(model=\"provider/model_name\")` syntax tells ADK to route requests for this agent through the LiteLLM library to the specified model provider.\n", + "\n", + "Make sure you have configured the necessary API keys for OpenAI and Anthropic in Step 0. We'll use the `call_agent_async` function (defined earlier, which now accepts `runner`, `user_id`, and `session_id`) to interact with each agent immediately after its setup.\n", + "\n", + "Each block below will:\n", + "* Define the agent using a specific LiteLLM model (`MODEL_GPT_4O` or `MODEL_CLAUDE_SONNET`).\n", + "* Create a *new, separate* `InMemorySessionService` and session specifically for that agent's test run. This keeps the conversation histories isolated for this demonstration.\n", + "* Create a `Runner` configured for the specific agent and its session service.\n", + "* Immediately call `call_agent_async` to send a query and test the agent.\n", + "\n", + "**Best Practice:** Use constants for model names (like `MODEL_GPT_4O`, `MODEL_CLAUDE_SONNET` defined in Step 0) to avoid typos and make code easier to manage.\n", + "\n", + "**Error Handling:** We wrap the agent definitions in `try...except` blocks. This prevents the entire code cell from failing if an API key for a specific provider is missing or invalid, allowing the tutorial to proceed with the models that *are* configured.\n", + "\n", + "First, let's create and test the agent using OpenAI's GPT-4o." + ], + "metadata": { + "id": "NoUbe1mZnXd9" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define and Test GPT Agent\n", + "\n", + "# Make sure 'get_weather' function from Step 1 is defined in your environment.\n", + "# Make sure 'call_agent_async' is defined from earlier.\n", + "\n", + "# --- Agent using GPT-4o ---\n", + "weather_agent_gpt = None # Initialize to None\n", + "runner_gpt = None # Initialize runner to None\n", + "\n", + "try:\n", + " weather_agent_gpt = Agent(\n", + " name=\"weather_agent_gpt\",\n", + " # Key change: Wrap the LiteLLM model identifier\n", + " model=LiteLlm(model=MODEL_GPT_4O),\n", + " description=\"Provides weather information (using GPT-4o).\",\n", + " instruction=\"You are a helpful weather assistant powered by GPT-4o. \"\n", + " \"Use the 'get_weather' tool for city weather requests. \"\n", + " \"Clearly present successful reports or polite error messages based on the tool's output status.\",\n", + " tools=[get_weather], # Re-use the same tool\n", + " )\n", + " print(f\"Agent '{weather_agent_gpt.name}' created using model '{MODEL_GPT_4O}'.\")\n", + "\n", + " # InMemorySessionService is simple, non-persistent storage for this tutorial.\n", + " session_service_gpt = InMemorySessionService() # Create a dedicated service\n", + "\n", + " # Define constants for identifying the interaction context\n", + " APP_NAME_GPT = \"weather_tutorial_app_gpt\" # Unique app name for this test\n", + " USER_ID_GPT = \"user_1_gpt\"\n", + " SESSION_ID_GPT = \"session_001_gpt\" # Using a fixed ID for simplicity\n", + "\n", + " # Create the specific session where the conversation will happen\n", + " session_gpt = session_service_gpt.create_session(\n", + " app_name=APP_NAME_GPT,\n", + " user_id=USER_ID_GPT,\n", + " session_id=SESSION_ID_GPT\n", + " )\n", + " print(f\"Session created: App='{APP_NAME_GPT}', User='{USER_ID_GPT}', Session='{SESSION_ID_GPT}'\")\n", + "\n", + " # Create a runner specific to this agent and its session service\n", + " runner_gpt = Runner(\n", + " agent=weather_agent_gpt,\n", + " app_name=APP_NAME_GPT, # Use the specific app name\n", + " session_service=session_service_gpt # Use the specific session service\n", + " )\n", + " print(f\"Runner created for agent '{runner_gpt.agent.name}'.\")\n", + "\n", + " # --- Test the GPT Agent ---\n", + " print(\"\\n--- Testing GPT Agent ---\")\n", + " # Ensure call_agent_async uses the correct runner, user_id, session_id\n", + " await call_agent_async(query = \"What's the weather in Tokyo?\",\n", + " runner=runner_gpt,\n", + " user_id=USER_ID_GPT,\n", + " session_id=SESSION_ID_GPT)\n", + "\n", + "except Exception as e:\n", + " print(f\"❌ Could not create or run GPT agent '{MODEL_GPT_4O}'. Check API Key and model name. Error: {e}\")\n" + ], + "metadata": { + "id": "C2WvKj4_Sp2J" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "Next, we'll do the same for Anthropic's Claude Sonnet." + ], + "metadata": { + "id": "Gu_OHirKWFXN" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define and Test Claude Agent\n", + "\n", + "# Make sure 'get_weather' function from Step 1 is defined in your environment.\n", + "# Make sure 'call_agent_async' is defined from earlier.\n", + "\n", + "# --- Agent using Claude Sonnet ---\n", + "weather_agent_claude = None # Initialize to None\n", + "runner_claude = None # Initialize runner to None\n", + "\n", + "try:\n", + " weather_agent_claude = Agent(\n", + " name=\"weather_agent_claude\",\n", + " # Key change: Wrap the LiteLLM model identifier\n", + " model=LiteLlm(model=MODEL_CLAUDE_SONNET),\n", + " description=\"Provides weather information (using Claude Sonnet).\",\n", + " instruction=\"You are a helpful weather assistant powered by Claude Sonnet. \"\n", + " \"Use the 'get_weather' tool for city weather requests. \"\n", + " \"Analyze the tool's dictionary output ('status', 'report'/'error_message'). \"\n", + " \"Clearly present successful reports or polite error messages.\",\n", + " tools=[get_weather], # Re-use the same tool\n", + " )\n", + " print(f\"Agent '{weather_agent_claude.name}' created using model '{MODEL_CLAUDE_SONNET}'.\")\n", + "\n", + " # InMemorySessionService is simple, non-persistent storage for this tutorial.\n", + " session_service_claude = InMemorySessionService() # Create a dedicated service\n", + "\n", + " # Define constants for identifying the interaction context\n", + " APP_NAME_CLAUDE = \"weather_tutorial_app_claude\" # Unique app name\n", + " USER_ID_CLAUDE = \"user_1_claude\"\n", + " SESSION_ID_CLAUDE = \"session_001_claude\" # Using a fixed ID for simplicity\n", + "\n", + " # Create the specific session where the conversation will happen\n", + " session_claude = session_service_claude.create_session(\n", + " app_name=APP_NAME_CLAUDE,\n", + " user_id=USER_ID_CLAUDE,\n", + " session_id=SESSION_ID_CLAUDE\n", + " )\n", + " print(f\"Session created: App='{APP_NAME_CLAUDE}', User='{USER_ID_CLAUDE}', Session='{SESSION_ID_CLAUDE}'\")\n", + "\n", + " # Create a runner specific to this agent and its session service\n", + " runner_claude = Runner(\n", + " agent=weather_agent_claude,\n", + " app_name=APP_NAME_CLAUDE, # Use the specific app name\n", + " session_service=session_service_claude # Use the specific session service\n", + " )\n", + " print(f\"Runner created for agent '{runner_claude.agent.name}'.\")\n", + "\n", + " # --- Test the Claude Agent ---\n", + " print(\"\\n--- Testing Claude Agent ---\")\n", + " # Ensure call_agent_async uses the correct runner, user_id, session_id\n", + " await call_agent_async(query = \"Weather in London please.\",\n", + " runner=runner_claude,\n", + " user_id=USER_ID_CLAUDE,\n", + " session_id=SESSION_ID_CLAUDE)\n", + "\n", + "except Exception as e:\n", + " print(f\"❌ Could not create or run Claude agent '{MODEL_CLAUDE_SONNET}'. Check API Key and model name. Error: {e}\")" + ], + "metadata": { + "id": "7zqJIS4_nhoh" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "Observe the output carefully from both code blocks. You should see:\n", + "\n", + "1. Each agent (`weather_agent_gpt`, `weather_agent_claude`) is created successfully (if API keys are valid).\n", + "2. A dedicated session and runner are set up for each.\n", + "3. Each agent correctly identifies the need to use the `get_weather` tool when processing the query (you'll see the `--- Tool: get_weather called... ---` log).\n", + "4. The *underlying tool logic* remains identical, always returning our mock data.\n", + "5. However, the **final textual response** generated by each agent might differ slightly in phrasing, tone, or formatting. This is because the instruction prompt is interpreted and executed by different LLMs (GPT-4o vs. Claude Sonnet).\n", + "\n", + "This step demonstrates the power and flexibility ADK + LiteLLM provide. You can easily experiment with and deploy agents using various LLMs while keeping your core application logic (tools, fundamental agent structure) consistent.\n", + "\n", + "In the next step, we'll move beyond a single agent and build a small team where agents can delegate tasks to each other!\n", + "\n", + "---" + ], + "metadata": { + "id": "xsroj8NzWMU9" + } + }, + { + "cell_type": "markdown", + "source": [ + "## Step 3: Building an Agent Team \\- Delegation for Greetings & Farewells\n", + "\n", + "In Steps 1 and 2, we built and experimented with a single agent focused solely on weather lookups. While effective for its specific task, real-world applications often involve handling a wider variety of user interactions. We *could* keep adding more tools and complex instructions to our single weather agent, but this can quickly become unmanageable and less efficient.\n", + "\n", + "A more robust approach is to build an **Agent Team**. This involves:\n", + "\n", + "1. Creating multiple, **specialized agents**, each designed for a specific capability (e.g., one for weather, one for greetings, one for calculations). \n", + "2. Designating a **root agent** (or orchestrator) that receives the initial user request. \n", + "3. Enabling the root agent to **delegate** the request to the most appropriate specialized sub-agent based on the user's intent.\n", + "\n", + "**Why build an Agent Team?**\n", + "\n", + "* **Modularity:** Easier to develop, test, and maintain individual agents. \n", + "* **Specialization:** Each agent can be fine-tuned (instructions, model choice) for its specific task. \n", + "* **Scalability:** Simpler to add new capabilities by adding new agents. \n", + "* **Efficiency:** Allows using potentially simpler/cheaper models for simpler tasks (like greetings).\n", + "\n", + "**In this step, we will:**\n", + "\n", + "1. Define simple tools for handling greetings (`say_hello`) and farewells (`say_goodbye`). \n", + "2. Create two new specialized sub-agents: `greeting_agent` and `farewell_agent`. \n", + "3. Update our main weather agent (`weather_agent_v2`) to act as the **root agent**. \n", + "4. Configure the root agent with its sub-agents, enabling **automatic delegation**. \n", + "5. Test the delegation flow by sending different types of requests to the root agent." + ], + "metadata": { + "id": "tL5estZ_VKki" + } + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**1\\. Define Tools for Sub-Agents**\n", + "\n", + "First, let's create the simple Python functions that will serve as tools for our new specialist agents. Remember, clear docstrings are vital for the agents that will use them." + ], + "metadata": { + "id": "tLpXYXxppB4S" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define Tools for Greeting and Farewell Agents\n", + "\n", + "# Ensure 'get_weather' from Step 1 is available if running this step independently.\n", + "# def get_weather(city: str) -> dict: ... (from Step 1)\n", + "\n", + "def say_hello(name: str = \"there\") -> str:\n", + " \"\"\"Provides a simple greeting, optionally addressing the user by name.\n", + "\n", + " Args:\n", + " name (str, optional): The name of the person to greet. Defaults to \"there\".\n", + "\n", + " Returns:\n", + " str: A friendly greeting message.\n", + " \"\"\"\n", + " print(f\"--- Tool: say_hello called with name: {name} ---\")\n", + " return f\"Hello, {name}!\"\n", + "\n", + "def say_goodbye() -> str:\n", + " \"\"\"Provides a simple farewell message to conclude the conversation.\"\"\"\n", + " print(f\"--- Tool: say_goodbye called ---\")\n", + " return \"Goodbye! Have a great day.\"\n", + "\n", + "print(\"Greeting and Farewell tools defined.\")\n", + "\n", + "# Optional self-test\n", + "print(say_hello(\"Alice\"))\n", + "print(say_goodbye())" + ], + "metadata": { + "id": "Qc7dHr4ZVM6X" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**2\\. Define the Sub-Agents (Greeting & Farewell)**\n", + "\n", + "Now, create the `Agent` instances for our specialists. Notice their highly focused `instruction` and, critically, their clear `description`. The `description` is the primary information the *root agent* uses to decide *when* to delegate to these sub-agents.\n", + "\n", + "We can even use different LLMs for these sub-agents\\! Let's assign GPT-4o to the Greeting Agent and keep the Farewell Agent using GPT-4o as well (you could easily switch one to Claude or Gemini if desired and API keys are set).\n", + "\n", + "**Best Practice:** Sub-agent `description` fields should accurately and concisely summarize their specific capability. This is crucial for effective automatic delegation.\n", + "\n", + "**Best Practice:** Sub-agent `instruction` fields should be tailored to their limited scope, telling them exactly what to do and *what not* to do (e.g., \"Your *only* task is...\")." + ], + "metadata": { + "id": "lkv34_tMVPG3" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define Greeting and Farewell Sub-Agents\n", + "\n", + "# Ensure LiteLlm is imported and API keys are set (from Step 0/2)\n", + "# from google.adk.models.lite_llm import LiteLlm\n", + "# MODEL_GPT_4O, MODEL_CLAUDE_SONNET etc. should be defined\n", + "\n", + "# --- Greeting Agent ---\n", + "greeting_agent = None\n", + "try:\n", + " greeting_agent = Agent(\n", + " # Using a potentially different/cheaper model for a simple task\n", + " model=LiteLlm(model=MODEL_GPT_4O),\n", + " name=\"greeting_agent\",\n", + " instruction=\"You are the Greeting Agent. Your ONLY task is to provide a friendly greeting to the user. \"\n", + " \"Use the 'say_hello' tool to generate the greeting. \"\n", + " \"If the user provides their name, make sure to pass it to the tool. \"\n", + " \"Do not engage in any other conversation or tasks.\",\n", + " description=\"Handles simple greetings and hellos using the 'say_hello' tool.\", # Crucial for delegation\n", + " tools=[say_hello],\n", + " )\n", + " print(f\"✅ Agent '{greeting_agent.name}' created using model '{MODEL_GPT_4O}'.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not create Greeting agent. Check API Key ({MODEL_GPT_4O}). Error: {e}\")\n", + "\n", + "# --- Farewell Agent ---\n", + "farewell_agent = None\n", + "try:\n", + " farewell_agent = Agent(\n", + " # Can use the same or a different model\n", + " model=LiteLlm(model=MODEL_GPT_4O), # Sticking with GPT for this example\n", + " name=\"farewell_agent\",\n", + " instruction=\"You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message. \"\n", + " \"Use the 'say_goodbye' tool when the user indicates they are leaving or ending the conversation \"\n", + " \"(e.g., using words like 'bye', 'goodbye', 'thanks bye', 'see you'). \"\n", + " \"Do not perform any other actions.\",\n", + " description=\"Handles simple farewells and goodbyes using the 'say_goodbye' tool.\", # Crucial for delegation\n", + " tools=[say_goodbye],\n", + " )\n", + " print(f\"✅ Agent '{farewell_agent.name}' created using model '{MODEL_GPT_4O}'.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not create Farewell agent. Check API Key ({MODEL_GPT_4O}). Error: {e}\")" + ], + "metadata": { + "id": "tgT7P1doVRA0" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**3\\. Define the Root Agent (Weather Agent v2) with Sub-Agents**\n", + "\n", + "Now, we upgrade our `weather_agent`. The key changes are:\n", + "\n", + "* Adding the `sub_agents` parameter: We pass a list containing the `greeting_agent` and `farewell_agent` instances we just created. \n", + "* Updating the `instruction`: We explicitly tell the root agent *about* its sub-agents and *when* it should delegate tasks to them.\n", + "\n", + "**Key Concept: Automatic Delegation (Auto Flow)** By providing the `sub_agents` list, ADK enables automatic delegation. When the root agent receives a user query, its LLM considers not only its own instructions and tools but also the `description` of each sub-agent. If the LLM determines that a query aligns better with a sub-agent's described capability (e.g., \"Handles simple greetings\"), it will automatically generate a special internal action to *transfer control* to that sub-agent for that turn. The sub-agent then processes the query using its own model, instructions, and tools.\n", + "\n", + "**Best Practice:** Ensure the root agent's instructions clearly guide its delegation decisions. Mention the sub-agents by name and describe the conditions under which delegation should occur." + ], + "metadata": { + "id": "IFL_TLFPVS5P" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Define the Root Agent with Sub-Agents\n", + "\n", + "# Ensure sub-agents were created successfully before defining the root agent.\n", + "# Also ensure the original 'get_weather' tool is defined.\n", + "root_agent = None\n", + "runner_root = None # Initialize runner\n", + "\n", + "if greeting_agent and farewell_agent and 'get_weather' in globals():\n", + " # Let's use a capable Gemini model for the root agent to handle orchestration\n", + " root_agent_model = MODEL_GEMINI_2_0_FLASH\n", + "\n", + " weather_agent_team = Agent(\n", + " name=\"weather_agent_v2\", # Give it a new version name\n", + " model=root_agent_model,\n", + " description=\"The main coordinator agent. Handles weather requests and delegates greetings/farewells to specialists.\",\n", + " instruction=\"You are the main Weather Agent coordinating a team. Your primary responsibility is to provide weather information. \"\n", + " \"Use the 'get_weather' tool ONLY for specific weather requests (e.g., 'weather in London'). \"\n", + " \"You have specialized sub-agents: \"\n", + " \"1. 'greeting_agent': Handles simple greetings like 'Hi', 'Hello'. Delegate to it for these. \"\n", + " \"2. 'farewell_agent': Handles simple farewells like 'Bye', 'See you'. Delegate to it for these. \"\n", + " \"Analyze the user's query. If it's a greeting, delegate to 'greeting_agent'. If it's a farewell, delegate to 'farewell_agent'. \"\n", + " \"If it's a weather request, handle it yourself using 'get_weather'. \"\n", + " \"For anything else, respond appropriately or state you cannot handle it.\",\n", + " tools=[get_weather], # Root agent still needs the weather tool for its core task\n", + " # Key change: Link the sub-agents here!\n", + " sub_agents=[greeting_agent, farewell_agent]\n", + " )\n", + " print(f\"✅ Root Agent '{weather_agent_team.name}' created using model '{root_agent_model}' with sub-agents: {[sa.name for sa in weather_agent_team.sub_agents]}\")\n", + "\n", + "else:\n", + " print(\"❌ Cannot create root agent because one or more sub-agents failed to initialize or 'get_weather' tool is missing.\")\n", + " if not greeting_agent: print(\" - Greeting Agent is missing.\")\n", + " if not farewell_agent: print(\" - Farewell Agent is missing.\")\n", + " if 'get_weather' not in globals(): print(\" - get_weather function is missing.\")\n", + "\n" + ], + "metadata": { + "id": "nniWunchVV8_" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**4\\. Interact with the Agent Team**\n", + "\n", + "Now that we've defined our root agent (`weather_agent_team` - *Note: Ensure this variable name matches the one defined in the previous code block, likely `# @title Define the Root Agent with Sub-Agents`, which might have named it `root_agent`*) with its specialized sub-agents, let's test the delegation mechanism.\n", + "\n", + "The following code block will:\n", + "\n", + "1. Define an `async` function `run_team_conversation`.\n", + "2. Inside this function, create a *new, dedicated* `InMemorySessionService` and a specific session (`session_001_agent_team`) just for this test run. This isolates the conversation history for testing the team dynamics.\n", + "3. Create a `Runner` (`runner_agent_team`) configured to use our `weather_agent_team` (the root agent) and the dedicated session service.\n", + "4. Use our updated `call_agent_async` function to send different types of queries (greeting, weather request, farewell) to the `runner_agent_team`. We explicitly pass the runner, user ID, and session ID for this specific test.\n", + "5. Immediately execute the `run_team_conversation` function.\n", + "\n", + "We expect the following flow:\n", + "\n", + "1. The \"Hello there!\" query goes to `runner_agent_team`.\n", + "2. The root agent (`weather_agent_team`) receives it and, based on its instructions and the `greeting_agent`'s description, delegates the task.\n", + "3. `greeting_agent` handles the query, calls its `say_hello` tool, and generates the response.\n", + "4. The \"What is the weather in New York?\" query is *not* delegated and is handled directly by the root agent using its `get_weather` tool.\n", + "5. The \"Thanks, bye!\" query is delegated to the `farewell_agent`, which uses its `say_goodbye` tool.\n", + "\n" + ], + "metadata": { + "id": "Yg-IjZYVVYXe" + } + }, + { + "cell_type": "code", + "source": [ + "# @title Interact with the Agent Team\n", + "\n", + "# Ensure the root agent (e.g., 'weather_agent_team' or 'root_agent' from the previous cell) is defined.\n", + "# Ensure the call_agent_async function is defined.\n", + "\n", + "# Check if the root agent variable exists before defining the conversation function\n", + "root_agent_var_name = 'root_agent' # Default name from Step 3 guide\n", + "if 'weather_agent_team' in globals(): # Check if user used this name instead\n", + " root_agent_var_name = 'weather_agent_team'\n", + "elif 'root_agent' not in globals():\n", + " print(\"⚠️ Root agent ('root_agent' or 'weather_agent_team') not found. Cannot define run_team_conversation.\")\n", + " # Assign a dummy value to prevent NameError later if the code block runs anyway\n", + " root_agent = None\n", + "\n", + "if root_agent_var_name in globals() and globals()[root_agent_var_name]:\n", + " async def run_team_conversation():\n", + " print(\"\\n--- Testing Agent Team Delegation ---\")\n", + " # InMemorySessionService is simple, non-persistent storage for this tutorial.\n", + " session_service = InMemorySessionService()\n", + "\n", + " # Define constants for identifying the interaction context\n", + " APP_NAME = \"weather_tutorial_agent_team\"\n", + " USER_ID = \"user_1_agent_team\"\n", + " SESSION_ID = \"session_001_agent_team\" # Using a fixed ID for simplicity\n", + "\n", + " # Create the specific session where the conversation will happen\n", + " session = session_service.create_session(\n", + " app_name=APP_NAME,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID\n", + " )\n", + " print(f\"Session created: App='{APP_NAME}', User='{USER_ID}', Session='{SESSION_ID}'\")\n", + "\n", + " # --- Get the actual root agent object ---\n", + " # Use the determined variable name\n", + " actual_root_agent = globals()[root_agent_var_name]\n", + "\n", + " # Create a runner specific to this agent team test\n", + " runner_agent_team = Runner(\n", + " agent=actual_root_agent, # Use the root agent object\n", + " app_name=APP_NAME, # Use the specific app name\n", + " session_service=session_service # Use the specific session service\n", + " )\n", + " # Corrected print statement to show the actual root agent's name\n", + " print(f\"Runner created for agent '{actual_root_agent.name}'.\")\n", + "\n", + " # Always interact via the root agent's runner, passing the correct IDs\n", + " await call_agent_async(query = \"Hello there!\",\n", + " runner=runner_agent_team,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID)\n", + " await call_agent_async(query = \"What is the weather in New York?\",\n", + " runner=runner_agent_team,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID)\n", + " await call_agent_async(query = \"Thanks, bye!\",\n", + " runner=runner_agent_team,\n", + " user_id=USER_ID,\n", + " session_id=SESSION_ID)\n", + "\n", + " # Execute the conversation\n", + " # Note: This may require API keys for the models used by root and sub-agents!\n", + " await run_team_conversation()\n", + "else:\n", + " print(\"\\n⚠️ Skipping agent team conversation as the root agent was not successfully defined in the previous step.\")\n" + ], + "metadata": { + "id": "t9Wy4ai8VZ7H" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "Look closely at the output logs, especially the `--- Tool: ... called ---` messages. You should observe:\n", + "\n", + "* For \"Hello there!\", the `say_hello` tool was called (indicating `greeting_agent` handled it).\n", + "* For \"What is the weather in New York?\", the `get_weather` tool was called (indicating the root agent handled it).\n", + "* For \"Thanks, bye!\", the `say_goodbye` tool was called (indicating `farewell_agent` handled it).\n", + "\n", + "This confirms successful **automatic delegation**! The root agent, guided by its instructions and the `description`s of its `sub_agents`, correctly routed user requests to the appropriate specialist agent within the team.\n", + "\n", + "You've now structured your application with multiple collaborating agents. This modular design is fundamental for building more complex and capable agent systems. In the next step, we'll give our agents the ability to remember information across turns using session state." + ], + "metadata": { + "id": "Zgw3Cn2NVcI7" + } + }, + { + "cell_type": "markdown", + "source": [ + "## Step 4: Adding Memory and Personalization with Session State\n", + "\n", + "So far, our agent team can handle different tasks through delegation, but each interaction starts fresh – the agents have no memory of past conversations or user preferences within a session. To create more sophisticated and context-aware experiences, agents need **memory**. ADK provides this through **Session State**.\n", + "\n", + "**What is Session State?**\n", + "\n", + "* It's a Python dictionary (`session.state`) tied to a specific user session (identified by `APP_NAME`, `USER_ID`, `SESSION_ID`). \n", + "* It persists information *across multiple conversational turns* within that session. \n", + "* Agents and Tools can read from and write to this state, allowing them to remember details, adapt behavior, and personalize responses.\n", + "\n", + "**How Agents Interact with State:**\n", + "\n", + "1. **`ToolContext` (Primary Method):** Tools can accept a `ToolContext` object (automatically provided by ADK if declared as the last argument). This object gives direct access to the session state via `tool_context.state`, allowing tools to read preferences or save results *during* execution. \n", + "2. **`output_key` (Auto-Save Agent Response):** An `Agent` can be configured with an `output_key=\"your_key\"`. ADK will then automatically save the agent's final textual response for a turn into `session.state[\"your_key\"]`.\n", + "\n", + "**In this step, we will enhance our Weather Bot team by:**\n", + "\n", + "1. Using a **new** `InMemorySessionService` to demonstrate state in isolation. \n", + "2. Initializing session state with a user preference for `temperature_unit`. \n", + "3. Creating a state-aware version of the weather tool (`get_weather_stateful`) that reads this preference via `ToolContext` and adjusts its output format (Celsius/Fahrenheit). \n", + "4. Updating the root agent to use this stateful tool and configuring it with an `output_key` to automatically save its final weather report to the session state. \n", + "5. Running a conversation to observe how the initial state affects the tool, how manual state changes alter subsequent behavior, and how `output_key` persists the agent's response." + ], + "metadata": { + "id": "s7gD2sCy1qWz" + } + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**1\\. Initialize New Session Service and State**\n", + "\n", + "To clearly demonstrate state management without interference from prior steps, we'll instantiate a new `InMemorySessionService`. We'll also create a session with an initial state defining the user's preferred temperature unit." + ], + "metadata": { + "id": "HsIjxunW1xeO" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 1. Initialize New Session Service and State\n", + "\n", + "# Import necessary session components\n", + "from google.adk.sessions import InMemorySessionService\n", + "\n", + "# Create a NEW session service instance for this state demonstration\n", + "session_service_stateful = InMemorySessionService()\n", + "print(\"✅ New InMemorySessionService created for state demonstration.\")\n", + "\n", + "# Define a NEW session ID for this part of the tutorial\n", + "SESSION_ID_STATEFUL = \"session_state_demo_001\"\n", + "USER_ID_STATEFUL = \"user_state_demo\"\n", + "\n", + "# Define initial state data - user prefers Celsius initially\n", + "initial_state = {\n", + " \"user_preference_temperature_unit\": \"Celsius\"\n", + "}\n", + "\n", + "# Create the session, providing the initial state\n", + "session_stateful = session_service_stateful.create_session(\n", + " app_name=APP_NAME, # Use the consistent app name\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL,\n", + " state=initial_state # <<< Initialize state during creation\n", + ")\n", + "print(f\"✅ Session '{SESSION_ID_STATEFUL}' created for user '{USER_ID_STATEFUL}'.\")\n", + "\n", + "# Verify the initial state was set correctly\n", + "retrieved_session = session_service_stateful.get_session(app_name=APP_NAME,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id = SESSION_ID_STATEFUL)\n", + "print(\"\\n--- Initial Session State ---\")\n", + "if retrieved_session:\n", + " print(retrieved_session.state)\n", + "else:\n", + " print(\"Error: Could not retrieve session.\")" + ], + "metadata": { + "id": "wt21ea6ctFT5" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**2\\. Create State-Aware Weather Tool (`get_weather_stateful`)**\n", + "\n", + "Now, we create a new version of the weather tool. Its key feature is accepting `tool_context: ToolContext` which allows it to access `tool_context.state`. It will read the `user_preference_temperature_unit` and format the temperature accordingly.\n", + "\n", + "\n", + "* **Key Concept: `ToolContext`** This object is the bridge allowing your tool logic to interact with the session's context, including reading and writing state variables. ADK injects it automatically if defined as the last parameter of your tool function.\n", + "\n", + "\n", + "* **Best Practice:** When reading from state, use `dictionary.get('key', default_value)` to handle cases where the key might not exist yet, ensuring your tool doesn't crash." + ], + "metadata": { + "id": "652bNx3H16lJ" + } + }, + { + "cell_type": "code", + "source": [ + "from google.adk.tools.tool_context import ToolContext\n", + "\n", + "def get_weather_stateful(city: str, tool_context: ToolContext) -> dict:\n", + " \"\"\"Retrieves weather, converts temp unit based on session state.\"\"\"\n", + " print(f\"--- Tool: get_weather_stateful called for {city} ---\")\n", + "\n", + " # --- Read preference from state ---\n", + " preferred_unit = tool_context.state.get(\"user_preference_temperature_unit\", \"Celsius\") # Default to Celsius\n", + " print(f\"--- Tool: Reading state 'user_preference_temperature_unit': {preferred_unit} ---\")\n", + "\n", + " city_normalized = city.lower().replace(\" \", \"\")\n", + "\n", + " # Mock weather data (always stored in Celsius internally)\n", + " mock_weather_db = {\n", + " \"newyork\": {\"temp_c\": 25, \"condition\": \"sunny\"},\n", + " \"london\": {\"temp_c\": 15, \"condition\": \"cloudy\"},\n", + " \"tokyo\": {\"temp_c\": 18, \"condition\": \"light rain\"},\n", + " }\n", + "\n", + " if city_normalized in mock_weather_db:\n", + " data = mock_weather_db[city_normalized]\n", + " temp_c = data[\"temp_c\"]\n", + " condition = data[\"condition\"]\n", + "\n", + " # Format temperature based on state preference\n", + " if preferred_unit == \"Fahrenheit\":\n", + " temp_value = (temp_c * 9/5) + 32 # Calculate Fahrenheit\n", + " temp_unit = \"°F\"\n", + " else: # Default to Celsius\n", + " temp_value = temp_c\n", + " temp_unit = \"°C\"\n", + "\n", + " report = f\"The weather in {city.capitalize()} is {condition} with a temperature of {temp_value:.0f}{temp_unit}.\"\n", + " result = {\"status\": \"success\", \"report\": report}\n", + " print(f\"--- Tool: Generated report in {preferred_unit}. Result: {result} ---\")\n", + "\n", + " # Example of writing back to state (optional for this tool)\n", + " tool_context.state[\"last_city_checked_stateful\"] = city\n", + " print(f\"--- Tool: Updated state 'last_city_checked_stateful': {city} ---\")\n", + "\n", + " return result\n", + " else:\n", + " # Handle city not found\n", + " error_msg = f\"Sorry, I don't have weather information for '{city}'.\"\n", + " print(f\"--- Tool: City '{city}' not found. ---\")\n", + " return {\"status\": \"error\", \"error_message\": error_msg}\n", + "\n", + "print(\"✅ State-aware 'get_weather_stateful' tool defined.\")\n" + ], + "metadata": { + "id": "zK11GeWftFRC" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**3\\. Redefine Sub-Agents and Update Root Agent**\n", + "\n", + "To ensure this step is self-contained and builds correctly, we first redefine the `greeting_agent` and `farewell_agent` exactly as they were in Step 3\\. Then, we define our new root agent (`weather_agent_v4_stateful`):\n", + "\n", + "* It uses the new `get_weather_stateful` tool. \n", + "* It includes the greeting and farewell sub-agents for delegation. \n", + "* **Crucially**, it sets `output_key=\"last_weather_report\"` which automatically saves its final weather response to the session state." + ], + "metadata": { + "id": "UuQMolpG2Qkg" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 3. Redefine Sub-Agents and Update Root Agent with output_key\n", + "\n", + "# Ensure necessary imports: Agent, LiteLlm, Runner\n", + "from google.adk.agents import Agent\n", + "from google.adk.models.lite_llm import LiteLlm\n", + "from google.adk.runners import Runner\n", + "# Ensure tools 'say_hello', 'say_goodbye' are defined (from Step 3)\n", + "# Ensure model constants MODEL_GPT_4O, MODEL_GEMINI_2_5_PRO etc. are defined\n", + "\n", + "# --- Redefine Greeting Agent (from Step 3) ---\n", + "greeting_agent = None\n", + "try:\n", + " greeting_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"greeting_agent\",\n", + " instruction=\"You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.\",\n", + " description=\"Handles simple greetings and hellos using the 'say_hello' tool.\",\n", + " tools=[say_hello],\n", + " )\n", + " print(f\"✅ Agent '{greeting_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Greeting agent. Error: {e}\")\n", + "\n", + "# --- Redefine Farewell Agent (from Step 3) ---\n", + "farewell_agent = None\n", + "try:\n", + " farewell_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"farewell_agent\",\n", + " instruction=\"You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.\",\n", + " description=\"Handles simple farewells and goodbyes using the 'say_goodbye' tool.\",\n", + " tools=[say_goodbye],\n", + " )\n", + " print(f\"✅ Agent '{farewell_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Farewell agent. Error: {e}\")\n", + "\n", + "# --- Define the Updated Root Agent ---\n", + "root_agent_stateful = None\n", + "runner_root_stateful = None # Initialize runner\n", + "\n", + "# Check prerequisites before creating the root agent\n", + "if greeting_agent and farewell_agent and 'get_weather_stateful' in globals():\n", + "\n", + " root_agent_model = MODEL_GEMINI_2_0_FLASH # Choose orchestration model\n", + "\n", + " root_agent_stateful = Agent(\n", + " name=\"weather_agent_v4_stateful\", # New version name\n", + " model=root_agent_model,\n", + " description=\"Main agent: Provides weather (state-aware unit), delegates greetings/farewells, saves report to state.\",\n", + " instruction=\"You are the main Weather Agent. Your job is to provide weather using 'get_weather_stateful'. \"\n", + " \"The tool will format the temperature based on user preference stored in state. \"\n", + " \"Delegate simple greetings to 'greeting_agent' and farewells to 'farewell_agent'. \"\n", + " \"Handle only weather requests, greetings, and farewells.\",\n", + " tools=[get_weather_stateful], # Use the state-aware tool\n", + " sub_agents=[greeting_agent, farewell_agent], # Include sub-agents\n", + " output_key=\"last_weather_report\" # <<< Auto-save agent's final weather response\n", + " )\n", + " print(f\"✅ Root Agent '{root_agent_stateful.name}' created using stateful tool and output_key.\")\n", + "\n", + " # --- Create Runner for this Root Agent & NEW Session Service ---\n", + " runner_root_stateful = Runner(\n", + " agent=root_agent_stateful,\n", + " app_name=APP_NAME,\n", + " session_service=session_service_stateful # Use the NEW stateful session service\n", + " )\n", + " print(f\"✅ Runner created for stateful root agent '{runner_root_stateful.agent.name}' using stateful session service.\")\n", + "\n", + "else:\n", + " print(\"❌ Cannot create stateful root agent. Prerequisites missing.\")\n", + " if not greeting_agent: print(\" - greeting_agent definition missing.\")\n", + " if not farewell_agent: print(\" - farewell_agent definition missing.\")\n", + " if 'get_weather_stateful' not in globals(): print(\" - get_weather_stateful tool missing.\")\n" + ], + "metadata": { + "id": "ox3-2hwTtFOK" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**4\\. Interact and Test State Flow**\n", + "\n", + "Now, let's execute a conversation designed to test the state interactions using the `runner_root_stateful` (associated with our stateful agent and the `session_service_stateful`). We'll use the `call_agent_async` function defined earlier, ensuring we pass the correct runner, user ID (`USER_ID_STATEFUL`), and session ID (`SESSION_ID_STATEFUL`).\n", + "\n", + "The conversation flow will be:\n", + "\n", + "1. **Check weather (London):** The `get_weather_stateful` tool should read the initial \"Celsius\" preference from the session state initialized in Section 1. The root agent's final response (the weather report in Celsius) should get saved to `state['last_weather_report']` via the `output_key` configuration.\n", + "2. **Manually update state:** We will *directly modify* the state stored within the `InMemorySessionService` instance (`session_service_stateful`).\n", + " * **Why direct modification?** The `session_service.get_session()` method returns a *copy* of the session. Modifying that copy wouldn't affect the state used in subsequent agent runs. For this testing scenario with `InMemorySessionService`, we access the internal `sessions` dictionary to change the *actual* stored state value for `user_preference_temperature_unit` to \"Fahrenheit\". *Note: In real applications, state changes are typically triggered by tools or agent logic returning `EventActions(state_delta=...)`, not direct manual updates.*\n", + "3. **Check weather again (New York):** The `get_weather_stateful` tool should now read the updated \"Fahrenheit\" preference from the state and convert the temperature accordingly. The root agent's *new* response (weather in Fahrenheit) will overwrite the previous value in `state['last_weather_report']` due to the `output_key`.\n", + "4. **Greet the agent:** Verify that delegation to the `greeting_agent` still works correctly alongside the stateful operations. This interaction will become the *last* response saved by `output_key` in this specific sequence.\n", + "5. **Inspect final state:** After the conversation, we retrieve the session one last time (getting a copy) and print its state to confirm the `user_preference_temperature_unit` is indeed \"Fahrenheit\", observe the final value saved by `output_key` (which will be the greeting in this run), and see the `last_city_checked_stateful` value written by the tool.\n" + ], + "metadata": { + "id": "P394DfSb2aOw" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 4. Interact to Test State Flow and output_key\n", + "\n", + "# Ensure the stateful runner (runner_root_stateful) is available from the previous cell\n", + "# Ensure call_agent_async, USER_ID_STATEFUL, SESSION_ID_STATEFUL, APP_NAME are defined\n", + "\n", + "if 'runner_root_stateful' in globals() and runner_root_stateful:\n", + " async def run_stateful_conversation():\n", + " print(\"\\n--- Testing State: Temp Unit Conversion & output_key ---\")\n", + "\n", + " # 1. Check weather (Uses initial state: Celsius)\n", + " print(\"--- Turn 1: Requesting weather in London (expect Celsius) ---\")\n", + " await call_agent_async(query= \"What's the weather in London?\",\n", + " runner=runner_root_stateful,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL\n", + " )\n", + "\n", + " # 2. Manually update state preference to Fahrenheit - DIRECTLY MODIFY STORAGE\n", + " print(\"\\n--- Manually Updating State: Setting unit to Fahrenheit ---\")\n", + " try:\n", + " # Access the internal storage directly - THIS IS SPECIFIC TO InMemorySessionService for testing\n", + " stored_session = session_service_stateful.sessions[APP_NAME][USER_ID_STATEFUL][SESSION_ID_STATEFUL]\n", + " stored_session.state[\"user_preference_temperature_unit\"] = \"Fahrenheit\"\n", + " # Optional: You might want to update the timestamp as well if any logic depends on it\n", + " # import time\n", + " # stored_session.last_update_time = time.time()\n", + " print(f\"--- Stored session state updated. Current 'user_preference_temperature_unit': {stored_session.state['user_preference_temperature_unit']} ---\")\n", + " except KeyError:\n", + " print(f\"--- Error: Could not retrieve session '{SESSION_ID_STATEFUL}' from internal storage for user '{USER_ID_STATEFUL}' in app '{APP_NAME}' to update state. Check IDs and if session was created. ---\")\n", + " except Exception as e:\n", + " print(f\"--- Error updating internal session state: {e} ---\")\n", + "\n", + " # 3. Check weather again (Tool should now use Fahrenheit)\n", + " # This will also update 'last_weather_report' via output_key\n", + " print(\"\\n--- Turn 2: Requesting weather in New York (expect Fahrenheit) ---\")\n", + " await call_agent_async(query= \"Tell me the weather in New York.\",\n", + " runner=runner_root_stateful,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL\n", + " )\n", + "\n", + " # 4. Test basic delegation (should still work)\n", + " # This will update 'last_weather_report' again, overwriting the NY weather report\n", + " print(\"\\n--- Turn 3: Sending a greeting ---\")\n", + " await call_agent_async(query= \"Hi!\",\n", + " runner=runner_root_stateful,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL\n", + " )\n", + "\n", + " # Execute the conversation\n", + " await run_stateful_conversation()\n", + "\n", + " # Inspect final session state after the conversation\n", + " print(\"\\n--- Inspecting Final Session State ---\")\n", + " final_session = session_service_stateful.get_session(app_name=APP_NAME,\n", + " user_id= USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL)\n", + " if final_session:\n", + " print(f\"Final Preference: {final_session.state.get('user_preference_temperature_unit')}\")\n", + " print(f\"Final Last Weather Report (from output_key): {final_session.state.get('last_weather_report')}\")\n", + " print(f\"Final Last City Checked (by tool): {final_session.state.get('last_city_checked_stateful')}\")\n", + " # Print full state for detailed view\n", + " # print(f\"Full State: {final_session.state}\")\n", + " else:\n", + " print(\"\\n❌ Error: Could not retrieve final session state.\")\n", + "\n", + "else:\n", + " print(\"\\n⚠️ Skipping state test conversation. Stateful root agent runner ('runner_root_stateful') is not available.\")" + ], + "metadata": { + "id": "WYZfRCp0tFLT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "By reviewing the conversation flow and the final session state printout, you can confirm:\n", + "\n", + "* **State Read:** The weather tool (`get_weather_stateful`) correctly read `user_preference_temperature_unit` from state, initially using \"Celsius\" for London.\n", + "* **State Update:** The direct modification successfully changed the stored preference to \"Fahrenheit\".\n", + "* **State Read (Updated):** The tool subsequently read \"Fahrenheit\" when asked for New York's weather and performed the conversion.\n", + "* **Tool State Write:** The tool successfully wrote the `last_city_checked_stateful` (\"New York\" after the second weather check) into the state via `tool_context.state`.\n", + "* **Delegation:** The delegation to the `greeting_agent` for \"Hi!\" functioned correctly even after state modifications.\n", + "* **`output_key`:** The `output_key=\"last_weather_report\"` successfully saved the root agent's *final* response for *each turn* where the root agent was the one ultimately responding. In this sequence, the last response was the greeting (\"Hello, there!\"), so that overwrote the weather report in the state key.\n", + "* **Final State:** The final check confirms the preference persisted as \"Fahrenheit\".\n", + "\n", + "You've now successfully integrated session state to personalize agent behavior using `ToolContext`, manually manipulated state for testing `InMemorySessionService`, and observed how `output_key` provides a simple mechanism for saving the agent's last response to state. This foundational understanding of state management is key as we proceed to implement safety guardrails using callbacks in the next steps.\n", + "\n", + "---" + ], + "metadata": { + "id": "mqiG4SAX2l8C" + } + }, + { + "cell_type": "markdown", + "source": [ + "## Step 5: Adding Safety \\- Input Guardrail with `before_model_callback`\n", + "\n", + "Our agent team is becoming more capable, remembering preferences and using tools effectively. However, in real-world scenarios, we often need safety mechanisms to control the agent's behavior *before* potentially problematic requests even reach the core Large Language Model (LLM).\n", + "\n", + "ADK provides **Callbacks** – functions that allow you to hook into specific points in the agent's execution lifecycle. The `before_model_callback` is particularly useful for input safety.\n", + "\n", + "**What is `before_model_callback`?**\n", + "\n", + "* It's a Python function you define that ADK executes *just before* an agent sends its compiled request (including conversation history, instructions, and the latest user message) to the underlying LLM. \n", + "* **Purpose:** Inspect the request, modify it if necessary, or block it entirely based on predefined rules.\n", + "\n", + "**Common Use Cases:**\n", + "\n", + "* **Input Validation/Filtering:** Check if user input meets criteria or contains disallowed content (like PII or keywords). \n", + "* **Guardrails:** Prevent harmful, off-topic, or policy-violating requests from being processed by the LLM. \n", + "* **Dynamic Prompt Modification:** Add timely information (e.g., from session state) to the LLM request context just before sending.\n", + "\n", + "**How it Works:**\n", + "\n", + "1. Define a function accepting `callback_context: CallbackContext` and `llm_request: LlmRequest`. \n", + " * `callback_context`: Provides access to agent info, session state (`callback_context.state`), etc. \n", + " * `llm_request`: Contains the full payload intended for the LLM (`contents`, `config`). \n", + "2. Inside the function: \n", + " * **Inspect:** Examine `llm_request.contents` (especially the last user message). \n", + " * **Modify (Use Caution):** You *can* change parts of `llm_request`. \n", + " * **Block (Guardrail):** Return an `LlmResponse` object. ADK will send this response back immediately, *skipping* the LLM call for that turn. \n", + " * **Allow:** Return `None`. ADK proceeds to call the LLM with the (potentially modified) request.\n", + "\n", + "**In this step, we will:**\n", + "\n", + "1. Define a `before_model_callback` function (`block_keyword_guardrail`) that checks the user's input for a specific keyword (\"BLOCK\"). \n", + "2. Update our stateful root agent (`weather_agent_v4_stateful` from Step 4\\) to use this callback. \n", + "3. Create a new runner associated with this updated agent but using the *same stateful session service* to maintain state continuity. \n", + "4. Test the guardrail by sending both normal and keyword-containing requests." + ], + "metadata": { + "id": "JwTcmu0oaEiI" + } + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**1\\. Define the Guardrail Callback Function**\n", + "\n", + "This function will inspect the last user message within the `llm_request` content. If it finds \"BLOCK\" (case-insensitive), it constructs and returns an `LlmResponse` to block the flow; otherwise, it returns `None`. " + ], + "metadata": { + "id": "G7m6zhMv4Zss" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 1. Define the before_model_callback Guardrail\n", + "\n", + "# Ensure necessary imports are available\n", + "from google.adk.agents.callback_context import CallbackContext\n", + "from google.adk.models.llm_request import LlmRequest\n", + "from google.adk.models.llm_response import LlmResponse\n", + "from google.genai import types # For creating response content\n", + "from typing import Optional\n", + "\n", + "def block_keyword_guardrail(\n", + " callback_context: CallbackContext, llm_request: LlmRequest\n", + ") -> Optional[LlmResponse]:\n", + " \"\"\"\n", + " Inspects the latest user message for 'BLOCK'. If found, blocks the LLM call\n", + " and returns a predefined LlmResponse. Otherwise, returns None to proceed.\n", + " \"\"\"\n", + " agent_name = callback_context.agent_name # Get the name of the agent whose model call is being intercepted\n", + " print(f\"--- Callback: block_keyword_guardrail running for agent: {agent_name} ---\")\n", + "\n", + " # Extract the text from the latest user message in the request history\n", + " last_user_message_text = \"\"\n", + " if llm_request.contents:\n", + " # Find the most recent message with role 'user'\n", + " for content in reversed(llm_request.contents):\n", + " if content.role == 'user' and content.parts:\n", + " # Assuming text is in the first part for simplicity\n", + " if content.parts[0].text:\n", + " last_user_message_text = content.parts[0].text\n", + " break # Found the last user message text\n", + "\n", + " print(f\"--- Callback: Inspecting last user message: '{last_user_message_text[:100]}...' ---\") # Log first 100 chars\n", + "\n", + " # --- Guardrail Logic ---\n", + " keyword_to_block = \"BLOCK\"\n", + " if keyword_to_block in last_user_message_text.upper(): # Case-insensitive check\n", + " print(f\"--- Callback: Found '{keyword_to_block}'. Blocking LLM call! ---\")\n", + " # Optionally, set a flag in state to record the block event\n", + " callback_context.state[\"guardrail_block_keyword_triggered\"] = True\n", + " print(f\"--- Callback: Set state 'guardrail_block_keyword_triggered': True ---\")\n", + "\n", + " # Construct and return an LlmResponse to stop the flow and send this back instead\n", + " return LlmResponse(\n", + " content=types.Content(\n", + " role=\"model\", # Mimic a response from the agent's perspective\n", + " parts=[types.Part(text=f\"I cannot process this request because it contains the blocked keyword '{keyword_to_block}'.\")],\n", + " )\n", + " # Note: You could also set an error_message field here if needed\n", + " )\n", + " else:\n", + " # Keyword not found, allow the request to proceed to the LLM\n", + " print(f\"--- Callback: Keyword not found. Allowing LLM call for {agent_name}. ---\")\n", + " return None # Returning None signals ADK to continue normally\n", + "\n", + "print(\"✅ block_keyword_guardrail function defined.\")\n" + ], + "metadata": { + "id": "JZay2mbHaHSk" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**2\\. Update Root Agent to Use the Callback**\n", + "\n", + "We redefine the root agent, adding the `before_model_callback` parameter and pointing it to our new guardrail function. We'll give it a new version name for clarity.\n", + "\n", + "*Important:* We need to redefine the sub-agents (`greeting_agent`, `farewell_agent`) and the stateful tool (`get_weather_stateful`) within this context if they are not already available from previous steps, ensuring the root agent definition has access to all its components." + ], + "metadata": { + "id": "giawLd9VaI7G" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 2. Update Root Agent with before_model_callback\n", + "\n", + "\n", + "# --- Redefine Sub-Agents (Ensures they exist in this context) ---\n", + "greeting_agent = None\n", + "try:\n", + " # Use a defined model constant\n", + " greeting_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"greeting_agent\", # Keep original name for consistency\n", + " instruction=\"You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.\",\n", + " description=\"Handles simple greetings and hellos using the 'say_hello' tool.\",\n", + " tools=[say_hello],\n", + " )\n", + " print(f\"✅ Sub-Agent '{greeting_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Greeting agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}\")\n", + "\n", + "farewell_agent = None\n", + "try:\n", + " # Use a defined model constant\n", + " farewell_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"farewell_agent\", # Keep original name\n", + " instruction=\"You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.\",\n", + " description=\"Handles simple farewells and goodbyes using the 'say_goodbye' tool.\",\n", + " tools=[say_goodbye],\n", + " )\n", + " print(f\"✅ Sub-Agent '{farewell_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Farewell agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}\")\n", + "\n", + "\n", + "# --- Define the Root Agent with the Callback ---\n", + "root_agent_model_guardrail = None\n", + "runner_root_model_guardrail = None\n", + "\n", + "# Check all components before proceeding\n", + "if greeting_agent and farewell_agent and 'get_weather_stateful' in globals() and 'block_keyword_guardrail' in globals():\n", + "\n", + " # Use a defined model constant like MODEL_GEMINI_2_5_PRO\n", + " root_agent_model = MODEL_GEMINI_2_0_FLASH\n", + "\n", + " root_agent_model_guardrail = Agent(\n", + " name=\"weather_agent_v5_model_guardrail\", # New version name for clarity\n", + " model=root_agent_model,\n", + " description=\"Main agent: Handles weather, delegates greetings/farewells, includes input keyword guardrail.\",\n", + " instruction=\"You are the main Weather Agent. Provide weather using 'get_weather_stateful'. \"\n", + " \"Delegate simple greetings to 'greeting_agent' and farewells to 'farewell_agent'. \"\n", + " \"Handle only weather requests, greetings, and farewells.\",\n", + " tools=[get_weather],\n", + " sub_agents=[greeting_agent, farewell_agent], # Reference the redefined sub-agents\n", + " output_key=\"last_weather_report\", # Keep output_key from Step 4\n", + " before_model_callback=block_keyword_guardrail # <<< Assign the guardrail callback\n", + " )\n", + " print(f\"✅ Root Agent '{root_agent_model_guardrail.name}' created with before_model_callback.\")\n", + "\n", + " # --- Create Runner for this Agent, Using SAME Stateful Session Service ---\n", + " # Ensure session_service_stateful exists from Step 4\n", + " if 'session_service_stateful' in globals():\n", + " runner_root_model_guardrail = Runner(\n", + " agent=root_agent_model_guardrail,\n", + " app_name=APP_NAME, # Use consistent APP_NAME\n", + " session_service=session_service_stateful # <<< Use the service from Step 4\n", + " )\n", + " print(f\"✅ Runner created for guardrail agent '{runner_root_model_guardrail.agent.name}', using stateful session service.\")\n", + " else:\n", + " print(\"❌ Cannot create runner. 'session_service_stateful' from Step 4 is missing.\")\n", + "\n", + "else:\n", + " print(\"❌ Cannot create root agent with model guardrail. One or more prerequisites are missing or failed initialization:\")\n", + " if not greeting_agent: print(\" - Greeting Agent\")\n", + " if not farewell_agent: print(\" - Farewell Agent\")\n", + " if 'get_weather_stateful' not in globals(): print(\" - 'get_weather_stateful' tool\")\n", + " if 'block_keyword_guardrail' not in globals(): print(\" - 'block_keyword_guardrail' callback\")" + ], + "metadata": { + "id": "IRoMmJ9V_cuH" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**3\\. Interact to Test the Guardrail**\n", + "\n", + "Let's test the guardrail's behavior. We'll use the *same session* (`SESSION_ID_STATEFUL`) as in Step 4 to show that state persists across these changes.\n", + "\n", + "1. Send a normal weather request (should pass the guardrail and execute). \n", + "2. Send a request containing \"BLOCK\" (should be intercepted by the callback). \n", + "3. Send a greeting (should pass the root agent's guardrail, be delegated, and execute normally)." + ], + "metadata": { + "id": "R2EW2LSS4wnz" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 3. Interact to Test the Model Input Guardrail\n", + "\n", + "# Ensure the runner for the guardrail agent is available\n", + "if runner_root_model_guardrail:\n", + " async def run_guardrail_test_conversation():\n", + " print(\"\\n--- Testing Model Input Guardrail ---\")\n", + "\n", + " # Use the runner for the agent with the callback and the existing stateful session ID\n", + " interaction_func = lambda query: call_agent_async(query,\n", + " runner_root_model_guardrail, USER_ID_STATEFUL, SESSION_ID_STATEFUL # <-- Pass correct IDs\n", + " )\n", + " # 1. Normal request (Callback allows, should use Fahrenheit from Step 4 state change)\n", + " await interaction_func(\"What is the weather in London?\")\n", + "\n", + " # 2. Request containing the blocked keyword\n", + " await interaction_func(\"BLOCK the request for weather in Tokyo\")\n", + "\n", + " # 3. Normal greeting (Callback allows root agent, delegation happens)\n", + " await interaction_func(\"Hello again\")\n", + "\n", + "\n", + " # Execute the conversation\n", + " await run_guardrail_test_conversation()\n", + "\n", + " # Optional: Check state for the trigger flag set by the callback\n", + " final_session = session_service_stateful.get_session(app_name=APP_NAME,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id=SESSION_ID_STATEFUL)\n", + " if final_session:\n", + " print(\"\\n--- Final Session State (After Guardrail Test) ---\")\n", + " print(f\"Guardrail Triggered Flag: {final_session.state.get('guardrail_block_keyword_triggered')}\")\n", + " print(f\"Last Weather Report: {final_session.state.get('last_weather_report')}\") # Should be London weather\n", + " print(f\"Temperature Unit: {final_session.state.get('user_preference_temperature_unit')}\") # Should be Fahrenheit\n", + " else:\n", + " print(\"\\n❌ Error: Could not retrieve final session state.\")\n", + "\n", + "else:\n", + " print(\"\\n⚠️ Skipping model guardrail test. Runner ('runner_root_model_guardrail') is not available.\")\n", + "\n" + ], + "metadata": { + "id": "4EnMiXX8aO9n" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "Observe the execution flow:\n", + "\n", + "1. **London Weather:** The callback runs for `weather_agent_v5_model_guardrail`, inspects the message, prints \"Keyword not found. Allowing LLM call.\", and returns `None`. The agent proceeds, calls the `get_weather_stateful` tool (which uses the \"Fahrenheit\" preference from Step 4's state change), and returns the weather. This response updates `last_weather_report` via `output_key`. \n", + "2. **BLOCK Request:** The callback runs again for `weather_agent_v5_model_guardrail`, inspects the message, finds \"BLOCK\", prints \"Blocking LLM call\\!\", sets the state flag, and returns the predefined `LlmResponse`. The agent's underlying LLM is *never called* for this turn. The user sees the callback's blocking message. \n", + "3. **Hello Again:** The callback runs for `weather_agent_v5_model_guardrail`, allows the request. The root agent then delegates to `greeting_agent`. *Note: The `before_model_callback` defined on the root agent does NOT automatically apply to sub-agents.* The `greeting_agent` proceeds normally, calls its `say_hello` tool, and returns the greeting.\n", + "\n", + "You have successfully implemented an input safety layer\\! The `before_model_callback` provides a powerful mechanism to enforce rules and control agent behavior *before* expensive or potentially risky LLM calls are made. Next, we'll apply a similar concept to add guardrails around tool usage itself." + ], + "metadata": { + "id": "e5D0KaW-aQ8z" + } + }, + { + "cell_type": "markdown", + "source": [ + "## Step 6: Adding Safety \\- Tool Argument Guardrail (`before_tool_callback`)\n", + "\n", + "In Step 5, we added a guardrail to inspect and potentially block user input *before* it reached the LLM. Now, we'll add another layer of control *after* the LLM has decided to use a tool but *before* that tool actually executes. This is useful for validating the *arguments* the LLM wants to pass to the tool.\n", + "\n", + "ADK provides the `before_tool_callback` for this precise purpose.\n", + "\n", + "**What is `before_tool_callback`?**\n", + "\n", + "* It's a Python function executed just *before* a specific tool function runs, after the LLM has requested its use and decided on the arguments. \n", + "* **Purpose:** Validate tool arguments, prevent tool execution based on specific inputs, modify arguments dynamically, or enforce resource usage policies.\n", + "\n", + "**Common Use Cases:**\n", + "\n", + "* **Argument Validation:** Check if arguments provided by the LLM are valid, within allowed ranges, or conform to expected formats. \n", + "* **Resource Protection:** Prevent tools from being called with inputs that might be costly, access restricted data, or cause unwanted side effects (e.g., blocking API calls for certain parameters). \n", + "* **Dynamic Argument Modification:** Adjust arguments based on session state or other contextual information before the tool runs.\n", + "\n", + "**How it Works:**\n", + "\n", + "1. Define a function accepting `tool: BaseTool`, `args: Dict[str, Any]`, and `tool_context: ToolContext`. \n", + " * `tool`: The tool object about to be called (inspect `tool.name`). \n", + " * `args`: The dictionary of arguments the LLM generated for the tool. \n", + " * `tool_context`: Provides access to session state (`tool_context.state`), agent info, etc. \n", + "2. Inside the function: \n", + " * **Inspect:** Examine the `tool.name` and the `args` dictionary. \n", + " * **Modify:** Change values within the `args` dictionary *directly*. If you return `None`, the tool runs with these modified args. \n", + " * **Block/Override (Guardrail):** Return a **dictionary**. ADK treats this dictionary as the *result* of the tool call, completely *skipping* the execution of the original tool function. The dictionary should ideally match the expected return format of the tool it's blocking. \n", + " * **Allow:** Return `None`. ADK proceeds to execute the actual tool function with the (potentially modified) arguments.\n", + "\n", + "**In this step, we will:**\n", + "\n", + "1. Define a `before_tool_callback` function (`block_paris_tool_guardrail`) that specifically checks if the `get_weather_stateful` tool is called with the city \"Paris\". \n", + "2. If \"Paris\" is detected, the callback will block the tool and return a custom error dictionary. \n", + "3. Update our root agent (`weather_agent_v6_tool_guardrail`) to include *both* the `before_model_callback` and this new `before_tool_callback`. \n", + "4. Create a new runner for this agent, using the same stateful session service. \n", + "5. Test the flow by requesting weather for allowed cities and the blocked city (\"Paris\")." + ], + "metadata": { + "id": "ZnH5C0IRaqet" + } + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**1\\. Define the Tool Guardrail Callback Function**\n", + "\n", + "This function targets the `get_weather_stateful` tool. It checks the `city` argument. If it's \"Paris\", it returns an error dictionary that looks like the tool's own error response. Otherwise, it allows the tool to run by returning `None`." + ], + "metadata": { + "id": "H5myniS17Q5q" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 1. Define the before_tool_callback Guardrail\n", + "\n", + "# Ensure necessary imports are available\n", + "from google.adk.tools.base_tool import BaseTool\n", + "from google.adk.tools.tool_context import ToolContext\n", + "from typing import Optional, Dict, Any # For type hints\n", + "\n", + "def block_paris_tool_guardrail(\n", + " tool: BaseTool, args: Dict[str, Any], tool_context: ToolContext\n", + ") -> Optional[Dict]:\n", + " \"\"\"\n", + " Checks if 'get_weather_stateful' is called for 'Paris'.\n", + " If so, blocks the tool execution and returns a specific error dictionary.\n", + " Otherwise, allows the tool call to proceed by returning None.\n", + " \"\"\"\n", + " tool_name = tool.name\n", + " agent_name = tool_context.agent_name # Agent attempting the tool call\n", + " print(f\"--- Callback: block_paris_tool_guardrail running for tool '{tool_name}' in agent '{agent_name}' ---\")\n", + " print(f\"--- Callback: Inspecting args: {args} ---\")\n", + "\n", + " # --- Guardrail Logic ---\n", + " target_tool_name = \"get_weather_stateful\" # Match the function name used by FunctionTool\n", + " blocked_city = \"paris\"\n", + "\n", + " # Check if it's the correct tool and the city argument matches the blocked city\n", + " if tool_name == target_tool_name:\n", + " city_argument = args.get(\"city\", \"\") # Safely get the 'city' argument\n", + " if city_argument and city_argument.lower() == blocked_city:\n", + " print(f\"--- Callback: Detected blocked city '{city_argument}'. Blocking tool execution! ---\")\n", + " # Optionally update state\n", + " tool_context.state[\"guardrail_tool_block_triggered\"] = True\n", + " print(f\"--- Callback: Set state 'guardrail_tool_block_triggered': True ---\")\n", + "\n", + " # Return a dictionary matching the tool's expected output format for errors\n", + " # This dictionary becomes the tool's result, skipping the actual tool run.\n", + " return {\n", + " \"status\": \"error\",\n", + " \"error_message\": f\"Policy restriction: Weather checks for '{city_argument.capitalize()}' are currently disabled by a tool guardrail.\"\n", + " }\n", + " else:\n", + " print(f\"--- Callback: City '{city_argument}' is allowed for tool '{tool_name}'. ---\")\n", + " else:\n", + " print(f\"--- Callback: Tool '{tool_name}' is not the target tool. Allowing. ---\")\n", + "\n", + "\n", + " # If the checks above didn't return a dictionary, allow the tool to execute\n", + " print(f\"--- Callback: Allowing tool '{tool_name}' to proceed. ---\")\n", + " return None # Returning None allows the actual tool function to run\n", + "\n", + "print(\"✅ block_paris_tool_guardrail function defined.\")\n", + "\n" + ], + "metadata": { + "id": "g4wOLl6aastz" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**2\\. Update Root Agent to Use Both Callbacks**\n", + "\n", + "We redefine the root agent again (`weather_agent_v6_tool_guardrail`), this time adding the `before_tool_callback` parameter alongside the `before_model_callback` from Step 5\\.\n", + "\n", + "*Self-Contained Execution Note:* Similar to Step 5, ensure all prerequisites (sub-agents, tools, `before_model_callback`) are defined or available in the execution context before defining this agent." + ], + "metadata": { + "id": "4d01OYJlauSI" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 2. Update Root Agent with BOTH Callbacks (Self-Contained)\n", + "\n", + "# --- Ensure Prerequisites are Defined ---\n", + "# (Include or ensure execution of definitions for: Agent, LiteLlm, Runner, ToolContext,\n", + "# MODEL constants, say_hello, say_goodbye, greeting_agent, farewell_agent,\n", + "# get_weather_stateful, block_keyword_guardrail, block_paris_tool_guardrail)\n", + "\n", + "# --- Redefine Sub-Agents (Ensures they exist in this context) ---\n", + "greeting_agent = None\n", + "try:\n", + " # Use a defined model constant like MODEL_GPT_4O\n", + " greeting_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"greeting_agent\", # Keep original name for consistency\n", + " instruction=\"You are the Greeting Agent. Your ONLY task is to provide a friendly greeting using the 'say_hello' tool. Do nothing else.\",\n", + " description=\"Handles simple greetings and hellos using the 'say_hello' tool.\",\n", + " tools=[say_hello],\n", + " )\n", + " print(f\"✅ Sub-Agent '{greeting_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Greeting agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}\")\n", + "\n", + "farewell_agent = None\n", + "try:\n", + " # Use a defined model constant like MODEL_GPT_4O\n", + " farewell_agent = Agent(\n", + " model=MODEL_GEMINI_2_0_FLASH,\n", + " name=\"farewell_agent\", # Keep original name\n", + " instruction=\"You are the Farewell Agent. Your ONLY task is to provide a polite goodbye message using the 'say_goodbye' tool. Do not perform any other actions.\",\n", + " description=\"Handles simple farewells and goodbyes using the 'say_goodbye' tool.\",\n", + " tools=[say_goodbye],\n", + " )\n", + " print(f\"✅ Sub-Agent '{farewell_agent.name}' redefined.\")\n", + "except Exception as e:\n", + " print(f\"❌ Could not redefine Farewell agent. Check Model/API Key ({MODEL_GPT_4O}). Error: {e}\")\n", + "\n", + "# --- Define the Root Agent with Both Callbacks ---\n", + "root_agent_tool_guardrail = None\n", + "runner_root_tool_guardrail = None\n", + "\n", + "if ('greeting_agent' in globals() and greeting_agent and\n", + " 'farewell_agent' in globals() and farewell_agent and\n", + " 'get_weather_stateful' in globals() and\n", + " 'block_keyword_guardrail' in globals() and\n", + " 'block_paris_tool_guardrail' in globals()):\n", + "\n", + " root_agent_model = MODEL_GEMINI_2_0_FLASH\n", + "\n", + " root_agent_tool_guardrail = Agent(\n", + " name=\"weather_agent_v6_tool_guardrail\", # New version name\n", + " model=root_agent_model,\n", + " description=\"Main agent: Handles weather, delegates, includes input AND tool guardrails.\",\n", + " instruction=\"You are the main Weather Agent. Provide weather using 'get_weather_stateful'. \"\n", + " \"Delegate greetings to 'greeting_agent' and farewells to 'farewell_agent'. \"\n", + " \"Handle only weather, greetings, and farewells.\",\n", + " tools=[get_weather_stateful],\n", + " sub_agents=[greeting_agent, farewell_agent],\n", + " output_key=\"last_weather_report\",\n", + " before_model_callback=block_keyword_guardrail, # Keep model guardrail\n", + " before_tool_callback=block_paris_tool_guardrail # <<< Add tool guardrail\n", + " )\n", + " print(f\"✅ Root Agent '{root_agent_tool_guardrail.name}' created with BOTH callbacks.\")\n", + "\n", + " # --- Create Runner, Using SAME Stateful Session Service ---\n", + " if 'session_service_stateful' in globals():\n", + " runner_root_tool_guardrail = Runner(\n", + " agent=root_agent_tool_guardrail,\n", + " app_name=APP_NAME,\n", + " session_service=session_service_stateful # <<< Use the service from Step 4/5\n", + " )\n", + " print(f\"✅ Runner created for tool guardrail agent '{runner_root_tool_guardrail.agent.name}', using stateful session service.\")\n", + " else:\n", + " print(\"❌ Cannot create runner. 'session_service_stateful' from Step 4/5 is missing.\")\n", + "\n", + "else:\n", + " print(\"❌ Cannot create root agent with tool guardrail. Prerequisites missing.\")\n", + "\n" + ], + "metadata": { + "id": "8BVIl_3uLTZT" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "**3\\. Interact to Test the Tool Guardrail**\n", + "\n", + "Let's test the interaction flow, again using the same stateful session (`SESSION_ID_STATEFUL`) from the previous steps.\n", + "\n", + "1. Request weather for \"New York\": Passes both callbacks, tool executes (using Fahrenheit preference from state). \n", + "2. Request weather for \"Paris\": Passes `before_model_callback`. LLM decides to call `get_weather_stateful(city='Paris')`. `before_tool_callback` intercepts, blocks the tool, and returns the error dictionary. Agent relays this error. \n", + "3. Request weather for \"London\": Passes both callbacks, tool executes normally." + ], + "metadata": { + "id": "aUo-nu657kc8" + } + }, + { + "cell_type": "code", + "source": [ + "# @title 3. Interact to Test the Tool Argument Guardrail\n", + "\n", + "# Ensure the runner for the tool guardrail agent is available\n", + "if runner_root_tool_guardrail:\n", + " async def run_tool_guardrail_test():\n", + " print(\"\\n--- Testing Tool Argument Guardrail ('Paris' blocked) ---\")\n", + "\n", + " # Use the runner for the agent with both callbacks and the existing stateful session\n", + " interaction_func = lambda query: call_agent_async(query,\n", + " runner_root_tool_guardrail, USER_ID_STATEFUL, SESSION_ID_STATEFUL\n", + " )\n", + " # 1. Allowed city (Should pass both callbacks, use Fahrenheit state)\n", + " await interaction_func(\"What's the weather in New York?\")\n", + "\n", + " # 2. Blocked city (Should pass model callback, but be blocked by tool callback)\n", + " await interaction_func(\"How about Paris?\")\n", + "\n", + " # 3. Another allowed city (Should work normally again)\n", + " await interaction_func(\"Tell me the weather in London.\")\n", + "\n", + " # Execute the conversation\n", + " await run_tool_guardrail_test()\n", + "\n", + " # Optional: Check state for the tool block trigger flag\n", + " final_session = session_service_stateful.get_session(app_name=APP_NAME,\n", + " user_id=USER_ID_STATEFUL,\n", + " session_id= SESSION_ID_STATEFUL)\n", + " if final_session:\n", + " print(\"\\n--- Final Session State (After Tool Guardrail Test) ---\")\n", + " print(f\"Tool Guardrail Triggered Flag: {final_session.state.get('guardrail_tool_block_triggered')}\")\n", + " print(f\"Last Weather Report: {final_session.state.get('last_weather_report')}\") # Should be London weather\n", + " print(f\"Temperature Unit: {final_session.state.get('user_preference_temperature_unit')}\") # Should be Fahrenheit\n", + " else:\n", + " print(\"\\n❌ Error: Could not retrieve final session state.\")\n", + "\n", + "else:\n", + " print(\"\\n⚠️ Skipping tool guardrail test. Runner ('runner_root_tool_guardrail') is not available.\")" + ], + "metadata": { + "id": "wpg4fzkLav1-" + }, + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "source": [ + "---\n", + "\n", + "Analyze the output:\n", + "\n", + "1. **New York:** The `before_model_callback` allows the request. The LLM requests `get_weather_stateful`. The `before_tool_callback` runs, inspects the args (`{'city': 'New York'}`), sees it's not \"Paris\", prints \"Allowing tool...\" and returns `None`. The actual `get_weather_stateful` function executes, reads \"Fahrenheit\" from state, and returns the weather report. The agent relays this, and it gets saved via `output_key`. \n", + "2. **Paris:** The `before_model_callback` allows the request. The LLM requests `get_weather_stateful(city='Paris')`. The `before_tool_callback` runs, inspects the args, detects \"Paris\", prints \"Blocking tool execution\\!\", sets the state flag, and returns the error dictionary `{'status': 'error', 'error_message': 'Policy restriction...'}`. The actual `get_weather_stateful` function is **never executed**. The agent receives the error dictionary *as if it were the tool's output* and formulates a response based on that error message. \n", + "3. **London:** Behaves like New York, passing both callbacks and executing the tool successfully. The new London weather report overwrites the `last_weather_report` in the state.\n", + "\n", + "You've now added a crucial safety layer controlling not just *what* reaches the LLM, but also *how* the agent's tools can be used based on the specific arguments generated by the LLM. Callbacks like `before_model_callback` and `before_tool_callback` are essential for building robust, safe, and policy-compliant agent applications." + ], + "metadata": { + "id": "6gCcBgMfa1VS" + } + }, + { + "cell_type": "markdown", + "source": [ + "\n", + "\n", + "---\n", + "\n", + "\n", + "## Conclusion: Your Agent Team is Ready!\n", + "\n", + "Congratulations! You've successfully journeyed from building a single, basic weather agent to constructing a sophisticated, multi-agent team using the Agent Development Kit (ADK).\n", + "\n", + "**Let's recap what you've accomplished:**\n", + "\n", + "* You started with a **fundamental agent** equipped with a single tool (`get_weather`).\n", + "* You explored ADK's **multi-model flexibility** using LiteLLM, running the same core logic with different LLMs like Gemini, GPT-4o, and Claude.\n", + "* You embraced **modularity** by creating specialized sub-agents (`greeting_agent`, `farewell_agent`) and enabling **automatic delegation** from a root agent.\n", + "* You gave your agents **memory** using **Session State**, allowing them to remember user preferences (`temperature_unit`) and past interactions (`output_key`).\n", + "* You implemented crucial **safety guardrails** using both `before_model_callback` (blocking specific input keywords) and `before_tool_callback` (blocking tool execution based on arguments like the city \"Paris\").\n", + "\n", + "Through building this progressive Weather Bot team, you've gained hands-on experience with core ADK concepts essential for developing complex, intelligent applications.\n", + "\n", + "**Key Takeaways:**\n", + "\n", + "* **Agents & Tools:** The fundamental building blocks for defining capabilities and reasoning. Clear instructions and docstrings are paramount.\n", + "* **Runners & Session Services:** The engine and memory management system that orchestrate agent execution and maintain conversational context.\n", + "* **Delegation:** Designing multi-agent teams allows for specialization, modularity, and better management of complex tasks. Agent `description` is key for auto-flow.\n", + "* **Session State (`ToolContext`, `output_key`):** Essential for creating context-aware, personalized, and multi-turn conversational agents.\n", + "* **Callbacks (`before_model`, `before_tool`):** Powerful hooks for implementing safety, validation, policy enforcement, and dynamic modifications *before* critical operations (LLM calls or tool execution).\n", + "* **Flexibility (`LiteLlm`):** ADK empowers you to choose the best LLM for the job, balancing performance, cost, and features.\n", + "\n", + "**Where to Go Next?**\n", + "\n", + "Your Weather Bot team is a great starting point. Here are some ideas to further explore ADK and enhance your application:\n", + "\n", + "1. **Real Weather API:** Replace the `mock_weather_db` in your `get_weather` tool with a call to a real weather API (like OpenWeatherMap, WeatherAPI).\n", + "2. **More Complex State:** Store more user preferences (e.g., preferred location, notification settings) or conversation summaries in the session state.\n", + "3. **Refine Delegation:** Experiment with different root agent instructions or sub-agent descriptions to fine-tune the delegation logic. Could you add a \"forecast\" agent?\n", + "4. **Advanced Callbacks:**\n", + " * Use `after_model_callback` to potentially reformat or sanitize the LLM's response *after* it's generated.\n", + " * Use `after_tool_callback` to process or log the results returned by a tool.\n", + " * Implement `before_agent_callback` or `after_agent_callback` for agent-level entry/exit logic.\n", + "5. **Error Handling:** Improve how the agent handles tool errors or unexpected API responses. Maybe add retry logic within a tool.\n", + "6. **Persistent Session Storage:** Explore alternatives to `InMemorySessionService` for storing session state persistently (e.g., using databases like Firestore or Cloud SQL – requires custom implementation or future ADK integrations).\n", + "7. **Streaming UI:** Integrate your agent team with a web framework (like FastAPI, as shown in the ADK Streaming Quickstart) to create a real-time chat interface.\n", + "\n", + "The Agent Development Kit provides a robust foundation for building sophisticated LLM-powered applications. By mastering the concepts covered in this tutorial – tools, state, delegation, and callbacks – you are well-equipped to tackle increasingly complex agentic systems.\n", + "\n", + "Happy building!" + ], + "metadata": { + "id": "xYWtGbdI8DZw" + } + } + ] +} \ No newline at end of file