Construye un agente multi-herramienta¶

Esta guía de inicio rápido te orienta a través de la instalación del Agent Development Kit (ADK), la configuración de un agente básico con múltiples herramientas, y su ejecución local, ya sea en la terminal o en la interfaz de desarrollo interactiva basada en navegador.

Esta guía de inicio rápido asume un IDE local (VS Code, PyCharm, IntelliJ IDEA, etc.) con Python 3.10+ o Java 17+ y acceso a terminal. Este método ejecuta la aplicación completamente en tu máquina y es recomendado para desarrollo interno.

1. Configura el Entorno e Instala ADK¶

PythonTypeScriptJava

Crea y Activa el Entorno Virtual (Recomendado):

# Crear
python -m venv .venv
# Activar (cada nueva terminal)
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

Instala ADK:

pip install google-adk

Crea un nuevo directorio de proyecto, inicialízalo e instala las dependencias:

mkdir my-adk-agent
cd my-adk-agent
npm init -y
npm install @google/adk @google/adk-devtools
npm install -D typescript

Crea un archivo tsconfig.json con el siguiente contenido. Esta configuración asegura que tu proyecto maneje correctamente los módulos modernos de Node.js.

tsconfig.json

{
  "compilerOptions": {
    "target": "es2020",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    // establecer en false para permitir sintaxis de módulos CommonJS:
    "verbatimModuleSyntax": false
  }
}

Para instalar ADK y configurar el entorno, procede con los siguientes pasos.

2. Crea el Proyecto del Agente¶

Estructura del proyecto¶

PythonTypeScriptJava

Necesitarás crear la siguiente estructura de proyecto:

parent_folder/
    multi_tool_agent/
        __init__.py
        agent.py
        .env

Crea la carpeta multi_tool_agent:

mkdir multi_tool_agent/

Nota para usuarios de Windows

Al usar ADK en Windows para los próximos pasos, recomendamos crear archivos Python usando el Explorador de archivos o un IDE porque los siguientes comandos (mkdir, echo) típicamente generan archivos con bytes nulos y/o codificación incorrecta.

`init.py`¶

Ahora crea un archivo __init__.py en la carpeta:

echo "from . import agent" > multi_tool_agent/__init__.py

Tu __init__.py ahora debería verse así:

multi_tool_agent/__init__.py

from . import agent

`agent.py`¶

Crea un archivo agent.py en la misma carpeta:

OS X & LinuxWindows

touch multi_tool_agent/agent.py

type nul > multi_tool_agent/agent.py

Copia y pega el siguiente código en agent.py:

multi_tool_agent/agent.py

import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city for which to retrieve the weather report.

    Returns:
        dict: status and result or error msg.
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "The weather in New York is sunny with a temperature of 25 degrees"
                " Celsius (77 degrees Fahrenheit)."
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"Weather information for '{city}' is not available.",
        }


