Agentes Google ADK: de un único agente Gemini a despliegues en Cloud Run
Google ADK de un agente Gemini a producción: herramientas, agentes como herramientas, flujos secuenciales, pruebas locales y despliegues a Cloud Run y Vertex AI Agent Engine.
Los modelos de lenguaje grandes cambiaron la forma en que las personas utilizan el software, pero el siguiente paso tiene menos que ver con chats más inteligentes y más que ver con sistemas que razonan, invocan herramientas, trabajan en conjunto y ejecutan flujos de trabajo completos por sí solos. Ese es el ámbito de la IA agente. Mientras que una aplicación clásica envía una solicitud y espera una respuesta, un agente decide qué hacer a continuación: puede invocar una API, obtener información, asignar una subtarea a un especialista o devolver un resultado estructurado.
El Kit de Desarrollo de Agentes de Google (ADK) es un marco práctico para aprender esto. Permite crear agentes basados en los modelos Gemini, exponer funciones de Python como herramientas, orquestar varios agentes e implementarlos en Google Cloud. Las secciones siguientes abordan desde un agente individual hasta la implementación en la nube.
De las solicitudes a los agentes
Las aplicaciones tradicionales de LLM funcionan mediante un formato de pregunta y respuesta. Usted hace la pregunta, el modelo responde y eso es todo. En un entorno de agentes, el modelo se encuentra dentro de un sistema de ejecución más amplio. Puede tener objetivos, elegir herramientas, comunicarse con APIs y cooperar con otros agentes. La idea clave es que un agente es algo más que una simple pregunta: es un componente de software impulsado por un modelo de lenguaje.
Una aplicación ADK se centra en un root_agent. La versión más sencilla se ve así:
from google.adk.agents import Agent
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
Incluso este es un agente funcional con un nombre, comportamiento, un modelo y la capacidad de ejecutarse. Puede chatear, pero no puede interactuar con nada fuera de sí mismo hasta que obtenga herramientas.
Herramientas
Lo que define a la IA agente es el uso de herramientas. Sin ellas, un modelo solo genera texto, mientras que con ellas un agente puede aplicar lógica real. En ADK, una función simple de Python se convierte en una herramienta en cuanto se le pasa a la configuración del agente. Un agente calculador muestra cómo:
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]
)
Aquí el modelo comprende la solicitud, pero en lugar de realizar la aritmética por sí mismo, delega el cálculo exacto a la función. El LLM se encarga del razonamiento y la herramienta de su ejecución. Esa división es la base de diseños empresariales serios.
Los sistemas reales rara vez dependen de una sola herramienta. Un asistente puede llamar a APIs, convertir datos, consultar una base de datos, obtener documentos, verificar políticas y resumir resultados. Un agente multiherramientas combina aritmética, conversión de unidades y búsqueda de información meteorológica:
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,
],
)
El agente ahora actúa como orquestador. Elige herramientas sobre la marcha según la solicitud, y el usuario nunca tiene que indicar cuál utilizar.
Agentes como herramientas de otros agentes
ADK permite que un agente sirva como herramienta para otro, lo que fomenta la especialización. En lugar de un único prompt gigantesco que intenta abarcar todo, se crean agentes más pequeños con tareas específicas. Un planificador de viajes compuesto por varios agentes ilustra esto:
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)
]
)
El agente raíz funciona como un orquestador sin un flujo de trabajo fijo, y cada subagente es un especialista al que se puede llamar en cualquier orden. Un sistema de este tipo es más sencillo de mantener, escalar y comprender, lo cual coincide con la dirección que están tomando muchos diseños de IA empresarial.
Flujos estructurados
No todo proceso debe ser completamente autónomo, ya que los sistemas empresariales suelen necesitar estructura. Una forma común es planificar primero, luego ejecutar y finalmente informar. ADK lo aborda mediante agentes secuenciales, como en esta cadena de planificador, ejecutor e informante:
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,
],
)
Desarrollo local
El bucle local de ADK es rápido. Primero, un archivo .env establece el proyecto de Google Cloud, la ubicación y el uso de Vertex AI:
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True
Luego, un comando inicia una interfaz web local para probar los agentes de forma interactiva:
adk web
Ese ciclo rápido es adecuado para la experimentación.
Despliegue en Cloud Run
Las pruebas locales solo llegan hasta cierto punto, y Cloud Run es una de las vías más sencillas para el entorno de producción. Para el primer agente mencionado, basta con un Dockerfile breve:
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"]
Despliegue desde el origen con gcloud:
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
Después, busque la URL del servicio:
gcloud run services describe simple-agent \
--region us-central1 \
--format='value(status.url)'
Al abrir esa URL, se accede directamente a la interfaz de ADK desde Cloud Run. El resultado es un servicio de IA listo para desplegarse, y no solo una herramienta experimental para notas.
Exponer una API con FastAPI
A veces una API HTTP es más adecuada que una interfaz de navegador, y ADK funciona bien con FastAPI. Un main.py mínimo que contiene al agente de herramientas meteorológicas se ve así:
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
}
Para desplegarlo se necesita un Dockerfile ligeramente diferente:
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"]
Agent Engine
ADK también puede desplegarse en el Agent Engine de Google, un entorno de ejecución gestionado diseñado para la ejecución de agentes empresariales. Comience habilitando las API necesarias:
gcloud services enable \
aiplatform.googleapis.com \
storage.googleapis.com
A continuación, cree un bucket de staging:
export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"
gsutil mb -l us-central1 $STAGING_BUCKET
Luego, implemente el agente:
adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent
Esto genera un recurso de motor de razonamiento gestionado en Google Cloud, y el proceso es sencillo teniendo en cuenta todo lo que ocurre en el fondo.
Por qué es importante
La IA agente representa una forma diferente de desarrollar software basado en modelos de lenguaje, y no solo se trata de prompts más eficaces. Los agentes razonan, utilizan herramientas, coordinan flujos de trabajo y trabajan con sistemas externos en lugar de generar respuestas aisladas.
ADK es una excelente herramienta de aprendizaje, ya que introduce estas ideas de forma gradual. Comienzas con un agente Gemini, añades herramientas, conectas varios agentes y, posteriormente, pasas a flujos de trabajo empresariales que incluyen integraciones RAG y MCP, pipelines de evaluación y despliegue en GCP. Los mismos principios se aplican, desde el ejemplo de la calculadora hasta una configuración empresarial multiagente: razonamiento, delegación, orquestación y ejecución. El software está pasando de responder preguntas a operar dentro de aplicaciones reales.
Leer más
- Diseñando un Checkout Agente: Autoridad delegada, cotizaciones obsoletas y reintentos — Una guía paso a paso para el diseño de sistemas de compras gestionadas por agentes: mandatos, ofertas caducadas, claves de idempotencia que fallan, comerciante registrado, rastreos de auditoría y una guía de puntuación.
- Un mismo agente, tres implementaciones: Interactions API vs ADK vs Antigravity SDK — Crea un agente de opiniones para Hacker News en BigQuery utilizando la Interactions API, ADK y el Antigravity SDK; compara los ciclos de trabajo, las herramientas y los mecanismos de autenticación, y despliega cada uno en Cloud Run.