API de Interactions

La API de Interactions es nuestra nueva interfaz y la forma más sencilla de compilar con modelos y agentes de Gemini. A partir de junio de 2026, estará disponible de forma general y será la interfaz recomendada para todos los proyectos nuevos.

Si bien ahora se considera heredada, la API original de generateContent sigue siendo totalmente compatible.

¿Por qué usar la API de Interactions?

  • Nuevas capacidades listas para usar: Estado de conversación opcional del servidor con previous_interaction_id, pasos de ejecución observables para la depuración y la renderización de la IU, y ejecución en segundo plano para tareas de larga duración con background=true.
  • Menor costo con mayores tasas de aciertos de caché: La administración de estados del servidor permite un almacenamiento en caché de contexto más eficiente en los distintos turnos, lo que reduce los costos de tokens para las conversaciones de varios turnos.
  • Diseñado para modelos y agentes de vanguardia: Creado específicamente para modelos de pensamiento, uso de herramientas de varios pasos y flujos de razonamiento complejos, lo que simplifica el proceso de compilación, depuración y organización de aplicaciones basadas en agentes.
  • Una sola API para modelos y agentes: Una interfaz unificada para llamar a los modelos y agentes de Gemini directamente, como Deep Research y los agentes personalizados administrados, sin necesidad de aprender patrones o endpoints separados.
  • Dónde se lanzarán las novedades: En el futuro, los nuevos modelos y capacidades más allá de la familia principal, junto con las nuevas capacidades de agente y herramientas, se lanzarán en la API de Interactions.

De forma predeterminada, la API de Interactions almacena solicitudes para que puedas aprovechar las funciones de administración de estado del servidor con previous_interaction_id. Puedes habilitar el comportamiento sin estado configurando store=false. Consulta la sección sobre la retención de datos para obtener más información.

Comenzar

  • Configura tu agente de programación: Conéctate al MCP de Gemini Docs y, luego, instala la habilidad gemini-interactions-api para que tu asistente tenga acceso directo a la documentación para desarrolladores y las prácticas recomendadas más recientes. Configura tu agente de programación →
  • Migra desde generateContent: Si tienes una integración existente, sigue la Guía de migración para realizar la transición a la API de Interactions.
  • Comienza a usar la API: Comienza a usar la guía de inicio de la API de Interactions.

Guías de funciones

Explora las capacidades específicas de la API de Interactions a través de estas guías. Puedes usar el botón de activación de estas páginas para alternar entre la API de Interactions y la de generateContent:

Cómo funciona la API de Interactions

La API de Interactions se centra en un recurso principal: Interaction. Un Interaction representa un turno completo en una conversación o tarea. Actúa como un registro de sesión, que contiene todo el historial de una interacción como una secuencia cronológica de pasos de ejecución. Estos pasos incluyen las reflexiones del modelo, las llamadas a herramientas y los resultados del servidor o del cliente (como function_call y function_result), y el model_output final. El recurso almacenado (recuperado a través de interactions.get) también incluye pasos de user_input para el contexto completo, aunque la respuesta de interactions.create solo devuelve los pasos generados por el modelo.

Cuando llamas a interactions.create, creas un nuevo recurso Interaction.

Administración del estado del servidor

Puedes usar el id de una interacción completada en una llamada posterior con el parámetro previous_interaction_id para continuar la conversación. El servidor usa este ID para recuperar el historial de conversación, lo que te evita tener que volver a enviar todo el historial de chat.

El parámetro previous_interaction_id solo conserva el historial de conversaciones (entradas y salidas) con previous_interaction_id. Los demás parámetros son de alcance de la interacción y se aplican solo a la interacción específica que estás generando:

  • tools
  • system_instruction
  • generation_config (incluidos thinking_level, temperature, etcétera)

Esto significa que debes volver a especificar estos parámetros en cada interacción nueva si quieres que se apliquen. Esta administración de estado del servidor es opcional. También puedes operar en modo sin estado enviando el historial de conversación completo en cada solicitud.