def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city.

    Args:
        city (str): The name of the city for which to retrieve the current time.

    Returns:
        dict: status and result or error msg.
    """

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {
            "status": "error",
            "error_message": (
                f"Sorry, I don't have timezone information for {city}."
            ),
        }

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    report = (
        f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
    )
    return {"status": "success", "report": report}


root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash",
    description=(
        "Agent to answer questions about the time and weather in a city."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the time and weather in a city."
    ),
    tools=[get_weather, get_current_time],
)

`.env`¶

Crea un archivo .env en la misma carpeta:

OS X & LinuxWindows

touch multi_tool_agent/.env

type nul > multi_tool_agent\.env

Más instrucciones sobre este archivo se describen en la siguiente sección sobre Configura el modelo.

Necesitarás crear la siguiente estructura de proyecto en tu directorio my-adk-agent:

my-adk-agent/
    agent.ts
    .env
    package.json
    tsconfig.json

`agent.ts`¶

Crea un archivo agent.ts en tu carpeta de proyecto:

OS X & LinuxWindows

touch agent.ts

type nul > agent.ts

Copia y pega el siguiente código en agent.ts:

agent.ts

import 'dotenv/config';
import { FunctionTool, LlmAgent } from '@google/adk';
import { z } from 'zod';

const getWeather = new FunctionTool({
  name: 'get_weather',
  description: 'Retrieves the current weather report for a specified city.',
  parameters: z.object({
    city: z.string().describe('The name of the city for which to retrieve the weather report.'),
  }),
  execute: ({ city }) => {
    if (city.toLowerCase() === 'new york') {
      return {
        status: 'success',
        report:
          'The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).',
      };
    } else {
      return {
        status: 'error',
        error_message: `Weather information for '${city}' is not available.`,
      };
    }
  },
});

const getCurrentTime = new FunctionTool({
  name: 'get_current_time',
  description: 'Returns the current time in a specified city.',
  parameters: z.object({
    city: z.string().describe("The name of the city for which to retrieve the current time."),
  }),
  execute: ({ city }) => {
    let tz_identifier: string;
    if (city.toLowerCase() === 'new york') {
      tz_identifier = 'America/New_York';
    } else {
      return {
        status: 'error',
        error_message: `Sorry, I don't have timezone information for ${city}.`,
      };
    }

    const now = new Date();
    const report = `The current time in ${city} is ${now.toLocaleString('en-US', { timeZone: tz_identifier })}`;

    return { status: 'success', report: report };
  },
});

export const rootAgent = new LlmAgent({
  name: 'weather_time_agent',
  model: 'gemini-2.5-flash',
  description: 'Agent to answer questions about the time and weather in a city.',
  instruction: 'You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools: [getWeather, getCurrentTime],
});

`.env`¶

Crea un archivo .env en la misma carpeta:

OS X & LinuxWindows

touch .env

type nul > .env

Más instrucciones sobre este archivo se describen en la siguiente sección sobre Configura el modelo.

Los proyectos Java generalmente presentan la siguiente estructura de proyecto:

project_folder/
├── pom.xml (or build.gradle)
├── src/
├── └── main/
│       └── java/
│           └── agents/
│               └── multitool/
└── test/

Crea `MultiToolAgent.java`¶

Crea un archivo fuente MultiToolAgent.java en el paquete agents.multitool en el directorio src/main/java/agents/multitool/.

Copia y pega el siguiente código en MultiToolAgent.java:

agents/multitool/MultiToolAgent.java

package agents.multitool;

import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.LlmAgent;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.Session;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;
import java.nio.charset.StandardCharsets;
import java.text.Normalizer;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;
import java.util.Scanner;

public class MultiToolAgent {

    private static String USER_ID = "student";
    private static String NAME = "multi_tool_agent";

    // The run your agent with Dev UI, the ROOT_AGENT should be a global public static final variable.
    public static final BaseAgent ROOT_AGENT = initAgent();

    public static BaseAgent initAgent() {
        return LlmAgent.builder()
            .name(NAME)
            .model("gemini-2.0-flash")
            .description("Agent to answer questions about the time and weather in a city.")
            .instruction(
                "You are a helpful agent who can answer user questions about the time and weather"
                    + " in a city.")
            .tools(
                FunctionTool.create(MultiToolAgent.class, "getCurrentTime"),
                FunctionTool.create(MultiToolAgent.class, "getWeather"))
            .build();
    }

    public static Map<String, String> getCurrentTime(
        @Schema(name = "city",
                description = "The name of the city for which to retrieve the current time")
        String city) {
        String normalizedCity =
            Normalizer.normalize(city, Normalizer.Form.NFD)
                .trim()
                .toLowerCase()
                .replaceAll("(\\p{IsM}+|\\p{IsP}+)", "")
                .replaceAll("\\s+", "_");

        return ZoneId.getAvailableZoneIds().stream()
            .filter(zid -> zid.toLowerCase().endsWith("/" + normalizedCity))
            .findFirst()
            .map(
                zid ->
                    Map.of(
                        "status",
                        "success",
                        "report",
                        "The current time in "
                            + city
                            + " is "
                            + ZonedDateTime.now(ZoneId.of(zid))
                            .format(DateTimeFormatter.ofPattern("HH:mm"))
                            + "."))
            .orElse(
                Map.of(
                    "status",
                    "error",
                    "report",
                    "Sorry, I don't have timezone information for " + city + "."));
    }

    public static Map<String, String> getWeather(
        @Schema(name = "city",
                description = "The name of the city for which to retrieve the weather report")
        String city) {
        if (city.toLowerCase().equals("new york")) {
            return Map.of(
                "status",
                "success",
                "report",
                "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees"
                    + " Fahrenheit).");

        } else {
            return Map.of(
                "status", "error", "report", "Weather information for " + city + " is not available.");
        }
    }

    public static void main(String[] args) throws Exception {
        InMemoryRunner runner = new InMemoryRunner(ROOT_AGENT);

        Session session =
            runner
                .sessionService()
                .createSession(NAME, USER_ID)
                .blockingGet();

        try (Scanner scanner = new Scanner(System.in, StandardCharsets.UTF_8)) {
            while (true) {
                System.out.print("\nYou > ");
                String userInput = scanner.nextLine();

                if ("quit".equalsIgnoreCase(userInput)) {
                    break;
                }

                Content userMsg = Content.fromParts(Part.fromText(userInput));
                Flowable<Event> events = runner.runAsync(USER_ID, session.id(), userMsg);

                System.out.print("\nAgent > ");
                events.blockingForEach(event -> System.out.println(event.stringifyContent()));
            }
        }
    }
}

3. Configura el modelo¶

La capacidad de tu agente para comprender las solicitudes de los usuarios y generar respuestas es impulsada por un Modelo de Lenguaje Grande (LLM). Tu agente necesita realizar llamadas seguras a este servicio LLM externo, lo cual requiere credenciales de autenticación. Sin autenticación válida, el servicio LLM denegará las solicitudes del agente, y el agente no podrá funcionar.

Guía de Autenticación del Modelo

Para una guía detallada sobre cómo autenticarse con diferentes modelos, consulta la Guía de Autenticación. Este es un paso crítico para asegurar que tu agente pueda realizar llamadas al servicio LLM.

Gemini - Google AI StudioGemini - Google Cloud Vertex AIGemini - Google Cloud Vertex AI con Modo Express

Obtén una clave API de Google AI Studio.
Al usar Python, abre el archivo .env ubicado dentro de (multi_tool_agent/) y copia-pega el siguiente código.
multi_tool_agent/.env
```
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
```
Al usar Java, define las variables de entorno:
terminal
```
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
```
Al usar TypeScript, el archivo .env se carga automáticamente por la línea import 'dotenv/config'; al inicio de tu archivo agent.ts.

env title=""multi_tool_agent/.env" GOOGLE_GENAI_USE_VERTEXAI=FALSE GOOGLE_GENAI_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
Reemplaza PASTE_YOUR_ACTUAL_API_KEY_HERE con tu API KEY real.

Configura un proyecto de Google Cloud y habilita la API de Vertex AI.
Configura la CLI de gcloud.
Autentícate en Google Cloud desde la terminal ejecutando gcloud auth application-default login.
Al usar Python, abre el archivo .env ubicado dentro de (multi_tool_agent/). Copia-pega el siguiente código y actualiza el ID del proyecto y la ubicación.
multi_tool_agent/.env
```
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
```
Al usar Java, define las variables de entorno:
terminal
```
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
```
Al usar TypeScript, el archivo .env se carga automáticamente por la línea import 'dotenv/config'; al inicio de tu archivo agent.ts.
.env
```
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
```

¡Puedes registrarte para un proyecto gratuito de Google Cloud y usar Gemini gratis con una cuenta elegible!
- Configura un proyecto de Google Cloud con Modo Express de Vertex AI
- Obtén una clave API de tu proyecto en modo Express. Esta clave puede usarse con ADK para usar modelos Gemini gratis, así como acceso a servicios de Agent Engine.
Al usar Python, abre el archivo .env ubicado dentro de (multi_tool_agent/). Copia-pega el siguiente código y actualiza el ID del proyecto y la ubicación.
multi_tool_agent/.env
```
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE
```
Al usar Java, define las variables de entorno:
terminal
```
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE
```
Al usar TypeScript, el archivo .env se carga automáticamente por la línea import 'dotenv/config'; al inicio de tu archivo agent.ts.
.env
```
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_GENAI_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE
```

4. Ejecuta tu Agente¶

PythonTypeScriptJava

Usando la terminal, navega al directorio padre de tu proyecto de agente (ej. usando cd ..):

parent_folder/      <-- navega a este directorio
    multi_tool_agent/
        __init__.py
        agent.py
        .env

Hay múltiples formas de interactuar con tu agente:

Dev UI (adk web)Terminal (adk run)API Server (adk api_server)

Configuración de Autenticación para Usuarios de Vertex AI

Si seleccionaste "Gemini - Google Cloud Vertex AI" en el paso anterior, debes autenticarte con Google Cloud antes de iniciar la interfaz de desarrollo.

Ejecuta este comando y sigue las instrucciones:

gcloud auth application-default login

Nota: Omite este paso si estás usando "Gemini - Google AI Studio".

Ejecuta el siguiente comando para iniciar la interfaz de desarrollo.

adk web

Precaución: ADK Web solo para desarrollo

ADK Web no está destinado para uso en despliegues de producción. Debes usar ADK Web solo para propósitos de desarrollo y depuración.

Nota para usuarios de Windows

Al encontrar el error _make_subprocess_transport NotImplementedError, considera usar adk web --no-reload en su lugar.

Paso 1: Abre la URL proporcionada (usualmente http://localhost:8000 o http://127.0.0.1:8000) directamente en tu navegador.

Paso 2. En la esquina superior izquierda de la interfaz, puedes seleccionar tu agente en el menú desplegable. Selecciona "multi_tool_agent".

Solución de problemas

Si no ves "multi_tool_agent" en el menú desplegable, asegúrate de estar ejecutando adk web en la carpeta padre de tu carpeta de agente (es decir, la carpeta padre de multi_tool_agent).

Paso 3. Ahora puedes chatear con tu agente usando el cuadro de texto:

Paso 4. Usando la pestaña Events a la izquierda, puedes inspeccionar llamadas de función individuales, respuestas y respuestas del modelo haciendo clic en las acciones:

En la pestaña Events, también puedes hacer clic en el botón Trace para ver los registros de seguimiento de cada evento que muestra la latencia de cada llamada de función:

Paso 5. También puedes habilitar tu micrófono y hablar con tu agente:

Soporte de modelo para streaming de voz/video

Para usar streaming de voz/video en ADK, necesitarás usar modelos Gemini que soporten la API Live. Puedes encontrar el/los ID(s) de modelo que soportan la API Live de Gemini en la documentación:

Luego puedes reemplazar la cadena model en root_agent en el archivo agent.py que creaste anteriormente (saltar a la sección). Tu código debería verse algo así:

root_agent = Agent(
    name="weather_time_agent",
    model="replace-me-with-model-id", #ej. gemini-2.0-flash-live-001
    ...

Tip

Al usar adk run puedes inyectar prompts en el agente para comenzar canalizando texto al comando de esta manera:

echo "Please start by listing files" | adk run file_listing_agent

Ejecuta el siguiente comando para chatear con tu agente Weather.

adk run multi_tool_agent

Para salir, usa Cmd/Ctrl+C.

adk api_server te permite crear un servidor FastAPI local en un solo comando, permitiéndote probar solicitudes cURL locales antes de desplegar tu agente.

Para aprender cómo usar adk api_server para pruebas, consulta la documentación sobre el uso del servidor API.

Usando la terminal, navega al directorio de tu proyecto de agente:

my-adk-agent/      <-- navega a este directorio
    agent.ts
    .env
    package.json
    tsconfig.json

Hay múltiples formas de interactuar con tu agente:

Dev UI (adk web)Terminal (adk run)API Server (adk api_server)

Ejecuta el siguiente comando para iniciar la interfaz de desarrollo.

npx adk web

Paso 1: Abre la URL proporcionada (usualmente http://localhost:8000 o http://127.0.0.1:8000) directamente en tu navegador.

Paso 2. En la esquina superior izquierda de la interfaz, selecciona tu agente del menú desplegable. Los agentes se listan por sus nombres de archivo, por lo que deberías seleccionar "agent".

Solución de problemas

Si no ves "agent" en el menú desplegable, asegúrate de estar ejecutando npx adk web en el directorio que contiene tu archivo agent.ts.

Paso 3. Ahora puedes chatear con tu agente usando el cuadro de texto:

Paso 4. Usando la pestaña Events a la izquierda, puedes inspeccionar llamadas de función individuales, respuestas y respuestas del modelo haciendo clic en las acciones:

En la pestaña Events, también puedes hacer clic en el botón Trace para ver los registros de seguimiento de cada evento que muestra la latencia de cada llamada de función:

Ejecuta el siguiente comando para chatear con tu agente.

npx adk run agent.ts

Para salir, usa Cmd/Ctrl+C.

npx adk api_server te permite crear un servidor Express.js local en un solo comando, permitiéndote probar solicitudes cURL locales antes de desplegar tu agente.

Para aprender cómo usar api_server para pruebas, consulta la documentación sobre pruebas.

Usando la terminal, navega al directorio padre de tu proyecto de agente (ej. usando cd ..):

project_folder/                <-- navega a este directorio
├── pom.xml (or build.gradle)
├── src/
├── └── main/
│       └── java/
│           └── agents/
│               └── multitool/
│                   └── MultiToolAgent.java
└── test/

Dev UIMavenGradle

Ejecuta el siguiente comando desde la terminal para iniciar la interfaz de desarrollo.

NO cambies el nombre de la clase principal del servidor Dev UI.

terminal

mvn exec:java \
    -Dexec.mainClass="com.google.adk.web.AdkWebServer" \
    -Dexec.args="--adk.agents.source-dir=src/main/java" \
    -Dexec.classpathScope="compile"

Paso 1: Abre la URL proporcionada (usualmente http://localhost:8080 o http://127.0.0.1:8080) directamente en tu navegador.

Paso 2. En la esquina superior izquierda de la interfaz, puedes seleccionar tu agente en el menú desplegable. Selecciona "multi_tool_agent".

Solución de problemas

Si no ves "multi_tool_agent" en el menú desplegable, asegúrate de estar ejecutando el comando mvn en la ubicación donde se encuentra tu código fuente Java (usualmente src/main/java).

Paso 3. Ahora puedes chatear con tu agente usando el cuadro de texto:

Paso 4. También puedes inspeccionar llamadas de función individuales, respuestas y respuestas del modelo haciendo clic en las acciones:

Precaución: ADK Web solo para desarrollo

ADK Web no está destinado para uso en despliegues de producción. Debes usar ADK Web solo para propósitos de desarrollo y depuración.

Con Maven, ejecuta el método main() de tu clase Java con el siguiente comando:

terminal

mvn compile exec:java -Dexec.mainClass="agents.multitool.MultiToolAgent"

Con Gradle, el archivo de construcción build.gradle o build.gradle.kts debe tener el siguiente plugin de Java en su sección plugins:

plugins {
    id('java')
    // otros plugins
}

Luego, en otra parte del archivo de construcción, al nivel superior, crea una nueva tarea para ejecutar el método main() de tu agente:

tasks.register('runAgent', JavaExec) {
    classpath = sourceSets.main.runtimeClasspath
    mainClass = 'agents.multitool.MultiToolAgent'
}

Finalmente, en la línea de comandos, ejecuta el siguiente comando:

gradle runAgent

📝 Ejemplos de prompts para probar¶

¿Cuál es el clima en Nueva York?
¿Qué hora es en Nueva York?
¿Cuál es el clima en París?
¿Qué hora es en París?

🎉 ¡Felicitaciones!¶

¡Has creado e interactuado exitosamente con tu primer agente usando ADK!

🛣️ Próximos pasos¶

Ve al tutorial: Aprende cómo agregar memoria, sesión, estado a tu agente: tutorial.
Profundiza en la configuración avanzada: Explora la sección de configuración para inmersiones más profundas en estructura de proyecto, configuración y otras interfaces.
Comprende los Conceptos Fundamentales: Aprende sobre conceptos de agentes.

Construye un agente multi-herramienta¶

1. Configura el Entorno e Instala ADK¶

2. Crea el Proyecto del Agente¶

Estructura del proyecto¶

__init__.py¶

agent.py¶

.env¶

agent.ts¶

.env¶

Crea MultiToolAgent.java¶

3. Configura el modelo¶

4. Ejecuta tu Agente¶

📝 Ejemplos de prompts para probar¶

🎉 ¡Felicitaciones!¶

🛣️ Próximos pasos¶

`init.py`¶

`agent.py`¶

`.env`¶

`agent.ts`¶

`.env`¶

Crea `MultiToolAgent.java`¶