Gemini Interactions API: qué es y cómo funciona
Gemini Interactions API es la interfaz moderna de Google para trabajar con modelos Gemini y agentes administrados desde un mismo endpoint. Permite generar contenido, utilizar herramientas, mantener conversaciones con estado, ejecutar tareas en segundo plano y llamar agentes como Deep Research o Antigravity mediante una arquitectura unificada.
¿Qué es la Interactions API de Gemini?
Es una API unificada de Google para trabajar tanto con modelos Gemini como con agentes de IA. Puede utilizarse para generación de texto, comprensión multimodal, structured outputs, uso de herramientas, conversaciones de varios turnos, agentes especializados y tareas de larga duración ejecutadas en segundo plano.
Por qué Google creó Interactions API
Los workflows actuales de inteligencia artificial ya no consisten únicamente en enviar un prompt y recibir texto. Los agentes necesitan herramientas, estado, ejecución prolongada y múltiples pasos.
Una sola interfaz
Permite utilizar modelos y agentes mediante un patrón común.
Estado de conversación
Puede conservar contexto entre interacciones sin reenviar todo manualmente.
Agentes
Permite llamar directamente agentes gestionados por Google.
Herramientas
Admite tool orchestration, function calling y herramientas integradas.
Background execution
Las tareas largas pueden continuar ejecutándose sin mantener abierta la conexión.
Pasos observables
Puede exponer pasos de ejecución útiles para depuración e interfaces.
Características clave de Interactions API
Google la posiciona actualmente como la interfaz recomendada para nuevos desarrollos con Gemini.
| Característica | Interactions API |
|---|---|
| Estado | General Availability |
| Disponible GA desde | Junio de 2026 |
| Modelos Gemini | Compatible |
| Agentes administrados | Compatible |
| Conversaciones multi-turn | Compatible |
| Estado server-side | Opcional |
| Streaming | Compatible |
| Background execution | Compatible |
| Structured outputs | Compatible con modelos |
| Tool calling | Compatible |
| Deep Research | Compatible |
| Antigravity | Compatible |
Modelos y agentes utilizan la misma API
Una de las mayores diferencias respecto de APIs anteriores es que ya no necesitas una arquitectura completamente distinta para utilizar un modelo convencional o un agente especializado.
Modelos Gemini
Puedes ejecutar modelos Flash, Pro y otras variantes.
Agentes administrados
También puedes invocar agentes especializados directamente.
Herramientas
Ambos pueden integrarse con herramientas según sus capacidades.
Cómo funciona Gemini Interactions API
Cada solicitud crea una interacción que puede representar desde una respuesta simple hasta un workflow agentic de varios minutos.
Eliges modelo o agente:
puedes indicar un model
o un agent.
Envías el input: proporciona texto, contenido multimodal o instrucciones según el recurso.
Configuras herramientas: puedes añadir herramientas compatibles con el modelo o agente.
Ejecutas: la interacción puede responder inmediatamente o ejecutarse en segundo plano.
Obtienes un Interaction ID: permite recuperar estado o continuar el workflow.
Continúas la conversación: puedes encadenar nuevas interacciones utilizando la anterior como contexto.
La diferencia entre llamar un modelo y un agente
Aunque utilizan la misma API, el comportamiento de un modelo y un agente administrado puede ser muy diferente.
| Aspecto | Model | Agent |
|---|---|---|
| Ejemplo | gemini-3.8-flash | antigravity-preview-05-2026 |
| Generación directa | Sí | No necesariamente |
| Workflow autónomo | Depende de herramientas | Principal |
| Herramientas internas | Según modelo | Según agente |
| Ejecución prolongada | Posible | Frecuente |
| Configuración | generation_config | agent_config |
generation_config
se utiliza cuando llamas un modelo.
agent_config
se utiliza cuando llamas un agente.
Agentes disponibles mediante Interactions API
Google utiliza esta API como punto de acceso común para sus agentes especializados.
Deep Research
Investiga múltiples fuentes, detecta vacíos y genera informes documentados.
Ver guía →Deep Research Max
Variante orientada a investigaciones de máxima exhaustividad.
Ver Deep Research →Antigravity Agent
Agente generalista capaz de ejecutar código, administrar archivos y usar la web.
Ver guía →| Agente | Identificador |
|---|---|
| Deep Research | deep-research-preview-04-2026 |
| Deep Research Max | deep-research-max-preview-04-2026 |
| Antigravity | antigravity-preview-05-2026 |
Conversaciones de varios turnos con previous_interaction_id
Una de las funciones más importantes es continuar una conversación sin reconstruir manualmente todo el historial anterior.
previous_interaction_id
Una nueva interacción puede indicar la interacción anterior para reutilizar su contexto y continuar desde allí.
previous_interaction_id
Google señala que el estado server-side puede mejorar los cache hits y reducir el costo de tokens en conversaciones de varios turnos.
Tareas que continúan aunque cierre la conexión HTTP
Las investigaciones o workflows agentic pueden durar mucho más que una solicitud HTTP convencional.
background=true
Cuando activas este parámetro, Google inicia la interacción y devuelve inmediatamente un ID. La tarea continúa ejecutándose en el servidor.
background=true
Creas la interacción: se inicia el trabajo en background.
Recibes un ID: tu aplicación puede continuar realizando otras tareas.
Consultas el estado: puedes hacer polling hasta que termine.
Recuperas el resultado: cuando la interacción está completa, obtienes su salida final.
Deep Research, razonamiento complejo, análisis prolongados y agentes que ejecutan múltiples herramientas son buenos candidatos para background execution.
Cómo seguir el progreso de una interacción
Una interacción de larga duración puede pasar por diferentes estados antes de producir el resultado final.
in_progress: la tarea todavía está ejecutándose.
completed: la interacción terminó correctamente.
incomplete: puede conservar trabajo y contexto para continuar.
Resultados progresivos y pasos observables
La API puede transmitir información a medida que una interacción avanza, algo especialmente útil para interfaces de agentes.
Texto progresivo
La respuesta puede llegar gradualmente mientras el modelo genera contenido.
Tool calls
La aplicación puede observar cuándo aparecen llamadas a herramientas.
Progreso del agente
Los pasos observables pueden utilizarse en la interfaz de usuario.
Tool orchestration dentro de una interacción
Los modelos compatibles pueden utilizar herramientas según las declaraciones incluidas en la solicitud.
Function calling: conectar Gemini con funciones propias.
Google Search: incorporar información actual de la web.
URL context: utilizar páginas como fuente de contexto.
Code execution: ejecutar código cuando el modelo lo soporte.
MCP: determinados agentes pueden conectarse a herramientas externas.
Cómo controlar el uso de herramientas
La API permite definir el comportamiento del modelo frente a las herramientas disponibles.
| tool_choice | Comportamiento |
|---|---|
| auto | Gemini decide si utiliza una herramienta |
| any | Debe utilizar alguna herramienta |
| none | No puede utilizar herramientas |
| validated | Uso restringido a llamadas válidas |
Interactions API vs generateContent
generateContent continúa funcionando, pero Google recomienda Interactions API para proyectos nuevos.
| Característica | Interactions API | generateContent |
|---|---|---|
| Estado | Recomendado | Legacy pero compatible |
| Modelos | Sí | Sí |
| Managed Agents | Sí | No |
| Estado server-side | Sí | No como arquitectura principal |
| Background execution | Sí | No equivalente |
| Agent workflows | Diseñado para ello | Más limitado |
| Proyectos nuevos | Recomendado | Mantenimiento y compatibilidad |
Google indica que generateContent continúa totalmente soportado. Sin embargo, Interactions API es la interfaz recomendada para nuevos desarrollos.
¿Cuándo conviene utilizar Interactions API?
Puede utilizarse para tareas simples, pero resulta especialmente útil cuando una aplicación necesita capacidades agentic.
Chatbots con estado: conversaciones largas sin reenviar todo el contexto.
Agentes: workflows que utilizan múltiples herramientas.
Deep Research: investigaciones que pueden tardar varios minutos.
Antigravity: tareas que ejecutan código, web y archivos.
Backend asincrónico: procesos que deben continuar aunque el cliente se desconecte.
Interfaces agentic: aplicaciones que muestran pasos y progreso del agente.
Documentación oficial de Interactions API
Google mantiene una guía con modelos, agentes, herramientas, background execution y estado de conversaciones.
Gemini Interactions API
Consulta la documentación antes de implementar nuevas aplicaciones o migrar workflows existentes.
Consultar documentación oficial →Guías relacionadas con Interactions API
Continúa explorando agentes y herramientas que utilizan esta arquitectura.
FAQ sobre Gemini Interactions API
Respuestas breves sobre modelos, agentes, estado y ejecución en background.
Es la API unificada de Google para trabajar con modelos Gemini, herramientas y agentes administrados.
Sí. Google indica que está en General Availability desde junio de 2026.
Es la API recomendada para proyectos nuevos, pero generateContent continúa siendo compatible.
Sí. Puede llamar directamente agentes como Deep Research y Antigravity.
Es el identificador que permite continuar una interacción anterior y reutilizar su contexto en una nueva solicitud.
Permite ejecutar una tarea de larga duración en segundo plano y recuperar su resultado posteriormente.
Sí. Puede transmitir respuestas y progreso de una interacción de forma progresiva.
Continúa con Gemini Antigravity Agent
Interactions API proporciona la infraestructura. Ahora conoce cómo Antigravity utiliza esa arquitectura para ejecutar código, trabajar con archivos y completar tareas autónomas.
Ver Gemini Antigravity Agent →