How to Build an Agent with Google ADK

Step 1: Install and Configure ADK

Install the google-adk package using pip. Set your Gemini API key as the GOOGLE_API_KEY environment variable, or configure a Vertex AI project if you are using Google Cloud. ADK supports both direct Gemini API access and Vertex AI endpoints, with the configuration determined by environment variables.

Create a project directory with separate files for agent definitions, tool implementations, workflow configurations, and the main entry point. ADK projects tend to have more files than other SDK projects because the framework encourages explicit separation of concerns. Create a tools directory for custom tool functions, an agents directory for agent class definitions, and a workflows directory for graph-based workflow specifications.

Choose your model based on the task. Gemini 2.5 Pro provides the strongest reasoning for complex tasks. Gemini 2.5 Flash offers a good balance of quality and cost for most agent workloads. Gemini Flash Lite is the most affordable option for simple routing and classification tasks within multi-agent systems. Each agent in a multi-agent system can use a different model, so you can optimize cost by routing different complexity levels to different model tiers.

Step 2: Define Your Agent Class

In ADK, agents are Python classes that inherit from the framework's base agent class. Define the class with a system instruction (the prompt that controls agent behavior), a model identifier, and a list of available tools. The class-based approach lets you encapsulate agent configuration, state, and behavior in a single unit that can be instantiated multiple times with different parameters.

The system instruction follows the same best practices as other SDKs: be specific about the agent's role, define its capabilities and constraints, and describe the quality standards it should meet. ADK agents also support a description field that other agents use when deciding whether to delegate tasks, so write a clear one-sentence description of what this agent specializes in.

Run the agent with a test task using ADK's runner. The runner manages the agent loop, handling model calls, tool dispatch, and response aggregation. Unlike the other SDKs where you call a simple function, ADK's runner is a more structured component that supports session management, context persistence, and execution tracking from the start.

Step 3: Build Custom Tools

ADK tools are Python functions decorated with the framework's tool decorator. Define the function with type annotations, add a docstring that describes when the tool should be used, and the framework handles parameter validation and JSON marshalling automatically. Pydantic models work as input types for tools that need complex parameters.

ADK provides native integrations with Google Cloud services. BigQuery tools let agents run SQL queries on your data warehouse. Cloud Storage tools enable file reading and writing. Vertex AI tools connect to other ML models and pipelines. These integrations use your existing Google Cloud credentials and require no additional authentication setup.

For external services, ADK supports MCP connections. Configure MCP servers in your project settings to give agents access to the broader ecosystem of 500+ community tool servers. ADK's MCP support is newer than the other SDKs but covers the core stdio and HTTP transport protocols. Test each tool individually before attaching it to an agent, verifying that it handles edge cases and returns clear error messages when something goes wrong.

Step 4: Create Multi-Agent Workflows

This is where ADK distinguishes itself from every other SDK. The graph-based workflow engine lets you define complex execution flows using a Python DSL. Create workflow nodes that represent agent tasks, connect them with edges that define the execution order, and add routing conditions that determine which path to follow based on intermediate results.

A common pattern is a triage workflow where an initial classifier agent examines the user's request and routes it to one of several specialist agents. Define the classifier as the entry node, create edges to each specialist, and specify routing conditions based on the classifier's output. The framework handles execution, context passing, and result aggregation.

For more complex scenarios, use parallel execution branches where multiple agents work simultaneously on different aspects of a task. The workflow engine supports fan-out (sending the same context to multiple agents), fan-in (aggregating results from parallel branches), and conditional branching (choosing a path based on prior results). Add retry logic to handle transient failures in any workflow step.

The Task API provides structured delegation between agents. Instead of informal handoffs (as in OpenAI's SDK), ADK uses formal task objects that specify the work to be done, the expected output format, and completion criteria. The delegating agent can track task progress and handle the result when it arrives. This structured approach prevents the context loss and ambiguity issues that plague informal handoff systems.

Step 5: Add Evaluation and Testing

ADK includes a built-in evaluation framework that measures agent quality systematically. Define test cases as Python dictionaries or JSON files, specifying the input task, the expected behavior (which tools should be called, in what order), and the expected output quality (using criteria like relevance, accuracy, and completeness).

Run evaluations using ADK's evaluation runner, which executes each test case against your agent and produces quality scores. The evaluation uses a separate model instance (typically Gemini Pro) to judge the agent's output against your criteria. This automated evaluation catches regressions before they reach production and provides quantitative data for comparing different agent configurations.

Integrate evaluations into your CI/CD pipeline using standard Python test runners. ADK's evaluation runner produces results that pytest can consume, so you can fail builds when agent quality drops below your threshold. This is a significant advantage over manual testing, especially as your agent system grows more complex and manual testing becomes impractical.

Step 6: Deploy to Google Cloud

ADK provides deployment tooling that packages your agent as a container and deploys it to Google Cloud. The CLI generates a Dockerfile, builds the container, and pushes it to Cloud Run or GKE depending on your configuration. Auto-scaling is configured automatically based on request volume, and the framework handles health checks and graceful shutdown.

For Vertex AI deployment, ADK integrates with Vertex AI's agent hosting platform, which provides managed infrastructure, automatic scaling, and built-in monitoring. The deployment process uploads your agent definition and tools to Vertex AI, which handles serving, scaling, and observability without any container management on your part.

Configure monitoring through Google Cloud's operations suite. ADK automatically emits metrics for agent execution time, tool call frequency, model token usage, and error rates. Set up alerts for error rate spikes, latency degradation, and cost threshold breaches. The observability data flows into Cloud Monitoring dashboards where you can visualize agent performance alongside your other application metrics.

For production reliability, configure the session service to persist agent state in Firestore or Cloud SQL. This enables session resumption after container restarts, load balancer failovers, and scaling events. Set execution limits (maximum turns, token budget, wall-clock timeout) at both the agent level and the workflow level to prevent runaway execution in complex multi-agent systems.