Google Agent Development Kit: Build & Test Python AI Agents

This guide walks you through using Google’s Agent Development Kit (ADK) to create and test Python-based AI agents. You’ll learn how to set up the environment, define an agent, run it locally, and use the built-in testing tools. By the end, you’ll have a working agent and the knowledge to extend it for your own use cases.

What You’ll Need

• Python 3.9 or later installed on your machine.
• pip (Python package installer) available.
• A Google Cloud project (optional but recommended for using Vertex AI models).
• An API key for the model you plan to use (e.g., Gemini API key) or access to Vertex AI.
• Basic familiarity with Python and command-line tools.

Step-by-Step

1. Install the Agent Development Kit
   Open your terminal and run:
   pip install google-adk
   This installs the core library and its dependencies.
2. Set up your API credentials
   If using Gemini, set your API key as an environment variable:
   export GOOGLE_API_KEY="your-api-key"
   For Vertex AI, authenticate with:
   gcloud auth application-default login
3. Create a project directory
   Make a folder for your agent, e.g., my_agent/, and navigate into it.
4. Define your agent
   Create a file named agent.py. Start with a simple agent that echoes user input:

   from google.adk.agents import Agent
   
   agent = Agent(
       name="echo_agent",
       model="gemini-1.5-flash",
       instruction="You are a helpful assistant that repeats what the user says."
   )
   

5. Run the agent locally
   Use the ADK CLI to start a local session:
   adk run agent.py
   This launches an interactive chat in the terminal. Type a message and press Enter to see the agent’s response.
6. Test with the built-in test runner
   Create a test file test_agent.py:

   from google.adk.testing import AgentTestCase
   import agent
   
   class TestEchoAgent(AgentTestCase):
       def test_echo(self):
           result = self.run_agent(agent.agent, "Hello")
           self.assertIn("Hello", result.response)
   

   Run tests with:
   python -m pytest test_agent.py

7. Add tools to your agent
   Define a function and pass it to the tools parameter:

   def get_weather(city: str) -> str:
       """Returns weather for a city."""
       return f"Sunny in {city}"
   
   agent = Agent(
       name="weather_agent",
       model="gemini-1.5-flash",
       instruction="You can check weather.",
       tools=[get_weather]
   )
   

8. Use the web UI for debugging
   Run adk web to open a browser-based interface where you can interact with your agent, view logs, and inspect tool calls.
9. Deploy to Vertex AI (optional)
   Use the ADK CLI to deploy:
   adk deploy --project your-project-id --location us-central1
   Follow the prompts to set up the endpoint.

Common Mistakes

• Forgetting to set the API key – The agent won’t start without valid credentials.
• Using an unsupported model name – Check the ADK documentation for available models; typos cause errors.
• Not installing the CLI – The adk command may not be in your PATH if you used a virtual environment; ensure it’s activated.
• Misunderstanding tool schema – Tools must have type hints and docstrings; otherwise, the model can’t call them correctly.
• Ignoring test failures – Tests can fail due to non-deterministic model responses; use assertions that check for key phrases rather than exact matches.

Tips

• Start with a simple agent and gradually add tools to avoid debugging complexity.
• Use the web UI to see the full conversation history and tool call traces – it’s invaluable for understanding agent behavior.
• Keep your instructions clear and specific; the model follows them closely.
• Use environment variables for credentials instead of hardcoding them in your code.
• Write tests that cover edge cases, like empty input or tool errors, to ensure robustness.

Troubleshooting

• Agent doesn’t start: “ModuleNotFoundError: No module named ‘google.adk'”
  Reinstall with pip install --upgrade google-adk and ensure your virtual environment is active.
• Authentication errors
  Verify your API key is correct and has the necessary permissions. For Vertex AI, check that your project has billing enabled.
• Model returns empty responses
  Try a different model or increase the temperature parameter in the agent configuration.
• Tools not being called
  Ensure your function has a clear docstring and type hints. Test the function directly first.
• CLI command not found
  Install the CLI separately: pip install google-adk-cli or check your PATH.

Frequently Asked Questions

1. Can I use open-source models with ADK?
   Yes, ADK supports any model that implements the Google GenAI SDK interface, including open models like Llama or Mistral, as long as you have the appropriate API endpoint.
2. How do I add memory to my agent?
   Use the memory parameter in the Agent constructor, e.g., memory=InMemoryMemory(). This stores conversation history across turns.
3. Can I run ADK agents in production?
   Yes, you can deploy to Vertex AI or run them in a container using the provided Dockerfile. The ADK is designed for production use.
4. What is the difference between ADK and LangChain?
   ADK is Google’s official framework, tightly integrated with Google Cloud and Gemini models. LangChain is a third-party framework with broader model support. Choose ADK if you’re in the Google ecosystem.
5. How do I debug a tool call that fails?
   Use the web UI to see the exact error message. Check that your function handles exceptions and returns a string, as the model expects a string response.
6. Is ADK free?
   The ADK library itself is open-source and free, but you pay for model inference (e.g., Gemini API usage) and any cloud resources used.

Related

• Card Reader File Recovery: How It Works
• MySQL Keeps Crashing? How to Find the Cause
• Change Fonts LG G7: Step-by-Step Guide