Creación de agentes gestionados con la API de Gemini: una guía completa para desarrolladores

Los agentes autónomos que razonan, escriben y ejecutan código, navegan por la web y gestionan archivos solían requerir semanas de trabajo de infraestructura. Con el lanzamiento de Agentes Gestionados en la API de Gemini, Google ha condensado esa configuración en una sola llamada a la API. Una solicitud pone en marcha un sandbox Linux seguro y efímero alojado por Google, y un agente listo para hacer trabajo real dentro de él.

Esta guía cubre todo lo que los desarrolladores necesitan saber: cómo funciona el agente Antigravity, cómo crear y desplegar agentes personalizados, cómo bifurcar entornos para ejecuciones reproducibles, cómo bloquear la red y las credenciales, y cómo la nueva CLI de Gemini encaja en un flujo de trabajo centrado en agentes.

¿Qué son los Agentes Gestionados de la API de Gemini?

Los Agentes Gestionados son el nuevo primitivo para desarrolladores de Google para agentes de IA autónomos en la API de Gemini. En lugar de ensamblar por tu cuenta la lógica de orquestación, los entornos de ejecución de código, la infraestructura de llamada a herramientas y los controles de seguridad, la API se encarga de todo.

Una sola llamada a la API de Interacciones aprovisiona un entorno Linux aislado, inicia un agente impulsado por Gemini y ejecuta tu tarea de principio a fin. El agente puede razonar y planificar, llamar herramientas, ejecutar código, gestionar archivos y navegar por la web, todo dentro de un runtime seguro que Google administra por ti.

Dos superficies hacen esto posible:

• La API de Interacciones: la interfaz de runtime. Envía una tarea y recibe un agente que razona y actúa.
• La API de Agentes: el plano de control. Define, registra y gestiona agentes con nombre con instrucciones, herramientas, habilidades y configuraciones de entorno personalizadas.

El agente Antigravity: un agente de propósito general listo para usar

El primer agente gestionado de propósito general en la API de Gemini es Antigravity. Está impulsado por Gemini 3.5 Flash y se ejecuta sobre el mismo armazón que hay detrás del IDE Antigravity y otros productos de agentes de primera parte de Google. Antes de Antigravity, Deep Research era el único agente gestionado disponible: un agente especializado para flujos de trabajo de investigación de varios pasos.

Antigravity es su contraparte de propósito general: una sola llamada a la API que aprovisiona un entorno Linux remoto y se pone a trabajar.

Qué puede hacer Antigravity

Dentro de su sandbox gestionado, el agente Antigravity puede:

• Razonar y planificar usando el armazón de agente de Gemini
• Ejecutar código y gestionar archivos en un entorno Linux seguro
• Navegar por la web para obtener y procesar datos en tiempo real
• Usar herramientas como búsqueda web, ejecución de código y E/S de archivos

Tu primera llamada a la API de Antigravity

Aquí tienes la invocación más simple posible de Antigravity: una sola llamada a la API que aprovisiona un entorno remoto, ejecuta el agente y devuelve la salida:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

Eso es todo. Sin configuración de contenedores. Sin código de sandboxing. Sin andamiaje para llamadas a herramientas. Google se encarga de todo.

Entornos persistentes: agentes con estado y de varios turnos

Los entornos persisten entre llamadas. La primera interacción aprovisiona un sandbox y devuelve un environment_id. Pasa ese ID en solicitudes posteriores y el agente reanuda con todos los archivos, paquetes y estado exactamente como quedó en la llamada anterior.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

Este carácter con estado es lo que hace prácticos los flujos de trabajo de varios pasos. Un agente que instala paquetes, escribe archivos y ejecuta análisis en una llamada puede pasar todo eso sin problemas a la siguiente llamada: sin reconfiguración, sin volver a descargar, sin volver a ejecutar.

Los entornos también aceptan datos externos al inicio: repositorios Git, objetos de Google Cloud Storage o contenido en línea pueden montarse en el sandbox antes de que el agente empiece a trabajar.

Creación de agentes gestionados personalizados

El agente Antigravity cubre bien las tareas de propósito general. Pero los casos de uso en producción casi siempre necesitan comportamiento personalizado: instrucciones específicas, habilidades de dominio, herramientas propietarias o fuentes de datos curadas. Para eso sirve la API de Agentes.

Los Agentes Gestionados de Gemini te permiten agrupar instrucciones, habilidades, herramientas y un entorno en un agente con nombre al que invocas por ID. En lugar de escribir código complejo de orquestación, defines todo de forma declarativa —en archivos markdown como AGENTS.md y SKILL.md— y lo registras una sola vez.

Definir un agente a partir de fuentes

Crea un agente desde cero especificando instrucciones del sistema y fuentes. Las fuentes pueden ser repositorios de GitHub, rutas de Google Cloud Storage o contenido en línea. La plataforma aprovisiona un sandbox nuevo con tus archivos en cada invocación.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Una vez registrado, data-analyst es un agente duradero al que puedes invocar por nombre. Cada ejecución aprovisiona un entorno limpio con tu configuración exacta: sin fugas de estado entre invocaciones.

