> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build your first agent
> Tutorial showing how to scaffold and run a minimal Google ADK Python agent with simple tools for time and weather, and how the LLM routes tool calls
In this lesson you'll scaffold and run a minimal Google ADK agent — a "hello world" style example that shows how to:
* scaffold an agent,
* register simple tools,
* and let the LLM decide which tool to call based on natural language.
This step-by-step walkthrough covers creating a Python virtual environment, installing the Google ADK package, scaffolding a starter application, implementing two deterministic tools (get\_current\_time and get\_current\_weather), and running the agent interactively.
What we'll do
* Create and activate a Python virtual environment
* Install google-adk
* Scaffold an ADK app
* Add two simple tools
* Run the agent and interact with it
Create and activate a virtual environment (macOS / Linux shown):
```bash theme={null}
# Create venv
python3 -m venv .venv
# Activate venv (macOS / Linux)
source .venv/bin/activate
# Your prompt should indicate the venv is active, e.g.:
# (.venv) jeremy@MACSTUDIO hello-world %
```
Install the Google ADK package inside the virtual environment:
```bash theme={null}
(.venv) jeremy@MACSTUDIO hello-world % pip install google-adk
```
The package installs several dependencies; expect to download multiple MBs.
Scaffold a new ADK application from your project root:
```bash theme={null}
(.venv) jeremy@MACSTUDIO hello-world % adk create my_agent
```
Follow the interactive prompts. For this lesson choose the Gemini model and Google AI backend:
```text theme={null}
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 1
Don't have API Key? Create one in AI Studio: https://aistudio.google.com/apikey
Enter Google API key:
```
After entering your API key the scaffold creates a basic layout (files like `__init__.py` and `agent.py`). The generated `agent.py` is the canonical place to register your agent and tools.
Example agent.py
Below is a minimal `agent.py` that defines two deterministic tools and registers them with the root agent. These are intentionally hard-coded for clarity; replace them with real API calls in production.
```python theme={null}
# agent.py
from google.adk.agents.llm_agent import Agent
def get_current_time(city: str) -> dict:
"""Returns the current time in a specified city."""
# Hard-coded for demonstration
return {"status": "success", "city": city, "time": "10:30 AM"}
def get_current_weather(city: str) -> dict:
"""Returns the current weather in a specified city."""
# Hard-coded for demonstration
return {"status": "success", "city": city, "weather": "Sunny, 75°F"}
root_agent = Agent(
model="gemini-2.5-flash",
name="root_agent",
description="Tells the current time or weather in a specific city.",
instruction=(
"You are a helpful assistant that can provide the current time and the current weather in cities. "
"Use the 'get_current_time' tool to get the time and the 'get_current_weather' tool to get the weather."
),
tools=[get_current_time, get_current_weather],
)
```
Why register tools this way?
* instruction: The text given to the LLM that defines the agent's behavior and available tools.
* tools: A list of Python callables the model may invoke. The LLM chooses which tool to call based on the user query.
Run the agent from the project root:
```bash theme={null}
(.venv) jeremy@MACSTUDIO hello-world % adk run my_agent
```
A typical interactive session:
```text theme={null}
Log setup complete: /tmp/agents_log/agent.log
/Users/jeremy/.../.venv/lib/python3.14/site-packages/google/adk/cli/cli.py:155: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice.
credential_service = InMemoryCredentialService()
Running agent root_agent, type exit to exit.
[user]: What do you do?
[root_agent]: I can tell you the current time or weather in a specific city. Just ask me something like "What time is it in New York?" or "What's the weather like in London?"
[user]: What time is it in New York City?
[root_agent]: The current time in New York is 10:30 AM.
[user]: What is the weather in Tokyo?
[root_agent]: The weather in Tokyo is currently Sunny, 75°F.
[user]:
```
Key concepts and best practices
* The LLM acts as a router: the instruction plus the user query determines which tool (if any) gets invoked.
* Tools are plain Python callables and can wrap HTTP APIs, SDKs, or complex business logic.
* For production, use real services (timezone APIs, weather APIs), robust error handling, timeouts, and non-blocking I/O when appropriate.
* Keep tool signatures simple and well-documented (type hints and short docstrings improve the LLM's ability to choose correctly).
Tooling at a glance
| Component | Purpose | Example / Notes |
| ----------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| Agent instruction | Tells the model what tools are available and how to behave | Use clear, concise language describing tools and when to use them |
| tools parameter | Registers Python callables the agent may invoke | Functions, API wrappers, async callables (if supported) |
| Model selection | Chooses the LLM that will act as the router and responder | gemini-2.5-flash used in this tutorial |
| Backend | Underlying runtime for the model | Google AI (AI Studio) or Vertex AI |
Tip: Keep your tool interfaces simple and well-documented (type hints and concise docstrings help the LLM choose the right tool). In production, prefer non-blocking calls and proper error handling in tools.
Warning: Some ADK features are experimental and may emit warnings at runtime. Pay attention to those messages and review the ADK changelog when upgrading.
Why this structure matters
* The model performs semantic routing: given the instruction and a user prompt, it decides which tool to call and how to format the call.
* This approach separates decision-making (LLM) from execution (tools/APIs), enabling safer, auditable, and extensible agents.
* It mirrors retrieval-augmented patterns: the LLM identifies the appropriate capability or data source and returns the result in natural language.
Summary
* We created a Python virtual environment, installed google-adk, scaffolded a project, added two deterministic tools, and ran an interactive agent that uses the LLM to choose tools based on natural language.
* To build a production-ready agent, replace the stub tools with real API integrations (timezone, weather, or other services), add robust error handling, and monitor agent behavior.
Links and references
* [Google ADK course](https://learn.kodekloud.com/user/courses/google-adk)
* AI Studio: [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)
* For more on agent design patterns, consult the ADK documentation included with the package or the provider's model docs.