Next ‘26: Conferencia para desarrolladores: Cómo crear agentes del ADK con habilidades y herramientas

1. Introducción

En este codelab, crearás un sofisticado agente de planificación de maratones con el Kit de desarrollo de agentes (ADK). Examinarás progresivamente las capacidades del agente, desde una instrucción del sistema bien estructurada hasta la carga dinámica de habilidades y el mapeo de herramientas de MCP. Por último, probarás el agente de forma local y lo implementarás en el entorno de ejecución del agente (Agent Engine).

Actividades

  • Inicializa un nuevo proyecto de agente del ADK
  • Redacta una instrucción del sistema sólida con un compilador estructurado
  • Agrega herramientas de MCP de Google Maps para el contexto de ubicación del mundo real
  • Cargar habilidades de forma dinámica en el conjunto de herramientas del agente
  • Prueba la ejecución del agente de forma local
  • Implementa el agente en Agent Engine (Cloud Run)

Requisitos

  • Un navegador web, como Chrome
  • Un proyecto de Google Cloud con la facturación habilitada.
  • Conocimientos básicos sobre Python

Este codelab es para desarrolladores intermedios que buscan crear agentes especializados de IA generativa.

Duración estimada: 45 minutos

Los recursos creados en este codelab deberían costar menos de USD 2.

2. Antes de comenzar

Crea un proyecto de Google Cloud

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Inicie Cloud Shell

Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias.

  1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
  2. Una vez que te conectes a Cloud Shell, verifica tu autenticación:
    gcloud auth list
  3. Confirma que tu proyecto esté configurado:
    gcloud config get project
  4. Si tu proyecto no está configurado como se esperaba, configúralo:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Verifica la autenticación:

gcloud auth list

Confirma tu proyecto:

gcloud config get project

Establécela si es necesario:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Habilita las APIs

Ejecuta este comando para habilitar todas las APIs requeridas:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Crea una clave de API de Google Maps

Para usar las herramientas de MCP de Google Maps, debes generar una clave de la API de Maps.

  1. En la consola de Google Cloud, usa la barra de búsqueda para navegar a Google Maps Platform > Credenciales.
  2. Si se te solicita, confirma tu proyecto de Google Cloud.
  3. Haz clic en Crear credenciales y selecciona Clave de API.
  4. Copia la clave de API generada. La necesitarás en el próximo paso.

3. Configura tu entorno

En este codelab, el código se aloja en GitHub. Clonarás el repositorio, que contiene la estructura de directorios y los subcomponentes necesarios (como el directorio skills/).

  1. Clona el repositorio y navega a la carpeta del proyecto:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Configura un entorno virtual de Python y, luego, instala el ADK:
uv venv
source .venv/bin/activate
uv sync
  1. Configura tu clave de API de Google Maps. La aplicación la lee de una variable de entorno:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Configura variables de entorno

El agente de Simulator usa un archivo .env para la configuración. Copia el archivo de ejemplo y actualízalo con tu ID del proyecto.

  1. Copia el archivo de entorno de muestra:
cp planner_agent/sample.env planner_agent/.env
  1. Abre planner_agent/.env y actualiza el campo GOOGLE_CLOUD_PROJECT con tu ID de proyecto de Google Cloud real, y actualiza el campo GOOGLE_MAPS_API_KEY con la clave de la API de Google Maps que creaste.

El archivo debería verse de la siguiente manera:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Crea un agente nuevo del ADK

Explora el archivo principal que define el agente: planner_agent/agent.py.

En el repositorio build-agents-with-skills, el agente se inicializa con la clase Agent del ADK. Especifica el modelo subyacente, un nombre de identidad y extrae las instrucciones y las herramientas definidas en otros módulos.

Abre planner_agent/agent.py para examinar el código de inicialización:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

La clase Agent abstrae el historial de mensajes, la organización de herramientas y la comunicación con el LLM, lo que te permite enfocarte en el comportamiento del agente.

En este momento, el agente es muy genérico. Puedes interactuar con él como con cualquier otro LLM.

uv run adk run planner_agent

Este comando iniciará un chat con el agente. Utiliza gemini-3-flash-preview como modelo y puede responder preguntas básicas.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

El agente ya conoce algunos datos sobre las maratones. Sin embargo, esto no es suficiente para planificar una maratón adecuada con reglas y planificación de rutas.

5. Crea una instrucción del sistema

Las instrucciones del sistema dictan el comportamiento del agente. En lugar de una sola cadena gigante, este proyecto usa un PromptBuilder (planner_agent/utils.py) para componer instrucciones de forma dinámica.

Abre planner_agent/prompts.py para ver cómo se estructura la instrucción en secciones lógicas:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

De vuelta en planner_agent/agent.py, ya se importó.

Busca la sección con TODO: Replace Instruction and Description y quita el comentario de la reasignación de las variables instruction y description.

Esa sección del código debería verse de la siguiente manera:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

Estás importando una versión de la instrucción para el agente que no hace referencia a ninguna herramienta. Agregarás herramientas en un paso posterior.

Puedes probar esta versión del agente:

uv run adk run planner_agent

