I was recently building a small research assistant that needed to verify claims against reliable sources. I started with one of the popular agent frameworks, and after two hours of wrestling with abstract base classes, dependency injection containers, and three different configuration files, I still didn't have a working prototype. I just wanted to pass a claim to a model, let it search, and return whether the claim was accurate. That shouldn't require a 400-line boilerplate project.
That frustration led me to Google's Agent Development Kit (ADK). It's open-source, code-first, and the promise was simple: build a functional agent in under 100 lines of Python. I was skeptical, but I gave it a shot. Here's how it actually went, from setup to a working fact-checking agent running in a local web UI.
Setting Up the Environment
First, I needed to get the prerequisites sorted. You'll need Python (I used 3.12) and uv, which is a fast Python package manager. If you haven't used uv before, it's worth the switch from pip for the speed alone. I was running uv version 0.11.7.
You'll also need a Gemini API key from Google AI Studio. This part caught me off guard slightly—you need a Google Cloud Platform account with billing enabled or active GCP credits to use the API key for Gemini. If you don't have that set up already, budget an extra 15 minutes for the GCP console dance.
Once I had the API key, I created my project directory and set up a virtual environment:
mkdir fact-checker-agent && cd fact-checker-agent
uv venv
source .venv/bin/activate
Then, install the ADK Python package:
uv pip install google-adk
This pulls in the framework and its dependencies. Clean and straightforward—no weird dependency conflicts on my machine, which was a pleasant surprise.
Building the Fact-Checker Agent
Now for the actual code. In ADK, an agent is defined declaratively. You specify the model, give it a name, write clear instructions, and attach any tools it needs. I created a file called agent.py:
from google.adk import Agent
from google.adk.tools import google_search
fact_checker = Agent(
name="fact_checker",
model="gemini-2.0-flash",
instruction="""You are a precise fact-checking assistant. When a user presents a claim,
you must:
1. Search for reliable sources to verify the claim
2. Evaluate the credibility of the sources you find
3. Provide a clear verdict: TRUE, FALSE, PARTIALLY TRUE, or UNVERIFIABLE
4. Cite the sources you used to reach your conclusion
5. If the claim is nuanced, explain the context
Always be transparent about your confidence level. If you cannot find sufficient
information, say so rather than guessing.""",
tools=[google_search]
)
That's it. That's the entire agent definition. Let me break down what's happening here:
- name: An identifier for the agent. This matters more when you start building multi-agent systems, but it's required even for single agents.
- model: I chose
gemini-2.0-flashbecause it's fast and cost-effective for a fact-checking use case. You can use other Gemini models depending on your needs. - instruction: This is the system prompt. I spent time crafting this carefully because the quality of the agent's output depends heavily on how well you specify its behavior. The structured format (verdict + sources + confidence) keeps responses consistent.
- tools: I gave it
google_search, which is a built-in tool in ADK. This is what lets the agent actually look things up rather than relying solely on training data.
The google_search tool integration was where I expected complexity, but ADK handles the tool-calling loop internally. The agent decides when to search, parses the results, and incorporates them into its response. I didn't have to write any HTTP request handling or result parsing code.
Running the Agent in the CLI
Before jumping to a fancy UI, I wanted to test it in the terminal first. ADK provides a CLI runner that lets you interact with your agent directly. I created a simple entry point:
# main.py
from agent import fact_checker
if __name__ == "__main__":
from google.adk.cli import run_agent
run_agent(fact_checker)
Then I ran it:
python main.py
This opens an interactive prompt in your terminal. I tested it with a few claims:
Me: "The Great Wall of China is visible from space with the naked eye."
Agent: "VERDICT: FALSE. This is a common misconception. Multiple astronauts, including those on the International Space Station, have confirmed that the Great Wall is not visible from low Earth orbit with the naked eye. It's too narrow (about 6 meters wide in most sections) and blends with the surrounding terrain. Sources: NASA reports, statements from astronaut Jeffrey Hoffman and ISS Commander Chris Hadfield."
Me: "Honey never spoils."
Agent: "VERDICT: TRUE (with nuance). Archaeologists have found pots of honey in ancient Egyptian tombs that are over 3,000 years old and still perfectly edible. Honey's low moisture content, acidic pH, and natural hydrogen peroxide production create an inhospitable environment for bacteria and microorganisms. However, honey can ferment if exposed to moisture. Sources: Smithsonian Magazine, Journal of Archaeological Science."
The responses were structured exactly as I specified in the instructions, and the search results were being pulled in real-time. The CLI mode is great for quick iteration on your instructions—you can see immediately how changes to the prompt affect behavior.
One mistake I made early on: my first version of the instruction was too vague, just saying "check if claims are true." The agent would give wishy-washy answers without citations. Adding the explicit structure (verdict, sources, confidence) made a huge difference in output quality.
Running the Agent with the Web UI
The CLI is fine for development, but ADK also ships with a built-in web playground. This was the feature that genuinely surprised me—I didn't expect a polished local UI out of the box.
To launch it:
adk web
This starts a local server and opens a browser-based interface where you can chat with your agent. The web UI shows the conversation thread, and more importantly, it shows the agent's tool calls. You can see exactly when it decides to search, what query it sends, and what results come back. This transparency is invaluable for debugging.
When I first ran adk web, I got an error because I hadn't set my API key as an environment variable. The fix was simple:
export GOOGLE_API_KEY="your-api-key-here"
adk web
In the web UI, I could see the full tool-calling trace. For the honey claim, I watched the agent formulate a search query, get results, then formulate a second more specific query about archaeological evidence, and synthesize both into the final answer. Seeing that reasoning chain helped me understand that my agent was actually doing multi-step research, not just pattern-matching.
Practical Tips and Honest Limitations
After spending a weekend building with ADK, here's what I've learned:
Start with the instructions. The quality of your agent is 80% determined by how well you write the instruction prompt. Spend time there before adding complexity.
Use the web UI for debugging. The tool call visibility alone makes it worth running adk web instead of just testing in the CLI. You'll catch issues like the agent searching for the wrong thing much faster.
The built-in tools are limited but solid. google_search works well, but if you need custom tools (like calling your own APIs or databases), you'll need to write those as Python functions with the @tool decorator. The documentation for custom tools is still maturing, so expect some trial and error.
It's Python-first. ADK supports TypeScript, Go, Java, and Kotlin, but the Python SDK is clearly the most mature based on the samples and community activity. If you're choosing a language, go with Python for now.
The real limitation is single-agent scope. This fact-checker works great on its own, but ADK's real power supposedly comes from multi-agent systems where agents delegate to each other. I haven't explored that yet, and the learning curve looks steeper there.
API costs add up. Each fact check involves at least one search-augmented call to Gemini. If you're running this in production, monitor your API usage. Gemini 2.0 Flash is cheap, but it's not free.
Overall, ADK delivered on its promise. I went from zero to a working, useful agent in under an hour with less than 30 lines of actual code. The built-in web playground and tool visibility make it genuinely pleasant to develop with. If you're tired of framework boilerplate and just want to build something that works, give it a try.