This article is published in English.
Practical notes: Introduction to Agentic AI with Google ADK
Operable walkthrough of Practical notes: Introduction to Agentic AI with Google ADK: contracts, checks, and drop-in code slots for teams shipping this pattern.
This walkthrough rebuilds the path from raw materials to a working system for: Introduction to Agentic AI with Google ADK. The focus is operable steps, explicit checks, and code that you can drop into a repo without guessing intent. For the Overview stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
The Shift from Chatbots to Agents
When working through the The Shift from Chatbots stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
Understanding the Core Idea Behind Agentic AI
When working through the Understanding the Core Idea stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
from google.adk.agents import Agent
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
Giving an Agent Real Capabilities with Tools
When working through the Giving an Agent Real stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours. When working through the Giving an Agent Real stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise Exception("Cannot divide by zero")
return a / b
raise Exception("Unsupported operation")
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction=(
"You are a helpful assistant with calculator capabilities. "
"Use the calculator tool for arithmetic. "
"Supported operations are add, subtract, multiply, divide."
),
tools=[calculator]
)
Building Multi-Tool Agents
The Building Multi-Tool Agents stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise ValueError("Cannot divide by zero.")
return a / b
raise ValueError("Unsupported operation.")
def convert_units(value: float, from_unit: str, to_unit: str) -> float:
from_unit = from_unit.lower()
to_unit = to_unit.lower()
if from_unit == "km" and to_unit == "miles":
return value * 0.621371
if from_unit == "miles" and to_unit == "km":
return value / 0.621371
if from_unit == "celsius" and to_unit == "fahrenheit":
return value * 9 / 5 + 32
if from_unit == "fahrenheit" and to_unit == "celsius":
return (value - 32) * 5 / 9
raise ValueError("Unsupported unit conversion.")
def get_weather_mock(city: str) -> dict:
weather_data = {
"bucharest": {
"temperature_celsius": 23,
"condition": "sunny",
"wind_speed_kmh": 10,
},
"london": {
"temperature_celsius": 16,
"condition": "rain",
"wind_speed_kmh": 18,
},
}
key = city.lower()
if key not in weather_data:
return {
"city": city,
"error": "Weather data not available."
}
return {
"city": city,
**weather_data[key],
}
root_agent = Agent(
name="multi_tool_agent",
model="gemini-2.5-flash",
instruction=(
"You are a practical assistant. "
"Use the available tools when the user asks for calculations, "
"unit conversions, or weather information."
),
tools=[
calculator,
convert_units,
get_weather_mock,
],
)
Multi-Agent Systems: Agents Using Other Agents
The Multi-Agent Systems Agents Using stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.adk.tools import google_maps_grounding
from google.adk.tools.agent_tool import AgentTool
routing_agent = LlmAgent(
name="routing_agent",
model="gemini-2.5-pro",
instruction="""
You are a routing agent.
Use google_maps_grounding to estimate routes and travel times.
""",
tools=[google_maps_grounding],
)
discovery_agent = LlmAgent(
name="discovery_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel discovery agent.
Use Google Search to find interesting places.
""",
tools=[google_search]
)
composer_agent = LlmAgent(
name="composer_agent",
model="gemini-2.5-pro",
instruction="""
Write a friendly travel itinerary based on the collected information.
""",
tools=[]
)
root_agent = LlmAgent(
name="travel_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel assistant.
Coordinate discovery, routing, and itinerary composition.
""",
tools=[
AgentTool(discovery_agent),
AgentTool(routing_agent),
AgentTool(composer_agent)
]
)
Sequential Workflows and Deterministic Orchestration
The Sequential Workflows and Deterministic stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts. The Sequential Workflows and Deterministic stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
from google.adk.agents import Agent, SequentialAgent
from google.adk.tools import AgentTool
planner_agent = Agent(
name="planner_agent",
model="gemini-2.5-flash",
instruction="""
Read the user request and create a short execution plan.
"""
)
executor_agent = Agent(
name="executor_agent",
model="gemini-2.5-flash",
instruction="""
Execute the plan and delegate specialist work.
""",
tools=[]
)
report_agent = Agent(
name="report_agent",
model="gemini-2.5-flash",
instruction="""
Produce the final report based on execution results.
"""
)
root_agent = SequentialAgent(
name="planner_executor_report_workflow",
sub_agents=[
planner_agent,
executor_agent,
report_agent,
],
)
Running an ADK Agent Locally
For the Running an ADK Agent stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True
adk web
Deploying an Agent to Google Cloud Run
For the Deploying an Agent to stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["adk", "web", "--host", "0.0.0.0", "--port", "8080"]
gcloud run deploy simple-agent \
--source . \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
--set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \
--set-env-vars GOOGLE_CLOUD_LOCATION=us-central1
gcloud run services describe simple-agent \
--region us-central1 \
--format='value(status.url)'
Exposing an Agent Through FastAPI
For the Exposing an Agent Through stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness. For the Exposing an Agent Through stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
import uuid
from fastapi import FastAPI
from pydantic import BaseModel
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from agent import root_agent
app = FastAPI()
session_service = InMemorySessionService()
runner = Runner(
agent=root_agent,
app_name="weather_agent_service",
session_service=session_service,
)
class QueryRequest(BaseModel):
message: str
@app.post("/weather")
async def weather(request: QueryRequest):
user_id = "api_user"
session_id = str(uuid.uuid4())
await session_service.create_session(
app_name="weather_agent_service",
user_id=user_id,
session_id=session_id,
)
content = types.Content(
role="user",
parts=[
types.Part(text=request.message)
],
)
final_answer = ""
async for event in runner.run_async(
user_id=user_id,
session_id=session_id,
new_message=content,
):
if event.is_final_response():
final_answer = event.content.parts[0].text
return {
"response": final_answer
}
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
Deploying to Agent Engine
When working through the Deploying to Agent Engine stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
gcloud services enable \
aiplatform.googleapis.com \
storage.googleapis.com
export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"
gsutil mb -l us-central1 $STAGING_BUCKET
adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent
Final Thoughts
When working through the Final Thoughts stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
Operational checklist
The Operational checklist stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope.
Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.
Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.
Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.
Batch note for 18b8374abe5a: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.