API de Interactions

La API de Interactions es el nuevo estándar recomendado para compilar con Gemini. Está optimizada para flujos de trabajo de agentes, administración de estados del servidor y conversaciones complejas multimodales y de varios turnos. La API original de generateContent sigue siendo totalmente compatible.

¿Por qué usar la API de Interactions?

  • Administración del historial del servidor: Flujos de varios turnos simplificados a través de previous_interaction_id. El servidor habilita el estado de forma predeterminada (store=true), pero puedes habilitar el comportamiento sin estado si configuras store=false.
  • Pasos de ejecución observables: Los pasos con tipo facilitan la depuración de flujos complejos y la renderización de la IU para eventos intermedios (como pensamientos o widgets de búsqueda).
  • Diseñada para flujos de trabajo de agentes: Compatibilidad nativa para el uso de herramientas de varios pasos, la organización y los flujos de razonamiento complejos a través de pasos de ejecución con tipo.
  • Tareas en segundo plano y de larga duración: Admite la descarga de operaciones que requieren mucho tiempo, como Deep Think y Deep Research, a procesos en segundo plano con background=true.
  • Acceso a nuevos modelos y capacidades: En el futuro, los modelos nuevos más allá de la familia principal, junto con las nuevas capacidades de agente y herramientas, se lanzarán exclusivamente en la API de Interactions.

Usa la API de Interactions si estás comenzando un proyecto nuevo, compilando aplicaciones de agentes o necesitas la administración de conversaciones del servidor. Usa generateContent si tienes una integración existente que funciona para tus necesidades o si necesitas una función que aún no está disponible en la API de Interactions, como la API de Batch o el almacenamiento en caché explícito.

Comenzar

  • Configura tu agente de programación: Conéctate al MCP de Gemini Docs e instala la habilidad gemini-interactions-api para darle a tu asistente acceso directo a la documentación más reciente para desarrolladores y a las prácticas recomendadas. 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.
  • Prueba la guía de inicio rápido: Comienza con un ejemplo de trabajo mínimo en la guía de inicio rápido 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 generateContent y la API de Interactions:

Cómo funciona la API de Interactions

La API de Interactions se centra en un recurso principal: Interaction. Una 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 pensamientos del modelo, llamadas y resultados de herramientas 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 obtener el contexto completo, aunque la respuesta interactions.create solo muestra los pasos generados por el modelo.

Cuando realizas una llamada a interactions.create, estás creando un nuevo recurso Interaction.

Accede a los resultados con las propiedades de conveniencia del SDK

Si bien la API de Interactions muestra una cronología estructurada de los pasos de ejecución (como pensamientos, consultas de búsqueda y llamadas a funciones), no es necesario que recorras los pasos de forma manual para obtener la respuesta final del modelo.

Los SDKs de Google GenAI proporcionan propiedades de conveniencia directamente en el objeto Interaction que se muestra para acceder a los resultados de diferentes modalidades:

Propiedad de conveniencia del SDK Tipo de datos que se muestra Descripción
interaction.output_text String Muestra los últimos bloques de texto en la respuesta del modelo. Si la respuesta se divide en varios bloques TextContent consecutivos, los une automáticamente. No incluye bloques de texto anteriores separados por contenido que no sea de texto (como pensamientos, imágenes, audio o llamadas a herramientas). Para respuestas multimodales complejas o intercaladas, debes iterar manualmente sobre steps.
interaction.output_image ImageContent o None Muestra el último bloque de imágenes generado por el modelo en la solicitud actual.
interaction.output_audio AudioContent o None Muestra el último bloque de audio generado por el modelo en la solicitud actual.

Para casos de uso avanzados, como renderizar procesos de pensamiento intermedios, inspeccionar llamadas a herramientas paso a paso o depurar, puedes inspeccionar y recorrer la cronología interaction.steps sin procesar de forma manual.

Administración de estados del servidor

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

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

  • 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 deseas que se apliquen. Esta administración de estados del servidor es opcional. También puedes operar en modo sin estado enviando el historial de conversaciones 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 retiene las interacciones durante 55 días.
  • Nivel gratuito: El sistema retiene las interacciones durante 1 día.

Si no quieres esto, puedes configurar store=false en tu solicitud. Este control está separado de la administración de estados. Puedes inhabilitar el almacenamiento para cualquier interacción. Sin embargo, ten en cuenta que store=false no es compatible con background=true y evita el uso de previous_interaction_id para los turnos posteriores.

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

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é: El uso de 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 de agentes y modelos dentro de 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 cambiar el formato, y vincular estos pasos con el previous_interaction_id.

Modelos y agentes compatibles

Nombre del modelo Tipo ID de modelo
Gemini 3.5 Flash Modelo gemini-3.5-flash
Gemini 3.1 Flash-Lite Modelo gemini-3.1-flash-lite
Versión preliminar de Gemini 3.1 Pro Modelo gemini-3.1-pro-preview
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
Versión preliminar de Lyria 3 Clip 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-pro-preview-12-2025
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

SDK

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

  • En Python, este es el paquete google-genai de la versión 1.55.0 en adelante.
  • En JavaScript, este es el paquete @google/genai de la versión 1.33.0 en adelante.

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

Limitaciones

  • Estado beta: La API de Interactions está en versión beta o preliminar. Las funciones y los esquemas pueden cambiar.
  • MCP remoto: Gemini 3 no admite 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:

Cambios rotundos

Actualmente, la API de Interactions se encuentra en una etapa beta inicial. Estamos desarrollando y definiendo mejor de forma activa las capacidades de la API, los esquemas de recursos y las interfaces del SDK en función del uso real y los comentarios de los desarrolladores. Como resultado, pueden producirse cambios rotundos.

Cambios rotundos existentes:

  • Esquema de pasos: Un nuevo array de pasos reemplaza el array de resultados, lo que proporciona una cronología estructurada de cada turno de interacción.

Para obtener información sobre el cambio rotundo más reciente y comprender cómo migrar, consulta la Guía de migración de cambios rotundos (mayo de 2026).

Otras actualizaciones potenciales pueden incluir cambios en los esquemas de entrada y salida, las firmas de métodos del SDK y las estructuras de objetos, y los comportamientos de funciones específicas.

Para las cargas de trabajo de producción, debes seguir usando la API estándar de generateContent. Sigue siendo la ruta recomendada para las implementaciones estables, y seguiremos desarrollándola y manteniéndola de forma activa.

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 Google AI.

¿Qué sigue?