Almacenamiento y retención de datos

De forma predeterminada, la API almacena todos los objetos Interaction (store=true) para simplificar el uso de las funciones de administración de estados del servidor (con previous_interaction_id), la ejecución en segundo plano (con background=true) y los fines de observabilidad.

  • Nivel pagado: El sistema conserva las interacciones durante 55 días.
  • Nivel gratuito: El sistema retiene las interacciones durante 1 día.

Si no quieres esto, puedes establecer store=false en tu solicitud. Este control es independiente de la administración del estado. Puedes inhabilitar el almacenamiento para cualquier interacción. Sin embargo, ten en cuenta que store=false no es compatible con la ejecución en segundo plano y evita el uso de previous_interaction_id en turnos posteriores.

Puedes borrar las interacciones almacenadas en cualquier momento con el método de eliminación que se encuentra en la Referencia de la API. Solo puedes borrar interacciones si conoces su ID.

Una vez que venza el período de retención, tus datos se borrarán automáticamente.

El sistema procesa los objetos Interaction según las condiciones.

Prácticas recomendadas

  • Tasa de aciertos de caché: Usar previous_interaction_id para continuar las conversaciones permite que el sistema utilice con mayor facilidad el almacenamiento en caché implícito para el historial de conversaciones, lo que mejora el rendimiento y reduce los costos.
  • Combinación de interacciones: Tienes la flexibilidad de combinar interacciones del agente y del modelo en una conversación. Por ejemplo, puedes usar un agente especializado, como el agente de Deep Research, para la recopilación inicial de datos y, luego, usar un modelo estándar de Gemini para tareas de seguimiento, como resumir o reformatear, y vincular estos pasos con previous_interaction_id.

Modelos y agentes compatibles

Nombre del modelo Tipo ID de modelo
Gemini 3.5 Flash Modelo gemini-3.5-flash
Versión preliminar de Gemini 3.1 Pro Modelo gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite Modelo gemini-3.1-flash-lite
Versión preliminar de Gemini 3 Flash Modelo gemini-3-flash-preview
Gemini 2.5 Pro Modelo gemini-2.5-pro
Gemini 2.5 Flash Modelo gemini-2.5-flash
Gemini 2.5 Flash-lite Modelo gemini-2.5-flash-lite
Gemini 3 Pro Image Modelo gemini-3-pro-image
Gemini 3.1 Flash Image Modelo gemini-3.1-flash-image
Versión preliminar de TTS de Gemini 3.1 Flash Modelo gemini-3.1-flash-tts-preview
Gemma 4 31B IT Modelo gemma-4-31b-it
Gemma 4 26B MoE IT Modelo gemma-4-26b-a4b-it
Vista previa de clip de Lyria 3 Modelo lyria-3-clip-preview
Versión preliminar de Lyria 3 Pro Modelo lyria-3-pro-preview
Versión preliminar de Deep Research Agente deep-research-preview-04-2026
Versión preliminar de Deep Research Agente deep-research-max-preview-04-2026
Vista previa de Antigravity Agente antigravity-preview-05-2026

SDK

Puedes usar la versión más reciente de los SDKs de IA generativa de Google para acceder a la API de Interactions.

  • En Python, este es el paquete google-genai a partir de la versión 2.3.0.
  • En JavaScript, este es el paquete @google/genai a partir de la versión 2.3.0.

Puedes obtener más información para instalar los SDKs en la página Libraries.

Limitaciones

  • MCP remoto: Gemini 3 no admite el MCP remoto. Esta función estará disponible pronto.

La API de generateContent admite las siguientes funciones, pero aún no están disponibles en la API de Interactions:

Comentarios

Tus comentarios son fundamentales para el desarrollo de la API de Interactions. Comparte tus opiniones, informa errores o solicita funciones en nuestro foro de la comunidad de desarrolladores de IA de Google.

¿Qué sigue?