Want to create smart AI agents without getting lost in complex frameworks? Google’s Agent Development Kit (ADK) makes it super easy. This guide will get you started with a simple “Math” agent, step-by-step.
What is the Google ADK?
The ADK helps you build AI agents that can understand, reason, and act. It connects your code with powerful Large Language Models (LLMs), letting the AI decide when and how to use your custom functions.
Key Concepts:
- Tools (tools.py): These are regular Python functions that the AI can “call.” You describe what they do in their docstrings, and the LLM reads these descriptions to understand how to use them.
- Agent (agent.py): This is your AI’s brain. It defines the agent, registers the tools it can use, and handles interactions.
- Prompt (prompts.py): This file contains the instructions that guide your agent’s overall behavior.
Let’s Build a Simple Math Agent! 🧮
We’ll create an agent that can do basic math: addition, subtraction, multiplication, division, and exponents.
Step 1: Prerequisites & Setup
First, ensure you have Python installed on your system. Next, create a new project folder and set up a virtual environment to manage your dependencies:
# Create and navigate into your project folder
mkdir math_agent_project
cd math_agent_project# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
Now, install the Google ADK library:
pip install google-adk
Create .env file to store GOOGLE_API_KEY
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Step 2: Project Structure
To keep our agent organized, we’ll structure the code into agent.py, prompts.py, and tools.py within a math_agent directory. This separation of concerns makes your agent’s components more manageable and readable.
./math_agent_project/
└── math_agent/
├── __init__.py
├── agent.py
├── prompts.py
└── tools.py
Here’s what each file will contain:
agent.py
from google.adk.agents import LlmAgent
from .tools import math_tools
from .prompts import MATH_AGENT_INSTRUCTION # Define the agent
math_agent = LlmAgent(
name="math_agent",
model="gemini-1.5-flash",
instruction=MATH_AGENT_INSTRUCTION,
tools=math_tools,
)
# ADK's 'adk run' command expects a variable named 'agent' in agent.py
root_agent = math_agent
prompt.py
MATH_AGENT_INSTRUCTION = """You are a helpful Math Agent designed to perform basic calculations.
When the user asks you to compute something:
1. Identify the mathematical expression from the user's request.
2. Use the 'calculate' tool to evaluate the expression.
3. Pass the extracted expression string to the 'expression' argument of the 'calculate' tool.
4. Return the value from the 'result' key in the tool's output to the user.Examples:
- User: "What is 2 plus 2?" -> Call calculate(expression="2 + 2")
- User: "Calculate 10 * (3 + 4)" -> Call calculate(expression="10 * (3 + 4)")
- User: "5 to the power of 3" -> Call calculate(expression="5**3")
If the 'calculate' tool returns an 'error' key, present the error message to the user.
Do not attempt to perform calculations yourself; ALWAYS use the 'calculate' tool.
"""
tools.py
import ast
import operator as op
from typing import Dict, Any
# from google.adk.tools import tool# Supported operators
_operators = {
ast.Add: op.add,
ast.Sub: op.sub,
ast.Mult: op.mul,
ast.Div: op.truediv,
ast.Pow: op.pow,
ast.USub: op.neg
}
def _eval_node(node):
if isinstance(node, ast.Num): #
return node.n
elif isinstance(node, ast.Constant): # Constant value (e.g., numbers)
return node.value
elif isinstance(node, ast.BinOp): #
left_val = _eval_node(node.left)
right_val = _eval_node(node.right)
return _operators[type(node.op)](left_val, right_val)
elif isinstance(node, ast.UnaryOp): # e.g., -1
operand_val = _eval_node(node.operand)
return _operators[type(node.op)](operand_val)
else:
raise TypeError(f"Unsupported node type: {type(node).__name__}")
def _eval_expr(expr):
"""
Safely evaluates a mathematical expression string.
Supports basic arithmetic operations: +, -, *, /, ** (power), and parentheses.
"""
return _eval_node(ast.parse(expr, mode='eval').body)
def calculate(expression: str) -> Dict[str, Any]:
"""
Calculates the result of a basic mathematical expression.
Args:
expression: A string representing the mathematical expression (e.g., "2 + 3 * 4", "(100 - 20) / 2**3").
Supports +, -, *, /, ** (power), and parentheses.
Returns:
A dictionary containing the 'result' or an 'error'.
"""
try:
if len(expression) > 200:
return {"error": "Expression is too long."}
result = _eval_expr(expression)
return {"result": str(result)}
except (TypeError, SyntaxError, KeyError, ZeroDivisionError) as e:
return {"error": f"Error evaluating expression: {e}"}
except Exception as e:
return {"error": f"An unexpected error occurred: {e}"}
# You can group multiple tools in a list if needed
math_tools = [calculate]
Step 3: Run Your Agent! 🚀
This is the fun part! The ADK includes a built-in web interface for testing your agent.
- Make sure you are in the
math_agent_projectdirectory in your terminal. - Run the following command:
adk web
- Your terminal will show that a local server has started, usually at
http://127.0.0.1:8000
- Open that URL in your web browser. You will see a simple and clean chat interface.
Now you can chat with your agent! Try asking it some math questions:
- “What is 25 * 4?”
- “Calculate (100 / 5) + 10”
- “What is 2 to the power of 10?”
- “A postman traveled from his post office to a village in order to distribute mail. He started on his bicycle from the post office at a speed of 25 km/hr. But, when he was about to return, a thief stole his bicycle. As a result, he had to walk back to the post office on foot at the speed of 4 km/hr. If the traveling part of his day lasted for 2 hours and 54 minutes, find the distance between the post office and the village.”
Congratulations! You’ve just built and run your first AI agent. From here, you can add more tools, refine the prompts, and build even more complex and helpful agents. Happy building!
Source Credit: https://medium.com/google-cloud/building-your-first-ai-agent-a-beginners-guide-to-the-google-agent-development-kit-adk-dd208c273d75?source=rss—-e52cf94d98af—4
