subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

How to run a first Google ADK Python agent

Official Google ADK Python quickstart: install the kit, scaffold an agent, add a tool, and run it from the CLI or local web UI.

google-adkgeminiagents

Getting a first Agent Development Kit (ADK) agent running is a small loop, and the official Python quickstart keeps it that way. Install the kit, scaffold a project, replace the generated agent with a sample that exposes one tool, set a Gemini API key, and run the agent. The same page also starts a local web UI, and it states that this UI is for development and debugging, not production.

What follows uses only that quickstart. Every command and the agent sample appear there. If the page does not name a working directory, a flag, or a later implementation, it is left unspecified here rather than guessed.

Install ADK

Before you start, the quickstart expects two things already installed:

  • Python 3.10 or later
  • pip for installing packages

Creating a virtual environment is recommended, not required. Create it with:

python3 -m venv .venv

Activate it with the command for your shell.

Windows Command Prompt:

.venv\Scripts\activate.bat

Windows PowerShell:

.venv\Scripts\Activate.ps1

macOS or Linux:

source .venv/bin/activate

Install the kit:

pip install google-adk

That install line is printed without a version pin. Use it as shown.

Scaffold the agent

Run the create command to start a new agent project:

adk create my_agent

The created project has this structure. The agent.py file contains the main control code for the agent:

my_agent/
    agent.py      # main agent code
    .env          # API keys or project IDs
    __init__.py

The env file is for API keys or project IDs. The quickstart shows this tree after adk create and does not paste the generated file contents, so treat the tree as the layout, not as a dump of the scaffold.

Add the get_current_time tool

agent.py contains a root_agent definition. The quickstart calls that definition the only required element of an ADK agent. You can also define tools for the agent to use.

Update the generated agent.py to include a get_current_time tool, as in this sample:

from google.adk.agents.llm_agent import Agent

# Mock tool implementation
def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-flash-latest',
    name='root_agent',
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

Read the mock before you demo it. The comment labels the function as a mock tool implementation. It takes a city string and returns a dictionary with a success status, that city, and a fixed time string. The docstring says it returns the current time in a specified city, but the function does not read a clock. It is there so the agent has a tool to call, not so it can answer a real time question.

The Agent constructor registers that function on its tools list. It also sets the model to gemini-flash-latest, the name root_agent, a short description, and an instruction. The instruction says the agent is a helpful assistant that tells the current time in cities, and that it should use get_current_time for that purpose. Copy the block as printed if you want the quickstart sample, not a variation of it.

Write the API key

This project uses the Gemini API, which requires an API key. If you do not already have a Gemini API key, create a key in Google AI Studio on the API Keys page.

In a terminal window, write your API key into an .env file as an environment variable. The quickstart labels each example as an update to the env file inside the agent project. The command writes .env in the current directory and replaces that file if it already exists. Run it from inside the agent folder so the file matches the label. The page does not include a change-directory command. Replace the placeholder in the command with the key you created.

macOS, Linux, and Windows PowerShell use the same line:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

Windows Command Prompt uses a line without the outer single quotes:

echo GOOGLE_API_KEY="YOUR_API_KEY" > .env

The variable name in both forms is GOOGLE_API_KEY.

ADK supports the use of many generative AI models. The quickstart points to its Models & Authentication documentation for configuring other models in ADK agents. This first run stays on the Gemini sample above.

Run the CLI

You can run your ADK agent with an interactive command-line interface, or with the web user interface. Both options let you test and interact with your agent. For the CLI:

adk run my_agent

The argument is the project name from adk create. The quickstart shows a screenshot of that session and does not include a sample transcript, so the first prompt is yours. A request that matches the instruction, the current time in a specified city, is the case this agent was written for. The only time value the tool can return is the fixed string in the sample above.

The page does not say which directory adk run must be started from. It does say that for the web command.

Optional local web UI

The framework also provides a web interface you can use to test and interact with your agent. Start it with the command from the quickstart:

adk web --port 8000

Run this command from the parent directory that contains your my_agent/ folder. For example, if your agent is inside agents/my_agent/, run adk web from the agents/ directory. Do not start it from inside the agent folder.

The command starts a web server with a chat interface. Access the web interface at http://localhost:8000. Select the agent at the upper left corner and type a request. The quickstart shows a screenshot of that development chat and does not document other controls.

The caution on that page is part of the setup, not a footnote. ADK Web is not meant for use in production deployments. You should use ADK Web for development and debugging purposes only. The quickstart does not describe a production host, authentication, or a public address for this UI.

Next step

Run the command-line session shown above and ask for the current time in a city. Compare the reply with the mock dictionary in agent.py: that function always returns the same time string and the city argument it received. If you want the same check in a browser, start the web command from the parent of my_agent/ and open http://localhost:8000. Keep that UI on a development machine.

When that first loop works, continue with the section the quickstart titles Next: Build your agent, and follow the build guides it links from the Python quickstart. If a shell result disagrees with a command here, re-check the command against that page before changing flags.

Sources