How To Build AI Agents 3 Ways With Google ADK

Google‘s Agent Development Kit (ADK) has rapidly become a foundational framework for building AI agents. Introduced at Google Cloud NEXT 2025, ADK powers agents across Google products, including Gemini Enterprise and the Google Customer Engagement Suite. What makes ADK particularly compelling for developers is its flexibility. Developers can build agents using Python code, YAML configuration files or a drag-and-drop visual interface — depending on workflow preferences and use case requirements. In this tutorial, I’ll walk you through all three approaches to building your first “Hello World” agent with ADK. By the end, you’ll have a functional agent running locally using each method, giving you a foundation to choose the right approach for your projects. Understanding the 3 Approaches Before diving into implementation, let’s understand what each approach offers: Imperative agents (Python): This code-first approach gives you maximum flexibility and control. You define agent logic, tools and orchestration directly in Python, making it ideal for complex agents that need custom logic, integration with existing codebases or sophisticated multiagent systems. The Python approach also supports any large language model (LLM) through LiteLLM integration. Declarative agents (YAML): Introduced in August 2025 with the Agent Config feature, this approach lets you define agents using YAML configuration files. It reduces boilerplate and makes agents easier to understand at a glance — particularly useful for simpler agents or when you want non-developers to understand agent behaviour. Visual Agent Builder (GUI): Launched in ADK v1.18.0, the Visual Agent Builder is a browser-based IDE that combines a visual workflow designer, configuration panels and an AI assistant. You can design multiagent systems through drag-and-drop interactions and natural language conversations, with the tool generating proper YAML configurations under the hood. Prerequisites Before we begin, ensure you have the following: Python 3.10 or higher A code editor Terminal access Either a Google AI Studio API key or a Google Cloud project with Vertex AI enabled Step 1: Setting up the Environment Let’s start by creating a virtual environment and installing ADK. Open your terminal and run: python -m venv .venv source .venv/bin/activate Install the ADK package: pip install google-adk Verify the installation: adk --version You should see the installed ADK version (1.18.0 or higher is required for the Visual Agent Builder). Step 2: Configure Model Access ADK needs access to an LLM. The simplest option for getting started is using Google AI Studio with a free API key. Obtain your API key from Google AI Studio and keep it accessible, as you’ll need it for the next steps. Approach 1: Building an Imperative Agent With Python The imperative approach is the most powerful method, giving you full control over agent behavior through code. Let’s build a simple greeting agent that demonstrates the core concepts. Create the Project Structure Create a new directory for your agent project: mkdir hello_agent cd hello_agent Create the following files inside the hello_agent directory: __init__.py from . import agent This file marks the directory as a Python package and imports the agent module. agent.py from google.adk.agents import Agent def greet_user(name: str) -> dict: """Greets a user by name. Args: name (str): The name of the user to greet. Returns: dict: A greeting message with status. """ return { "status": "success", "message": f"Hello, {name}! Welcome to Google ADK. I'm your first AI agent!" } def get_agent_info() -> dict: """Returns information about this agent. Returns: dict: Information about the agent's capabilities. """ return { "status": "success", "info": "I am a Hello World agent built with Google ADK using Python. " "I can greet users and tell them about myself." } root_agent = Agent( name="hello_agent", model="gemini-2.0-flash", description="A friendly greeting agent that welcomes users to Google ADK.", instruction="""You are a friendly and helpful greeting agent. Your primary purpose is to: 1. Greet users warmly when they provide their name using the greet_user tool 2. Explain what you are when asked using the get_agent_info tool 3. Be enthusiastic about introducing users to Google ADK Always use the available tools to respond appropriately to user requests.""", tools=[greet_user, get_agent_info], ) The Agent class is the core building block in ADK. Notice how we define tools as regular Python functions with type hints and docstrings. ADK uses these to help the LLM understand when and how to call each tool. .env GOOGLE_GENAI_USE_VERTEXAI=0 GOOGLE_API_KEY=YOUR_API_KEY_HERE Replace the placeholder values with your actual credentials. Run the Agent Navigate to the parent directory of your agent folder: cd .. Run the agent in terminal mode: adk run hello_agent You should see a prompt indicating the agent is running: Running agent hello_agent, type exit to exit. [user]: Try these interactions: [user]: Hello, my name is Jani [user]: What can you do? [user]: Tell me about yourself The agent will use the appropriate tools to respond. Type exit to quit. Approach 2: Building a Declarative Agent With YAML The declarative approach using YAML configuration files simplifies agent creation, especially for straightforward use cases. The Agent Config feature generates the same underlying agent structure but with less code. Create the Config-Based Project Use the ADK CLI to generate a config-based agent project: adk create yaml_hello_agent --type=config Accept the defaults and complete the steps. Define the Agent in YAML Open yaml_hello_agent/root_agent.yaml and replace its contents with: name: hello_yaml_agent model: gemini-2.0-flash description: A friendly greeting agent built with YAML configuration. instruction: | You are a friendly and helpful greeting agent. Your primary purpose is to: 1. Greet users warmly when they provide their name using the greet_user tool 2. Explain what you are when asked using the get_agent_info tool 3. Be enthusiastic about introducing users to Google ADK Always use the available tools to respond appropriately to user requests. tools: - name: yaml_hello_agent.greet_user - name: yaml_hello_agent.get_agent_info The YAML structure mirrors the Python Agent class parameters, but in a more readable format. Notice how tools are referenced by their module path. Create the Tools Module A powerful feature of ADK’s YAML config is that you can mix in Python code. Update __init__.py file in the yaml_hello_agent folder: def greet_user(name: str) -> dict: """Greets a user by name. Args: name (str): The name of the user to greet. Returns: dict: A greeting message with status. """ return { "status": "success", "message": f"Hello, {name}! Welcome to Google ADK via YAML config!" } def get_agent_info() -> dict: """Returns information about this agent. Returns: dict: Information about the agent's capabilities. """ return { "status": "success", "info": "I am a Hello World agent built with YAML configuration. " "I demonstrate the declarative approach to ADK agents." } Your project structure should now look like: yaml_hello_agent/ ├── root_agent.yaml ├── __init__.py └── .env Run the YAML-Based Agent Navigate to the parent directory and run: adk run yaml_hello_agent Test it with the same prompts: [user]: Hi, I'm Jani [user]: What are you? The agent responds identically to the Python version but is defined entirely through configuration. Approach 3: Building an Agent With the Visual Agent Builder The Visual Agent Builder, introduced in ADK v1.18.0, is a browser-based IDE that transforms how you build agents. It combines a visual workflow designer, configuration panels and an AI assistant that lets you design agents through drag-and-drop interactions and natural language conversations. Launch the Visual Agent Builder From any directory, run: adk web Open http://localhost:8000/dev-ui/ in your browser to access the Visual Agent Builder. Click the “+” button next to the dropdown and enter the name visual_hello_agent: Instead of manually configuring the agent, let’s use the AI Assistant. In the right panel, type: Create a simple greeting agent that can: 1. Greet users by name when they introduce themselves 2. Tell users about itself when asked Use gemini-2.5-flash as the model. Keep it simple with just two tools. The AI Assistant will generate a complete agent configuration, including: Proper agent name and description Model selection Detailed instructions Click the Save button, then exit the builder mode. You can now chat with the agent. Comparing the 3 Approaches After building agents with all three methods, here’s how they compare: Aspect Imperative (Python) Declarative (YAML) Visual Builder Best for Complex logic, CI/CD Simple agents, collaboration Prototyping, learning Learning curve Moderate Low Lowest Flexibility Highest Medium Medium Model support All (via LiteLLM) Gemini only Gemini only Version control Excellent Excellent Good (exports YAML) Non-developer friendly No Somewhat Yes Debugging Manual Manual Built-in tracing Key considerations: The Python approach is best when you need maximum control, custom integrations or support for non-Gemini models through LiteLLM. The YAML approach works well for straightforward agents where you want the simplicity of configuration files with the ability to mix in Python tools. The Visual Builder excels at rapid prototyping, learning ADK concepts and collaborating with non-developers who can describe requirements in natural language. In practice, these...