Bifurcar un entorno existente

A veces, la ruta más rápida hacia un agente personalizado es iterar. Empieza trabajando de forma interactiva con el agente Antigravity base: instala paquetes, crea plantillas, configura el entorno y luego bifurca esa instantánea del entorno en un agente con nombre reutilizable.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Una vez guardado, cada invocación posterior de my-data-analyst se bifurca desde esa instantánea base, empezando desde un estado limpio y preconfigurado cada vez.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

El patrón de bifurcar y registrar es especialmente eficaz para agentes que dependen de una configuración pesada: grafos de dependencias complejos, artefactos de modelo grandes o plantillas precompiladas que tardarían demasiado en reconstruirse en cada invocación.

Red segura y proxy de credenciales

Los agentes de producción casi siempre necesitan acceder a servicios externos —GitHub, APIs internas, registros de paquetes— y casi siempre necesitan hacerlo sin exponer credenciales sensibles dentro del sandbox. Los Agentes Gestionados manejan ambas cosas con un proxy de salida configurable.

La configuración de red cumple dos propósitos:

1. Las listas de अनुमति (allowlist) restringen las conexiones salientes a dominios explícitamente permitidos, evitando que un agente llegue a servicios externos no deseados.
2. Las transformaciones de encabezados inyectan credenciales del lado del servidor, de modo que los tokens de API y secretos nunca se pasan al propio entorno del sandbox.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

En esta configuración, el agente solo puede الوصول a api.github.com y pypi.org. Cualquier intento de conectarse a otro dominio se bloquea. Las solicitudes a GitHub se transforman automáticamente para incluir el encabezado Authorization; el código del sandbox nunca ve el token directamente.

Esta arquitectura es esencial para agentes desplegados frente a repositorios de código internos, APIs propietarias o cualquier entorno en el que el manejo correcto de credenciales sea un requisito de cumplimiento.

La CLI de Gemini API: una experiencia de desarrollo centrada en agentes

Junto con la API, Google lanzó una CLI de Gemini API experimental y de código abierto, diseñada para que los agentes de programación interactúen con la API de Gemini de una forma estructurada y compatible con agentes.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

El flujo de trabajo agents init / agents test / agents create refleja un cambio en la forma en que Google espera que los desarrolladores construyan sobre la API de Gemini: definir el comportamiento del agente en archivos, probarlo localmente y desplegarlo como un agente gestionado con nombre, el mismo patrón que resulta familiar en las herramientas de infraestructura como código.

Herramientas complementarias

Más allá de la CLI, dos añadidos mantienen a los agentes de programación al día con la API de Gemini:

• Servidor MCP de Gemini API Docs — proporciona acceso en tiempo real a la documentación de Gemini, SDKs e información de modelos a través de MCP. Los agentes de programación pueden consultar la documentación directamente en lugar de depender de datos de entrenamiento obsoletos.
• Habilidad gemini-interactions-api — inyecta automáticamente patrones y buenas prácticas de la API de Interacciones en el contexto de un agente, de modo que los agentes creados con Agentes Gestionados de Gemini escriben código de interacción idiomático desde el principio.

Por qué los Agentes Gestionados importan para casos de uso en producción

La apuesta central detrás de los Agentes Gestionados es que la mayor parte del trabajo duro en el desarrollo de agentes no es el modelo, sino la infraestructura que lo rodea. El sandboxing, la integración de herramientas, la gestión de credenciales, la reproducibilidad de entornos y la seguridad de red son problemas que cada equipo que lanza agentes tiene que resolver por separado. Los Agentes Gestionados hacen que esos problemas pasen a ser de Google.

Ese cambio tiene implicaciones prácticas para los despliegues en producción:

Ejecuciones reproducibles. Los entornos bifurcados garantizan que cada invocación del agente empiece desde una base idéntica: sin deriva de dependencias y sin contaminación de estado entre ejecuciones.

Menor superficie de ataque. Las credenciales nunca entran en el sandbox. La salida de red está restringida por allowlist. El entorno de ejecución es efímero y aislado. Estos no son pasos de endurecimiento opcionales; son el comportamiento predeterminado.

Iteración más rápida. El flujo de trabajo de bifurcar y registrar permite a los equipos experimentar de forma interactiva, estabilizar una configuración y promoverla a un agente con nombre, sin reescribir la infraestructura entre el prototipo y la producción.

Compatibilidad con frameworks. Los Agentes Gestionados funcionan con los frameworks de orquestación que los equipos ya usan. Entre los socios de lanzamiento están Vercel AI SDK, LiteLLM, Agno, Eigent y LlamaIndex, así que los flujos de trabajo existentes no requieren una reescritura completa para aprovechar la infraestructura gestionada.

Agentes Gestionados para empresas

Para las empresas que necesitan ejecutar agentes gestionados personalizados a escala, Google ofrece la Plataforma de Agentes Empresariales de Gemini: las mismas APIs, con gobernanza adicional, visibilidad centralizada y controles de políticas a nivel organizacional.

