Descripción general de la API de Interactions

La API de Interactions proporciona una interfaz unificada y con estado para compilar aplicaciones de IA generativa y flujos de trabajo de agentes con modelos y agentes de Gemini alojados en Gemini Enterprise Agent Platform. Si bien hay una superposición de funciones con la API de generateContent existente, generateContentesta sigue siendo totalmente compatible.

¿Por qué usar la API de Interactions?

La API de Interactions proporciona varias ventajas clave para compilar aplicaciones de IA generativa y flujos de trabajo de agentes:

  • Una sola API para modelos y agentes: Un extremo y un patrón unificados para llamar directamente a los modelos estándar de Gemini, así como a los agentes especializados (como el agente de Deep Research de Gemini y los agentes administrados personalizados).
  • Nuevas capacidades listas para usar: Funciones como el 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 la ejecución en segundo plano para tareas de larga duración con background=true.
  • Dónde se lanzan las funciones nuevas: En el futuro, todos los modelos, las capacidades multimodales , las herramientas y las funciones de agentes nuevos serán compatibles con la API de Interactions.

Cómo funciona la API de Interactions

La API de Interactions se centra en el Interaction recurso. Una Interaction representa un turno completo en una conversación o tarea, y actúa como un registro de sesión que contiene una secuencia cronológica de steps de ejecución:

  • user_input: Los mensajes de entrada, los archivos multimodales o los resultados de las herramientas proporcionados para el turno. Las interacciones almacenadas recuperadas con interactions.get incluyen pasos de user_input para obtener el contexto completo, mientras que las respuestas de interactions.create solo muestran los pasos generados durante ese turno.
  • thought: Resúmenes de razonamiento intermedio generados por el modelo o el agente mientras planifica su respuesta.
  • Pasos de llamada y resultado de la herramienta: Invocaciones de herramientas del cliente o del servidor y salidas (como function_call y function_result).
  • model_output: El texto final, el JSON estructurado o el contenido multimodal producido por el modelo o el agente.

Cuando llamas a interactions.create, Agent Platform procesa tu entrada, ejecuta las herramientas configuradas del servidor o los bucles de agentes, y muestra el recurso Interaction resultante. Para obtener ejemplos de código en Python, TypeScript/JavaScript y REST, consulta la guía para desarrolladores de la API de Interactions.

Modelos compatibles

Los siguientes modelos de Gemini admiten la API de Interactions:

Haz clic para expandir los modelos compatibles

Además de los modelos mencionados anteriormente, la API de Interactions admite los siguientes modelos especializados de generación de audio y multimodal:

  • gemini-omni-flash-preview: Modelo multimodal de alto rendimiento para la generación de video conversacional, la edición y el control cinematográfico.
  • lyria-3-clip-preview y lyria-3-pro-preview: Modelos de música generativa para clips de audio de alta fidelidad y composición de canciones completas (solo compatibles con interacciones sin estado con store=false).

Agentes compatibles

Puedes invocar los siguientes agentes a través de la API de Interactions especificando el parámetro agent en lugar de model:

  • antigravity-preview-05-2026: Agente autónomo de uso general diseñado para el razonamiento de varios pasos, la codificación, las operaciones de archivos y el uso de herramientas.
  • deep-research-preview-04-2026: Agente de Deep Research de Gemini diseñado para la investigación y la síntesis web autónomas de varios pasos.
  • Agentes administrados personalizados implementados en Agent Platform.

Funciones y especificaciones

En las siguientes secciones, se describen las capacidades principales, las especificaciones técnicas y las consideraciones operativas de la API de Interactions.

Administración de estado

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.

Herramientas y fundamentación compatibles

Las siguientes herramientas integradas, proveedores de fundamentación y capacidades de búsqueda son compatibles con los modelos de Gemini 3 en la API de Interactions:

  • Fundamentación con la Búsqueda de Google y Fundamentación web para empresas: Fundamenta las respuestas del modelo con información web en tiempo real de la Búsqueda de Google o la Fundamentación web para empresas.
  • Agent Search y el motor RAG en Gemini Enterprise Agent Platform: Fundamenta las respuestas del modelo en almacenes de datos y repositorios de documentos empresariales privados con Agent Search y el motor RAG.
  • Búsqueda de xAI: Conecta modelos a la búsqueda social en tiempo real y a la fundamentación de conocimiento.
  • Búsqueda paralela: Fundamenta las respuestas del modelo con datos web públicos en tiempo real proporcionados por la API de búsqueda de Parallel Web Systems.
  • Ejecución de código: Permite que el modelo genere y ejecute código de Python en un entorno seguro de zona de pruebas.
  • Llamadas a funciones: Permite que los modelos se conecten a herramientas, APIs y bases de datos externas mostrando argumentos de función estructurados.

La API de Interactions admite la Fundamentación web para empresas y la Fundamentación con la Búsqueda de Google. El uso de estas funciones también está sujeto a sus Condiciones Específicas del Servicio.

Facturación

El uso de la API de Interactions se factura en función del consumo de tokens.

La facturación de las solicitudes interrumpidas o no cumplidas se maneja de la siguiente manera:

  • Cancelaciones manuales: Si se cancela una interacción antes de que se complete (por ejemplo, si se envía una solicitud de cancelación), se te cobrarán los tokens consumidos hasta el momento de la cancelación.
  • Solicitudes fallidas: Si falla una solicitud de interacción debido a un error interno del sistema o a una falla del backend, no se te cobrará por la solicitud fallida.

Seguridad y cumplimiento

Durante la versión preliminar, la API de Interactions tiene las siguientes consideraciones de seguridad, cumplimiento y residencia de datos:

  • Certificaciones de seguridad y cumplimiento: La versión preliminar de la API de Interactions no admite FedRAMP y no cumple con los requisitos del Nivel de Impacto 5 (IL5) del Departamento de Defensa (DoD) ni con el Reglamento Internacional de Tráfico de Armas (ITAR).
  • Claves de encriptación administradas por el cliente (CMEK): La API de Interactions admite CMEK para los datos de interacción almacenados a través de perfiles de servicio (con scope establecido en INTERACTIONS_API) en las multirregiones us y eu.
  • Controles del servicio de VPC: La versión preliminar de la API de Interactions admite los Controles del servicio de VPC (VPC-SC) para proteger el perímetro de tu API.
  • Residencia de datos: La versión preliminar de la API de Interactions no admite la residencia de datos y no asume ningún compromiso para el almacenamiento de sesiones.
  • Extremos: La versión preliminar de la API de Interactions admite el extremo global (locations/global) y los extremos multirregionales us y eu (locations/us y locations/eu) cuando se usa CMEK.

SDKs compatibles

Puedes acceder a la API de Interactions con el SDK unificado de IA generativa de Google o con llamadas directas a REST:

  • Python: google-genai versión 2.3.0 o posterior
  • TypeScript / JavaScript: @google/genai versión 2.3.0 o posterior
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

Los SDKs heredados (google-cloud-aiplatform, @google-cloud/vertexai y google-generativeai) no admiten la API de Interactions.

¿Qué sigue?