programa
Fundamentos de agentes de IA
6 h
A principios de esta semana, en la conferencia para desarrolladores Google I/O 2026, Google lanzó los Gemini Managed agents, una herramienta que simplifica el despliegue de agentes de IA autónomos. Permite a los desarrolladores crear agentes capaces de razonar, planificar, navegar por la web y ejecutar código en un entorno Linux aislado y temporal con una sola llamada a la API.
En este tutorial, aprenderás qué son los Gemini Managed Agents, cómo funcionan y cómo usar su API para crear un agente de analista de datos capaz de analizar cualquier tipo de dato.
¿Nuevo en la IA con agentes? Empieza con nuestro curso Introduction to AI Agents.
¿Qué son los agentes gestionados en la API de Gemini?
Piensa en un agente como un trabajador autónomo con acceso a su propio ordenador aislado. Cuando le das una tarea, como analizar un conjunto de datos, el agente escribe y ejecuta de forma autónoma el código necesario para completarla. Una vez que termina, puedes acceder al espacio de trabajo del agente para recuperar los resultados.
Los agentes gestionados no solo escriben código; también pueden interactuar con internet, gestionar archivos y utilizar un amplio abanico de herramientas para agilizar la ejecución de tareas.
Estos agentes están impulsados por Antigravity de Google, un arnés de agente de propósito general para los modelos Gemini.
Incluye un conjunto preconfigurado de herramientas operativas directamente en el entorno de ejecución, lo que elimina la necesidad de configuraciones manuales. Entre ellas hay un runtime aislado para ejecutar código en Bash, Python y Node.js, que permite al agente escribir, depurar y ejecutar código localmente.
También ofrece gestión de archivos mediante un sistema de archivos persistente dentro del contenedor remoto, donde el agente puede leer, escribir, editar y buscar archivos a lo largo de turnos secuenciales.
Por último, la integración web proporciona acceso directo a Google Search para fundamentar la información en tiempo real, junto con utilidades para obtener y analizar datos online no estructurados.
Ejemplo de uso
Imagina que gestionamos una cafetería y queremos analizar nuestras ventas. Podemos configurar un agente gestionado para que acceda a nuestra base de datos de ventas.
Luego, cuando necesitemos un informe, solo tenemos que pedir en lenguaje natural que analice los datos. El agente escribe y ejecuta autónomamente el código en Python, genera un informe resumen y lo guarda en nuestro sistema de archivos para revisarlo.
Introducción a los agentes de IA
Aprende los fundamentos de los agentes de IA, sus componentes y su uso en el mundo real, sin necesidad de programar.
¿Cuánto cuestan los agentes gestionados en la API de Gemini?
Hay muchos componentes involucrados en el precio de los Gemini Managed Agents, lo que dificulta estimar costes con precisión. El coste viene determinado por cuatro factores principales:
- Uso del modelo (tokens): Se cobra en función del número de tokens de entrada y salida procesados por el modelo Gemini subyacente. Ten en cuenta que incluye los tokens generados en resultados intermedios. Por ejemplo, si el agente genera un script en Python para crear un informe, los tokens necesarios para ese script también se facturan.
- Infraestructura y tarifas de plataforma: Los agentes gestionados se ejecutan dentro del entorno integrado de Google, lo que conlleva tarifas de servicio por usar las herramientas de la plataforma (como Vertex AI Agent Builder) para gestionar y desplegar agentes.
- Context caching: Si los agentes reutilizan con frecuencia los mismos datos, pueden aprovechar la caché de contexto. Esto suele suponer una reducción de costes significativa frente al precio estándar por token.
- Grounding: Si el agente usa servicios de grounding de Google como Google Search o Google Maps, se facturan por separado, a menudo con una cuota de peticiones gratuitas y después un coste por 1.000 consultas (normalmente alrededor de 14 $ por 1.000 consultas).
En este tutorial, crearemos un agente sobre el agente antigravity-preview-05-2026, impulsado por Gemini 3.5 Flash. Sus costes por token son los siguientes:
Cómo crear agentes gestionados en la API de Gemini
En esta guía, vamos a crear un agente gestionado con la API de Gemini y Python. Dado que los agentes gestionados son una versión reciente y están en beta, ten en cuenta que algunos detalles de implementación pueden cambiar.
Todo el código que escribiremos en este tutorial está en este repositorio de GitHub, que también usaremos para compartir datos con el agente analista de datos.
Configuración de la API
Para crear una clave de IA, ve a Google AI Studio y haz clic en “Create API Key” arriba a la derecha.
Las API keys deben asociarse a un proyecto de Google Cloud. Puedes seleccionar uno existente o crear uno nuevo. Aquí he creado uno llamado gemini-managed-agents.
Tras crear la clave, la copiamos. Luego creamos un archivo llamado .env en la carpeta donde crearemos nuestros agentes y pegamos lo siguiente con este formato:
GEMINI_API_KEY=<paste_your_api_key_here>Antes de cerrar Google AI Studio, debemos configurar la facturación en la API key que acabamos de crear. Sin esto, nuestras peticiones serán denegadas ya que Google no podrá cobrarnos. Para configurar la facturación, haz clic en el botón “Set up billing”.
Configuración del entorno de Python
Usaremos Anaconda para configurar un entorno de Python para este proyecto. Para crearlo con Anaconda, utiliza el comando:
conda create --name gemini_agents python=3.12 -yEsto crea un entorno llamado gemini_agents con Python 3.12. El parámetro -y es un atajo para responder “sí” a todas las preguntas durante la creación del entorno.
A continuación, hay que activarlo:
conda activate gemini_agentsPor último, instalamos las dependencias necesarias. Así:
pip install google-genai requests python-dotenvCrear una interacción básica con un agente gestionado
Ya tenemos todo listo para ejecutar nuestro primer agente. Este primer agente no hará gran cosa: solo instalará matplotlib e informará de la versión instalada.
Aquí tienes una explicación paso a paso de cómo podemos interactuar con un agente gestionado (el código completo está en el script simple_interaction.py del repositorio):
Primero, importamos los paquetes necesarios y cargamos la API key desde el archivo .env que creamos antes:
from dotenv import load_dotenv
from google import genai
# Load secure environment variables
load_dotenv()Después, inicializamos el cliente de Gemini y creamos una interacción con el agente base, actualmente llamado antigravity-preview-05-2026, pidiéndole que instale matplotlib:
# Initialize the GenAI Client
client = genai.Client()
# Create a basic interaction with a managed agent
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Install the matplotlib package, verify its version, and report back.",
environment="remote"
)Por último, obtenemos la salida del agente inspeccionando las propiedades status, environment_id y output_text:
# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")Este es el resultado:
Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.
Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9Estados del ciclo de vida del sandbox
En el ejemplo anterior mostramos el identificador del entorno de la interacción del agente gestionado:
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6Este valor es importante porque representa el identificador del entorno donde se ejecutó el agente. Las interacciones del agente se almacenan en un entorno efímero que se conserva hasta 7 días después de la última actividad antes de ser eliminado.
El diagrama ilustra el ciclo de vida del sandbox donde se ejecuta el agente durante una interacción.
Mientras el entorno no se elimine, podemos acceder a él y realizar más interacciones usando su identificador.
Realizar múltiples interacciones
En este ejemplo mostramos cómo realizar múltiples interacciones. El código completo está disponible en el archivo multiple_interactions.py del repositorio.
# First interaction
inter1 = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Write a Python script sum.py that adds all integers from 1 to 100.",
environment="remote"
)
# Second interaction
inter2 = client.interactions.create(
agent="antigravity-preview-05-2026",
previous_interaction_id=inter1.id, # Passes the conversation history
environment=inter1.environment_id, # Keeps the same filesystem state
input="Execute 'sum.py' using Python and display the standard output."
)
# Output the status of the agent
print(f"Output:\n{inter2.output_text}")Observa que en la segunda interacción añadimos dos parámetros:
-
previous_interaction_id: el identificador de la interacción anterior, para que el agente conozca el historial de la conversación. -
environment: el identificador del entorno para indicar en qué sandbox debe ejecutarse el agente.
Compartir archivos con un agente
No podemos crear un agente analista de datos si no podemos darle acceso a los datos. Hay varias formas de compartir datos con un agente:
- Datos inline: Cargar el contenido del archivo en una cadena y enviarlo durante la interacción.
- Archivo alojado: Alojar los datos en una URL pública y proporcionar esa URL para que el agente los descargue.
- Repositorio de GitHub: Proporcionar al agente la URL de un repositorio público de GitHub.
- Bucket de Google Cloud: Alojar un archivo en un bucket de Google Cloud Storage y configurar el proyecto para que el agente tenga acceso a ese bucket.
No exploraremos todas estas soluciones en este artículo. Veremos cómo enviar datos inline cargando un archivo local en una cadena y cómo compartir un repositorio de GitHub. La primera es ideal para compartir archivos locales pequeños (hasta 1 MB por archivo, con un límite total de 2 MB entre todos), mientras que la segunda es más adecuada para archivos grandes, como datasets.
Compartir datos inline
Aquí tienes un ejemplo de cómo proporcionar datos inline (código completo en inline_example.py):
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
# The file where to store the data in the agent environment
"target": "/workspace/numbers.txt",
# Assumes that the file data/numbers.txt exists
"content": utils.read_text_file("data/numbers.txt")
}
]
}
)Los datos se proporcionan usando el parámetro sources en la configuración de environment. El target define dónde se almacenará la información en el entorno del agente. Los archivos deben estar en la carpeta workspace. En este caso, será un archivo llamado number.txt.
El parámetro content aporta el contenido del archivo. Para fuentes inline, es simplemente una cadena, que en este caso leemos con la función read_text_file() del archivo utils.py.
Compartir un repositorio de GitHub
Para compartir archivos más grandes, podemos proporcionar la URL de un repositorio de GitHub. Así se hace:
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/repository/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}
)En el ejemplo anterior, el repositorio con URL https://github.com/fran-aubry/gemini-agents-tutorial se clona en una carpeta llamada repository dentro del espacio de trabajo del agente.
Descargar el entorno de un agente
Ya hemos visto cómo interactuar con agentes gestionados y cómo proporcionarles archivos. Para crear nuestro agente analista de datos, lo último que necesitamos aprender es a descargar el entorno de un agente. Así podremos acceder a los gráficos y resultados generados por el agente.
Cada workspace se puede descargar desde la URL:
https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:downloadDonde debes sustituir <env_id> por el identificador del entorno que quieras descargar.
Aquí tienes una función en Python que usa el paquete requests para descargar un paquete (esta función forma parte del archivo utils.py que creamos):
def download_env(env_id, path="environments"):
download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
try:
request_params = {"alt": "media"} # Retrieves raw media binary
request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
# Download the environment
print(f"Downloading environment: {env_id}")
response = requests.get(
download_url,
params=request_params,
headers=request_headers,
allow_redirects=True
)
response.raise_for_status()
# Save the compressed workspace archive locally
archive_name = f"{env_id}.tar"
output_path = os.path.join(path, archive_name)
with open(output_path, "wb") as archive_file:
archive_file.write(response.content)
print(f"Successfully downloaded workspace snapshot archive: {output_path}")
except requests.exceptions.RequestException as error:
print(f"Failed to download sandbox workspace via HTTP request: {error}")
except tarfile.TarError as archive_error:
print(f"Failed to unpack download tarball: {archive_error}")Crear un agente analista de datos
En esta sección, aprenderás a crear un agente que realice análisis de datos. Para probarlo, usaremos este dataset de Netflix de Kaggle, que también está en la carpeta data de nuestro repositorio.
En todos los ejemplos anteriores, siempre interactuamos con el agente base: antigravity-preview-05-2026. Aquí primero crearemos un agente usando la función client.agents.create().
Crear un agente
Así es como podemos crear un agente:
agent = client.agents.create(
id=”data-analyst”,
base_agent="antigravity-preview-05-2026",
base_environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": read_text_file(".agents/AGENTS.md")
},
# Explicitly load the skill
{
"type": "inline",
"target": ".agents/skills/csv-aggregator/SKILL.md",
"content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
},
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}Desglosemos cada parámetro:
-
id: define el nombre del agente, en este casodata-analyst. Usaremos este identificador en el métodoclient.interactions.create()en lugar deantigravity-preview-05-2026, que hemos usado hasta ahora. -
base_agent: el agente que se utilizará como base. Es decir, estamos construyendo un agente encima del agenteantigravity-preview-05-2026. -
base_environment: como antes, permite proporcionar archivos al agente. Hemos incluido dos archivos especiales:.agents/AGENTS.mdy.agents/skills/csv-aggregator/SKILL.md. En ellos definimos el comportamiento del agente. El archivoAGENTS.mddefine el comportamiento general, mientras queSKILL.mddefine una habilidad concreta. También proporcionamos el repositorio para que el agente tenga acceso a los archivos de datos que queremos analizar.
Entender AGENTS.md
Este archivo equivale a un system prompt. Actúa como el manual de instrucciones principal del agente. Debemos usarlo para definir con claridad el rol específico del agente, sus objetivos principales y los límites que debe respetar al trabajar.
También es el mejor lugar para enumerar las herramientas o fuentes de datos a las que el agente puede acceder y para aportar ejemplos de cómo queremos que se comunique o gestione tareas.
Si mantenemos estas instrucciones simples y bien organizadas dentro del archivo, ayudamos al agente a entender exactamente cómo comportarse y qué resultados esperamos.
La ubicación del archivo en el entorno del agente debe ser .agents/AGENTS.md.
Entender SKILL.md
Los archivos de habilidades se usan para dotar al agente de competencias específicas. Un agente puede tener varias habilidades y cada una debe describirse en un archivo SKILL.md ubicado en .agents/skills/<skill_name>/SKILL.md, sustituyendo <skill_name> por el nombre de la habilidad.
La estructura de un archivo de habilidad debe ser:
---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>Para ilustrarlo, hemos dotado al agente data-analyst de una habilidad llamada csv-aggregator, definida aquí. Esta habilidad se usa cuando queremos agrupar filas de un CSV por alguna columna y sumar otra columna.
En el caso del dataset de Netflix, si queremos conocer los géneros con más visualizaciones, agrupamos por Genre y sumamos los valores de la columna Viewership. Este archivo SKILL explica al agente cómo realizar la tarea.
Cargar el agente
Como los agentes son persistentes, si intentamos crear el agente dos veces, obtendremos un error. Por eso creamos la función load_or_create_agent() en el archivo utils.py. Esta función intentará crear el agente y, si ya existe, lo cargará usando client.agents.load().
Juntándolo todo
Ahora que tenemos un agente analista de datos, es hora de probarlo pidiéndole que analice los géneros de Netflix.
Empezamos como antes: importamos librerías, cargamos la API key e inicializamos el cliente:
from dotenv import load_dotenv
from google import genai
import utils
load_dotenv()
client = genai.Client()Luego creamos (o cargamos, si no es la primera vez que ejecutamos el script) el agente data-analyst usando la función utils.load_or_create_agent():
data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")Después, interactuamos con el agente igual que antes. La única diferencia es que en el parámetro agent ahora indicamos nuestro agente en lugar de antigravity-preview-05-2026.
Empezamos pidiéndole que instale el paquete matplotlib:
inter1 = client.interactions.create(
agent=data_analyst.id,
input="Install the matplotlib package.",
environment="remote"
)Como el entorno ya quedó configurado a nivel del agente, no tenemos que aportar archivos de nuevo; basta con indicar la cadena "remote".
A continuación, le pedimos que use la herramienta csv-aggregator para analizar los datos de Netflix por géneros y ver cuáles son los más vistos:
inter2 = client.interactions.create(
agent=data_analyst.id,
input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
environment=inter1.environment_id
)Observa que proporcionamos el identificador del entorno de la interacción anterior para que el agente continúe trabajando sobre él.
Por último, pedimos al agente que dibuje el gráfico ejecutando el script genres.py que se creó en el paso anterior (el archivo SKILL.md instruye al agente para crear este script):
inter3 = client.interactions.create(
agent=data_analyst.id,
input="Execute the genres.py script using python.",
environment=inter2.environment_id
)Tras esta interacción, el gráfico debería haberse generado. Podemos obtenerlo localmente descargando el entorno:
utils.download_env(inter3.environment_id)Este es el resultado:
El código completo de la interacción con el agente está en analyze_netflix_genres.py.
Conclusión
Poder crear agentes complejos con una sola llamada a la API, sin depender de una infraestructura cloud compleja para montar un sandbox, es muy potente. Esta capacidad facilita enormemente crear agentes avanzados sin preocuparse por el entorno donde se ejecutan.
En este tutorial hemos cubierto los fundamentos de los Gemini Managed Agents, pero no hemos creado agentes realmente complejos. Te animo a seguir profundizando y a construir sobre esta base para afianzar tus habilidades.