Los Agentes Gestionados en la API de Gemini están disponibles actualmente en vista previa. Los equipos empresariales pueden acceder a los mismos primitivos de agente gestionado a través de la Plataforma de Agentes Empresariales, con controles adicionales para auditoría, aplicación de DLP y gobernanza multi-equipo.

Conclusiones clave

El lanzamiento de Agentes Gestionados de la API de Gemini ofrece a los desarrolladores tres cosas que antes eran difíciles de conseguir juntas: un agente generalista capaz (Antigravity) listo para usar desde el primer momento, una API limpia para definir y desplegar agentes personalizados con seguridad de nivel de producción, y una experiencia para desarrolladores —CLI, servidor MCP, Skills— diseñada para que los agentes creen agentes.

Las decisiones de infraestructura son acertadas: entornos persistentes, bifurcación de entornos, allowlists de salida e inyección de credenciales del lado del servidor son los primitivos adecuados para despliegues de agentes en producción. La CLI de código abierto y la Skill reflejan el reconocimiento de Google de que la experiencia de desarrollo para agentes es tan importante como las capacidades del modelo subyacente.

Para los equipos que construyen sobre la plataforma agnóstica de modelos de Eigent, los Agentes Gestionados de Gemini representan un destino de despliegue convincente, que encaja bien con la capacidad de Eigent para enrutar tareas de forma inteligente entre proveedores de modelos mientras Google gestiona la capa de ejecución aislada.

Para empezar, prueba el agente Antigravity en el AI Studio Playground, lee la documentación de Agentes Gestionados e instala el SDK de Python o el SDK de JavaScript.

Preguntas frecuentes

¿Qué son los Agentes Gestionados de la API de Gemini?

Los Agentes Gestionados de la API de Gemini son agentes autónomos de IA que se ejecutan dentro de entornos Linux aislados alojados por Google. Una sola llamada a la API de Interacciones aprovisiona el sandbox, inicia un agente impulsado por Gemini y ejecuta tu tarea —incluyendo ejecución de código, navegación web y gestión de archivos— sin necesidad de que configures ninguna infraestructura.

¿Qué es el agente Antigravity?

Antigravity es el agente gestionado de propósito general de Google en la API de Gemini, impulsado por Gemini 3.5 Flash. Puede razonar y planificar, ejecutar código, gestionar archivos y navegar por la web dentro de un entorno Linux remoto seguro. Usa el mismo armazón de agente que impulsa el IDE Antigravity y otros productos de agentes de primera parte de Google.

¿Cómo funcionan los entornos persistentes?

La primera llamada de interacción con environment="remote" aprovisiona un nuevo sandbox y devuelve un environment_id. Pasar ese ID en llamadas posteriores reanuda el agente en el mismo entorno, con todos los archivos, paquetes instalados y estado preservados. Esto permite flujos de trabajo con estado y de varios turnos sin reconfiguración entre llamadas.

¿Cómo creo un agente gestionado personalizado?

Usa la API de Agentes para definir un agente con nombre especificando un agente base, instrucciones y fuentes (repositorios de GitHub, objetos de GCS o contenido en línea). Una vez registrado, invoca tu agente por nombre a través de la API de Interacciones. Como alternativa, itera de forma interactiva con Antigravity y luego bifurca el entorno resultante en un agente con nombre usando client.agents.create() con un base_environment que apunte a un environment_id existente.

¿Cómo funciona el proxy de credenciales?

El proxy de salida del agente gestionado se sitúa entre el sandbox e internet. Configuras un allowlist de dominios permitidos y, opcionalmente, reglas de transform de encabezados por dominio. El proxy inyecta automáticamente encabezados (como Authorization: Bearer <token>) en las solicitudes salientes coincidentes, de modo que el código del sandbox nunca tenga acceso directo a los valores de los tokens.

¿Qué frameworks son compatibles con los Agentes Gestionados de Gemini?

Los Agentes Gestionados de Gemini funcionan de fábrica con Vercel AI SDK, LiteLLM, Agno, Eigent y LlamaIndex en el lanzamiento. La API de Interacciones está basada en REST, así que cualquier framework de orquestación capaz de usar HTTP puede integrarse con ella.

¿Qué es la CLI de Gemini API?

La CLI de Gemini API es una herramienta experimental de código abierto diseñada para que los agentes de programación interactúen con la API de Gemini. Permite ejecutar prompts, generar imágenes y audio, y gestionar el ciclo de vida completo de los agentes gestionados —init, test, create y run— desde la línea de comandos.

¿Los Agentes Gestionados de Gemini están disponibles para uso empresarial?

Sí. Las mismas APIs de Agentes Gestionados están disponibles a través de la Plataforma de Agentes Empresariales de Gemini, con controles adicionales de gobernanza, visibilidad centralizada, aplicación de DLP y gestión de políticas organizativas. Los Agentes Gestionados en la API de Gemini están disponibles actualmente en vista previa.