En la ventana del chat, envía la siguiente instrucción:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Después de unos momentos, deberías recibir una respuesta similar a esta:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

Con una instrucción bien definida, el resultado ya se acerca mucho más al resultado esperado. En el siguiente paso, agregarás herramientas para llevar al agente al siguiente nivel.

6. Agrega habilidades y herramientas

Para habilitar las habilidades y herramientas en planner_agent/agent.py, busca la sección con TODO: Replaces Tools y quita el comentario de las siguientes dos líneas. El código debería verse como este fragmento:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Ese es el único cambio de código que se requiere en este paso. En el resto de esta sección, se explican los conceptos detrás de las habilidades y las herramientas.

Habilidades

Una habilidad de agente es una unidad autónoma de funcionalidad que un agente del ADK puede usar para realizar una tarea específica. Una habilidad del agente encapsula las instrucciones, los recursos y las herramientas necesarios para una tarea, según la especificación de la habilidad del agente. La estructura de una habilidad permite que se cargue de forma incremental para minimizar el impacto en la ventana de contexto operativo del agente.

En el caso del agente de planificación de maratones, se definen 3 habilidades:

  1. gis-spatial-engineering: Es responsable de procesar los datos de GeoJSON para crear la ruta de la maratón.
  2. mapping: Usa las herramientas de Google Maps para buscar lugares y obtener información del clima.
  3. race-director: Valida que la ruta de la maratón siga los lineamientos de planificación.

Las habilidades pueden tener secuencias de comandos, recursos adicionales y referencias.

La aplicación carga todas las habilidades y las proporciona como herramientas en planner_agent/tools.py. Observa cómo se hace esto en la función get_tools():

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

La parte más interesante es el método load_skill_from_dir del ADK. Existe otra forma de crear habilidades en el ADK, y es de forma intercalada. Si bien no se usa en este codelab, se ve de la siguiente manera:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Agregar herramientas de asignación

El planificador de maratones necesita contexto espacial para generar rutas. Para ello, debes integrar el servidor de MCP (Protocolo de contexto del modelo) de Google Maps.

En planner_agent/tools.py, observa cómo se registra el servidor de MCP con la herramienta ApiRegistry:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

Cuando se agrega el conjunto de herramientas de MCP, el agente obtiene automáticamente la capacidad de consultar Google Maps para obtener detalles sobre rutas, elevación y ubicación.

7. Ejecuta el agente de forma local

Ahora que el agente, la instrucción y las herramientas están conectados, ejecuta el agente de forma local. Esta vez, usarás adk web para que puedas ver los eventos de Skill Load y Tool Call.

uv run adk web

Deberías ver algo similar

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. Abre el navegador y ve a la URL que se muestra en la terminal (por lo general, http://localhost:8000).
  2. En el menú desplegable de la esquina superior izquierda, selecciona planner_agent.
  3. En la ventana del chat, envía la siguiente instrucción:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Deberías ver que se cargan las habilidades y se llaman las herramientas. Después de unos momentos, el agente generará un plan de maratón.

Tu IU debería verse similar a la siguiente:

IU web del ADK

8. Implementa el agente

Cuando estés conforme con el rendimiento del agente a nivel local, puedes implementarlo en Agent Engine, que aloja el agente en Cloud Run de forma segura.

Para implementar el agente, usa el comando de implementación de la CLI del ADK:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

Cuando finalice la implementación, la CLI generará un extremo alojado de forma segura para tu agente. Ahora puedes integrar este extremo en aplicaciones de frontend, chatbots o cualquier otro sistema de backend. También puedes usar Agent Runtime Playground para probar el agente.

El resultado luce de la siguiente manera:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Puedes usar la secuencia de comandos de Python proporcionada para comunicarte con el agente.

  1. Copia el archivo de entorno de muestra:
cp sample.env .env
  1. Abre .env y actualiza el campo GOOGLE_CLOUD_PROJECT con el ID real de tu proyecto de Google Cloud.

El archivo debe verse de la manera siguiente.

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Puedes enumerar los agentes de tu proyecto.
python main.py list

Deberías ver algo similar

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Una vez que tengas el ID del agente implementado, puedes enviar una instrucción:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

Obtendrás un resultado similar al siguiente:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Borra el servicio de Cloud Run creado por la implementación:

python main.py delete --agent-id ${AGENT_ID}

Si almacenaste la clave de la API de Maps en Secret Manager, borra el secreto:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Si creaste un proyecto de Google Cloud nuevo para este codelab, puedes borrar todo el proyecto para quitar todos los recursos y las APIs asociados a él:

gcloud projects delete $PROJECT_ID

10. Felicitaciones

¡Felicitaciones! Compilaste un agente sofisticado de Planificador de maratones con el ADK.

Qué aprendiste

  • Cómo inicializar un proyecto del Kit de desarrollo de agentes (ADK)
  • Cómo utilizar PromptBuilder para instrucciones del sistema modulares
  • Integración de funciones de asignación con herramientas de MCP y ApiRegistry
  • Cómo cargar habilidades de forma condicional con SkillToolset
  • Pruebas locales e implementación en Agent Engine

Documentos de referencia