Tutorial ·

Build an AI agent from a YAML file

A working Gemini agent, with Google Search, from a few lines of configuration and no Python. Then we grow it into a small research desk that looks up power-market news and explains it in plain English.

Based on Day 2 of Google’s Advent of Agents (“Hello World with YAML”) and the ADK Agent Config documentation. I ran every command and file below with ADK 2.13.0 on Windows 11 and Python 3.12. Config agents are marked experimental in ADK, so check the docs if a step has changed.

What you will build

The Agent Development Kit (ADK) is Google’s open-source framework for building agents. Most examples are Python, but ADK can also load an agent from a YAML file: a name, a model, a description, an instruction, and optional tools. ADK supplies the rest, including a chat window in your browser for testing.

  1. A one-file agent that answers energy-market questions using Google Search.
  2. A research desk: a coordinator that sends a scout to search the web, then hands the facts to an explainer that writes for a non-specialist.

You need Python 3.10 or newer (I used 3.12) and a Gemini API key, which is free to create in Google AI Studio.

1. Install ADK

Make a folder for the project, create a virtual environment in it, and install the google-adk package:

python -m venv .venv
# macOS or Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install google-adk
adk --version

If you use uv, you can skip the install and prefix each command with uvx --from google-adk, as the Advent of Agents page does: uvx --from google-adk adk web.

2. Create the agent

adk create --type=config --model gemini-flash-latest energy_agent

This makes an energy_agent folder with three files: root_agent.yaml (the agent), .env (your settings), and a .gitignore that keeps .env out of git. Leave out --model and ADK asks which model to use. Any Gemini model name you have access to works.

Windows tip: if adk create stops with a UnicodeEncodeError, the files were still written. The error is the console failing to print an emoji. Run $env:PYTHONIOENCODING="utf-8" in PowerShell (or set PYTHONIOENCODING=utf-8 in cmd) first, and it goes away.

3. Add your API key

Open energy_agent/.env and set your key. 0 means “use the Gemini API with a key,” not Google Cloud:

GOOGLE_GENAI_USE_ENTERPRISE=0
GOOGLE_API_KEY=paste-your-key-here

To run on Google Cloud instead, set it to 1 and add GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. Never commit this file or paste the key into a chat.

4. Write the agent: a few lines of YAML

Replace root_agent.yaml with this. The first line only helps your editor check the file against ADK’s schema.

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: grid_news
model: gemini-flash-latest
description: Answers questions about electricity markets with current facts.
instruction: |
  You answer questions about power markets: prices, outages, new rules, and big projects.
  Search the web for anything that may have changed recently.
  Give the date and the source of every number, and say when you are not sure.
tools:
  - name: google_search
  • name identifies the agent. Use letters, numbers, and underscores.
  • description says what the agent is for. Other agents read it when deciding whom to call.
  • instruction is the standing brief. Most of the quality comes from writing this well.
  • tools lists what the agent may use. google_search is built into ADK and grounds answers in live search results.

5. Run it

From the folder that contains energy_agent (not from inside it), start the dev UI:

adk web

Open http://127.0.0.1:8000, pick energy_agent at the top left, and ask something like “What moved ERCOT real-time prices this week?” The Events panel shows each step, including the search the agent ran. Prefer the terminal? adk run energy_agent gives you the same agent as a chat in your shell.

6. Grow it into a research desk

One agent that searches and writes tends to blur facts and interpretation. Splitting the jobs keeps them apart: a scout only gathers dated, sourced facts, an explainer only explains, and a coordinator runs the desk. Put three files in energy_agent:

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: grid_desk
model: gemini-flash-latest
description: Coordinates a small research desk for power-market questions.
instruction: |
  For anything that needs current facts (prices, outages, new rules), call news_scout.
  Then hand the facts to explainer to turn them into a short, plain-English answer.
  Always keep the date and the source of every number.
tools:
  - name: AgentTool
    args:
      agent:
        config_path: news_scout.yaml
sub_agents:
  - config_path: explainer.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: news_scout
model: gemini-flash-latest
description: Finds current energy-market facts on the web.
instruction: Search for the facts asked for. Return each fact with its date and source link. Do not interpret.
tools:
  - name: google_search
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
name: explainer
model: gemini-flash-latest
description: Explains energy-market facts in plain English.
instruction: |
  Explain the facts you are given for a non-specialist in under 150 words.
  Define any jargon (LMP, capacity market, curtailment) the first time you use it.

Two different links are at work here:

  • The scout is a tool (AgentTool). The coordinator calls it, gets the facts back, and stays in charge. Built-in tools such as google_search do not mix freely with other tools on one agent, so giving search its own small agent is the usual pattern.
  • The explainer is a sub-agent. The coordinator can hand the conversation over to it, and it writes the reply.

Restart adk web and ask the same question. In the Events panel you can watch the coordinator call the scout, then transfer to the explainer.

Where to go next

  • Your own data: a custom Python function can be listed as a tool by its import path, for example a function that reads a CSV of hourly prices.
  • Other services: ADK can connect to MCP servers, so an agent can read files, query a database, or use another app’s tools. See third-party tools in ADK.
  • From code: the same YAML loads in Python with config_agent_utils.from_config("energy_agent/root_agent.yaml"), so a config agent can later move into an app.
  • Deploying: ADK agents deploy to Cloud Run or Google’s managed agent runtime. Start with the dev UI until the instructions are right.

Limits worth knowing: config agents are experimental and work with Gemini models only. Some agent types and tools that Python ADK supports are not available from YAML yet. And a search-grounded agent can still be wrong, so check any number before you act on it.