Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Google’s Agent Development Kit (ADK) gives Python developers a code-first way to define an agent, attach ordinary Python tools, run conversations locally, and evaluate behavior against repeatable test cases. For a new project, use Python 3.11 or later in a virtual environment, install google-adk, scaffold an agent with adk create, and keep the first implementation deliberately small. Use adk run for terminal conversations, adk web for development debugging, and the Agents CLI evaluation commands when you need regression evidence instead of anecdotal chat results. Validate locally before choosing a hosted path such as Cloud Run or Agent Runtime.
What is Google’s Agent Development Kit?
Google describes ADK as an open-source framework for building, evaluating, debugging, orchestrating, and deploying AI agents. Its Python package is named google-adk. The framework is model-agnostic and deployment-agnostic, while offering particularly close integration with Gemini models.
As an Amazon Associate I earn from qualifying purchases.
In practical terms, ADK supplies the application structure around a model call. You define a root agent in Python, give it an instruction, and optionally expose tools as Python functions. ADK then provides command-line and browser-based development workflows, multi-agent composition, workflow support, evaluation features, and deployment integrations.
That distinction matters: an agent is not just a prompt sent to a model. A useful agent needs a controlled set of actions, clear input and output expectations, tests for failure cases, and a deployment process that preserves those controls. ADK is intended to cover that lifecycle in code rather than leaving each concern in unrelated scripts.
What do I need before installing ADK?
You need a working Python installation, pip, basic Python proficiency, and credentials for the model provider you select. The current Python quickstart lists Python 3.10 or later, while the repository README for the current stable release recommends Python 3.11 or newer. Using Python 3.11 or later for a new project is the least ambiguous choice; check the release documentation if you must remain on 3.10.
- Python: Prefer 3.11 or newer for a new project, subject to the release you install.
- Package manager:
pipmust be available in the interpreter or virtual environment you use. - Credentials: Configure the authentication variables required by your chosen model provider in the project’s
.envfile. - Skills: Be comfortable reading functions, docstrings, exceptions, and simple tests. The official codelab assumes basic Python proficiency.
Model names and authentication settings are release-sensitive. Treat the model identifier in an example as configuration, not as a permanent guarantee: verify the currently supported name and credential variables for your provider before running the project.
How do I create an ADK Python project?
Create an isolated environment, install the package, and let the ADK command-line tool generate the initial project. Run these commands from the directory where you keep your projects:
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk
adk create my_agentOn Windows PowerShell, activate the environment with .venvScriptsActivate.ps1; on Windows Command Prompt, use .venvScriptsactivate.bat. If PowerShell blocks script activation, use an approved execution-policy setting for your development machine or activate the environment from Command Prompt instead. The important check is that python and pip resolve inside .venv before you install packages.
The generated directory contains an agent module and the package files ADK expects. Keep the generated layout until the first agent runs; moving files immediately can create import and discovery problems that are unrelated to your model or tool logic.
What should the generated project contain?
The scaffold gives you a location for the root agent and project configuration. The exact filenames can change with ADK releases, so inspect the files created by your installed version rather than copying a layout from an older tutorial. Your first goal is simply to identify the Python module that defines root_agent and the .env file used for credentials.
How should I configure credentials?
Open the generated .env file and add the variables required by the model provider selected in your configuration. Keep secrets out of source control, and do not paste them into prompts, test datasets, or issue reports. If authentication fails, confirm that the environment is active, the variable names match the provider’s current documentation, and the process is being started from the project directory that contains the configuration.
How do I define a minimal Python agent?
Start with one root agent, one clear instruction, and at most one deterministic tool. ADK tools are ordinary Python functions; their docstrings explain the function’s purpose to the model. A small surface area makes it easier to tell whether a failure comes from the model instruction, the tool implementation, or the test harness.
Rank #2
from google.adk import Agent
def get_current_time(city: str) -> str:
"""Return the current time for a city."""
# Replace this body with your approved time-service implementation.
return f"Time lookup requested for {city}."
root_agent = Agent(
name="assistant",
model="gemini-flash-latest",
instruction="Answer clearly and use tools when needed.",
tools=[get_current_time],
)This example shows the shape of an ADK agent, not a claim that the placeholder function performs a real lookup. In a production implementation, the function should call a dependable data source, validate the city argument, handle service errors, and return a result that the model can explain without exposing credentials or internal traces.
How should I write the instruction?
State the agent’s role, the type of answer it should produce, and when it should use the tool. Avoid combining unrelated jobs in the first instruction. For example, an assistant that answers time questions and summarizes arbitrary documents should become two independently testable capabilities before you combine them.
What makes a tool reliable?
- Use a descriptive function name and a docstring that says what the function returns.
- Validate required arguments before making an external call.
- Return a predictable success shape and a readable error result.
- Keep side effects explicit; a function that changes data should not look like a harmless lookup.
- Write a direct test for the function independently of the model.
The model decides when a tool is appropriate, but your Python code remains responsible for correctness, authorization, timeouts, and safe handling of failures.
How do I run an ADK agent locally?
Use the terminal runner for a fast conversational check:
adk run my_agentAsk a normal question first, then one that should invoke the tool. Confirm that the response is understandable and that the tool receives the expected argument. Terminal interaction is intentionally quick to start, which makes it useful while you are changing an instruction or function.
For a browser-based development interface, run the web command from the parent directory that contains the agent folder:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
adk web --port 8000Open the address shown by the command, select your agent, and use the interface to inspect conversations while you debug. Google’s quickstart explicitly describes ADK Web as a development and debugging tool, not a production deployment. Do not expose it as the public interface for an end-user service.
What should I check during the first conversation?
- Ask a happy-path question that should be answered without a tool.
- Ask a question that clearly requires the tool and inspect the resulting value.
- Send a missing, malformed, or ambiguous argument and observe whether the agent asks for clarification or reports the problem safely.
- Change exactly one instruction or tool behavior, then repeat the same prompt.
- Record the failure and the input before adding another capability.
This sequence separates basic discovery problems from behavior regressions. It is a recommended smoke-test discipline, not a report of tests performed for this article.
How do I test an ADK agent beyond manual chat?
Manual chat is useful for discovery but weak as a regression test: a person can forget the exact prompt, overlook a wrong tool argument, or accept a response that only worked once. A repeatable test set should capture representative requests, expected tool behavior, and the edge cases your application cannot tolerate.
What cases belong in a first test set?
- Happy path: one ordinary request with an unambiguous answer.
- Tool invocation: one request that should call a specific tool with expected arguments.
- Ambiguity: one request where the agent should ask a clarifying question instead of guessing.
- Invalid input: one missing, malformed, or out-of-range value.
- Safety boundary: one refusal or safe-redirection case relevant to your application.
- Multi-turn state: include this only if remembering earlier turns is part of the product behavior.
Store prompts and expected outcomes in a versioned dataset. Keep the initial set small enough to understand every failure, then add a case whenever a bug reaches you. A test that cannot be reproduced from its recorded input is a debugging note, not a dependable regression test.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsHow does structured evaluation work?
The Agents CLI evaluation workflow uses a dataset of cases, trace generation, configured metrics, and grading. The command agents-cli eval run runs the agent over that dataset and reports scores. The evaluation is intended to examine response quality, tool use, and edge-case handling rather than merely whether a process exited successfully.
A practical development loop is:
- Use
agents-cli playgroundfor interactive exploration while designing a behavior. - Use
agents-cli run "your prompt"for a quick smoke test of a single prompt. - Run your linter, unit tests for tools, and integration tests for agent behavior.
- Run
agents-cli eval runagainst the versioned dataset and inspect traces and metric results. - Fix the implementation or instruction, add a regression case when appropriate, and run the evaluation again.
Expect several evaluation-and-fix iterations as the dataset grows. Begin with a small core set whose expected behavior is explicit; add failure cases instead of trying to predict every possible conversation in the first version. Do not publish a score unless you specify the dataset, metrics, configuration, and model used to produce it.
How should I interpret an evaluation failure?
First determine whether the failure is in the tool, the agent decision, the final wording, or the evaluator configuration. A wrong tool argument points toward schema, docstring, or instruction changes; a correct tool result with a poor answer points toward response instructions; a nondeterministic result may require tighter inputs or an evaluation design that allows acceptable variants. Keep the trace with the case so later fixes can be compared against the same evidence.
Can a coding assistant help create an ADK project?
Google’s Code with AI guide documents Agents CLI support for coding assistants. It can scaffold projects and provide skills related to the ADK lifecycle, Python API, evaluation, deployment, and observability. The same guide documents an ADK documentation MCP server and machine-readable llms.txt and llms-full.txt indexes for coding tools.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →This workflow is useful for generating boilerplate, test-case templates, or repetitive configuration, but generated code still needs human review. Check every tool’s argument validation, side effect, authentication path, and error handling. Review every evaluation case as well: a coding assistant can produce a syntactically valid test that asserts the wrong behavior or misses a safety boundary.
What should I ask an assistant to generate?
Constrain the request to one change at a time, such as creating a typed tool function, adding a unit test for malformed input, or converting a known conversation into an evaluation case. Give the assistant the project’s actual file names and expected behavior, then inspect the diff before running it. Keep secrets, production credentials, and sensitive user conversations out of prompts and generated fixtures.
How do I choose between local ADK, Cloud Run, and Agent Runtime?
Use local ADK while you are changing instructions, tools, and tests. Move to a hosted path only after local behavior is understood and repeatable. Google documents both Cloud Run and Agent Runtime deployment paths, but the operational work is different from a local command: hosted deployments require a Google Cloud project, permissions, service configuration, and post-deployment checks.
| Axis | Local ADK | Hosted runtime |
|---|---|---|
| Feedback speed | Fast CLI and web iteration | Slower deploy-test cycle |
| Test emphasis | Smoke tests and local evaluations | Post-deployment checks, authentication, logs, and runtime behavior |
| Operations | Developer-managed environment | Google Cloud project, permissions, billing, and service configuration |
When is Cloud Run appropriate?
The Cloud Run quickstart shows that a Python ADK agent with custom tools can be deployed as a service, with Cloud Run building a container image from source. This is a service-oriented path: you package the agent and its dependencies, configure the service, and verify the deployed endpoint and logs.
Free tools Windows power users keep installed
One-click scans. No signup required.
When is Agent Runtime appropriate?
The Agent Runtime quickstart covers Google Cloud project setup, installation of the Python SDK and ADK, agent development, deployment, and testing of the deployed agent. It is the documented path to investigate when you want a managed agent runtime rather than managing the service shape yourself.
Cloud permissions, available regions, SDK versions, and pricing can change. Verify those details in the current deployment guide before committing to an architecture or estimating operating cost.
What belongs in a post-deployment check?
- Confirm the deployed service accepts an authenticated request and rejects an unauthorized one.
- Repeat one happy-path case and one tool-use case from the local dataset.
- Inspect logs for tool errors, timeouts, and unexpected sensitive data.
- Verify the deployed model and environment variables match the configuration you evaluated locally.
- Run the regression evaluation against the deployed endpoint when the runtime supports that workflow.
What are the most common setup and testing problems?
The command is not found
Confirm that the virtual environment is active and that google-adk installed into that environment. Run the command with the environment’s interpreter or reactivate .venv; installing a package globally while executing a different interpreter is a common cause of missing CLI commands.
The agent cannot be discovered
Run the command from the directory expected by the scaffold, keep the generated package files in place, and verify that the root agent variable is named root_agent. If you changed the layout, compare it with the files generated by your installed ADK release rather than an older example.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteAuthentication fails
Check the provider-specific variables in .env, remove accidental quotation marks or spaces, and make sure the process starts in the directory where that configuration is loaded. Also verify that the model identifier is currently supported; model aliases can change independently of your Python code.
The model never calls the tool
Make the instruction explicit about when the tool should be used, give the function a precise name and docstring, and test with a request that cannot be answered correctly without it. Then inspect the trace: the problem may be tool selection, argument extraction, or a failure inside the function rather than registration.
The tool returns an error or unsafe result
Test the Python function directly with valid, missing, malformed, and boundary inputs. Return a controlled error that the agent can explain, and avoid exposing stack traces, access tokens, or internal service details in the tool result. Add the failing input to the evaluation dataset before changing the implementation so the fix remains verifiable.
Local results differ from hosted results
Compare model name, credentials, environment variables, dependency versions, tool configuration, and prompt text. A deployment can also differ in authentication and network access. Re-run a small set of identical cases in both environments and preserve traces so you can identify the first divergence.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →What should I verify before calling the agent ready?
Readiness is a combination of behavior, repeatability, and operations rather than a single successful conversation.
- The root agent starts from a clean virtual environment using the supported Python version.
- Each tool has direct unit tests for normal, invalid, and failure inputs.
- The evaluation dataset includes happy-path, tool-use, ambiguity, invalid-input, safety, and relevant multi-turn cases.
- Evaluation results are tied to a named model configuration and a versioned dataset.
- Secrets are supplied through the runtime environment rather than committed to the repository.
- The public service does not use ADK Web as its production interface.
- Hosted checks cover authentication, logs, permissions, and the behavior of custom tools.
- Every known failure has either a regression test or an explicit reason it is outside the application’s scope.
The practical path is incremental: make one small agent work, test the tool and the conversation, capture failures, and only then add orchestration or deployment complexity.
Frequently Asked Questions
Can I use ADK with a model other than Gemini?
ADK is described as model-agnostic, although it is optimized for Gemini. The exact provider adapters, model identifiers, and credential variables depend on the release and provider, so verify those settings in the current documentation before changing the example configuration.
Does running adk web expose my agent to the internet?
The web command starts a browser-based development interface on the local machine by default. It is intended for development and debugging, not as a production-facing service; deploy through a documented hosted path when external users need access.
How do I test whether a tool received the right arguments?
Give the evaluation case an expected argument shape and inspect the generated trace, then unit-test the Python function separately with representative values. Keeping tool tests independent lets you distinguish model argument extraction from a bug in the function itself.
Should I add multi-agent orchestration to my first project?
Usually wait until a single root agent and its tools have stable tests. Multiple agents and workflow composition add routing and state interactions, so introduce them only when a measured requirement cannot be met by a clearly scoped single-agent design.
What should I keep in version control for reproducible evaluations?
Keep the agent code, tool tests, evaluation dataset, metric configuration, and dependency configuration together. Record the model identifier and environment assumptions for each run, while excluding credentials and sensitive user data from the repository.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
