Build an Agent with Google ADK

In this guide, you can learn how to build and run an agent with the Google Agent Development Kit (ADK). The agent-engine-sdk-adk package is an adapter between ADK and the MongoDB Atlas Agent Engine. The adapter translates ADK agents, workflow nodes, and tool calls into operations that the platform's Orchestration Engine runs and records.

The adapter is durable, so ADK agents run in durable workflow mode. The Orchestration Engine, not ADK, stores the state for each session. The platform also stores the results of each model call and tool call. A resumed execution replays recorded results instead of repeating execution actions.

Google ADK Considerations

When you build an ADK agent on the Atlas Agent Engine, consider the following key points:

The Google ADK SDK is available for Python only. To build an agent in TypeScript, see the TypeScript SDK guide.
Your agent must set the features.durable_workflow value to true in the agent.yaml file. If you omit this field or set it to false, the first invocation fails. To learn more about the available fields in the agent.yaml file, see the agent.yaml schema.
The agent-engine-sdk-adk package accepts either an ADK BaseAgent or an ADK 2 Workflow as the root of your agent.

Prerequisites

Ensure that you have the following prerequisites before you begin:

Python 3.11 or later.
uv package manager.
Installed and authenticated agentengine CLI. To learn how, see Create a Project.
Google ADK version 2.9.0 or later. To learn how to install ADK, see the ADK installation documentation.
API key for your LLM provider. The agentengine create command prompts for the key and saves it to your .env file as LLM_API_KEY.

Steps

Create a project from an ADK starter template.

Run the agentengine create command with one of the ADK templates:

agentengine create --template hello-world-agent-adk

The hello-world-agent-adk template creates a minimal agent. The insurance-agent-adk template creates an insurance-domain agent. To learn about all available templates and agentengine create command options, see Supported Templates.

Review the template code.

Open the entrypoint module in your project. The template already registers a tool and builds the agent. The module uses the following SDK features:

@app.tool(): Registers a function as a tool with the platform. The decorator doesn't automatically expose the tool to your agent.
@app.entrypoint: Marks the function that returns your ADK agent.
app.llm(): Wraps an ADK BaseLlm instance so that the platform audits every model call.
app.tools(): Returns your registered tools with the platform's secure wrapper applied.

Important

Pass the tools that the app.tools() function returns to your agent, not the functions that you decorate with @app.tool().

Run the agent locally.

From your agent directory, run the following command to start the local development environment:

agentengine dev up

To learn about hot-reload and isolated modes, see Run and Test Your Agent Locally.

Deploy the agent.

Run the following command to build and deploy your agent in one step:

agentengine deploy --auto

The deployed agent also requires your LLM API key. To learn how to provide secrets to a deployed agent, see Provision Cloud Secrets.

To learn how to build and deploy as separate steps, see Build the Agent Image and Deploy Your Build.

Add Human Review to a Tool

To pause an execution until a human approves a tool call, wrap a callable tool function in the ADK FunctionTool class and pass the require_confirmation=True option to the constructor. To pause an execution and collect input other than an approval, use the ADK LongRunningFunctionTool class. Wrap the callable tool functions that app.tools() returns, not the raw functions that you decorate with @app.tool().

The following example wraps each callable tool that app.tools() returns in the FunctionTool class, so that every tool call waits for human approval before it runs:

import os
from google.adk.agents import LlmAgentfrom google.adk.models.lite_llm import LiteLlmfrom google.adk.tools.function_tool import FunctionTool
@app.entrypointdef build_agent():    return LlmAgent(        name="daily",        instruction="You are a helpful assistant.",        model=app.llm(            LiteLlm(                model="<model-name>",                api_key=os.environ["LLM_API_KEY"],            )        ),        tools=[            FunctionTool(tool, require_confirmation=True)            for tool in app.tools()        ],    )

Note

Remote MCP tools that app.tools() returns are ADK BaseTool objects, not plain callables, so you can't wrap them with the FunctionTool class. The platform governs MCP tool calls through Orchestration Engine policy and guardrails.

Respond to Tool Requests

A confirmation answer has the ADK object syntax {confirmed: true|false}. The platform records each pause as an Orchestration Engine activity and uses the activity ID as the interrupt ID.

To resume a paused execution, send a request to the invoke endpoint on the same session. In the request, include a resume_map object that maps the ID of every pending pause to its answer. You must answer all pending pauses in the same request. To find the IDs, read the suspend_context.interrupts list of the paused execution. To learn more, see Invocation API.

The following example request body answers two pending pauses. The first answer approves a tool call that requires confirmation. The second answer returns input that a different paused tool requested.

{  "resume_map": {    "<activity-id-1>": { "confirmed": true },    "<activity-id-2>": "us-east-1"  }}

To resume from the CLI, use the --session and --resume options of the agentengine invoke command. To learn more, see Invoke an Agent from the CLI.

Note

ADK agents run in durable workflow mode, so you resume them with a resume_map request and not with the decision request body described in the Human-in-the-Loop guide.

Supported Agent Structures

The agent-engine-sdk-adk package requires the complete Workflow and agent structure when your agent starts. The platform records each step by its path in that structure. The following table lists the ADK features that the agent-engine-sdk-adk package supports:

ADK Feature	Support
Plain `BaseAgent` root	Supported
Statically configured `Workflow` nodes, including nested serial and parallel graphs	Supported
Configured `sub_agents` parameter, where the model selects the child agent to run by calling the `transfer_to_agent` function	Supported
Workflow agent nodes with configured transfers	Supported when the agent uses `mode="chat"`
Agents wrapped with the `AgentTool` class	Rejected before execution. Use configured `sub_agents` instead.
`NodeTool` and nodes passed to `run_node()` at runtime	Rejected with an error before the nested agent or node starts.

Add Other Platform Features

The following platform features work with ADK agents:

Remote MCP servers that you declare in the mcp field of the agent.yaml file. The platform discovers the tools at startup and returns them from app.tools(). To learn more, see Use Remote MCP Servers.
Guardrail output review. An llm_output guardrail with the require_review action pauses the model call until a reviewer approves or denies the output. Review the output through the resume_map request.

Learn More

Back

Build a Deep Agent