Descripción general de la API de Interactions

La API de Interactions proporciona una interfaz unificada y con estado para crear aplicaciones de IA generativa y flujos de trabajo basados en agentes con modelos y agentes de Gemini alojados en Gemini Enterprise Agent Platform. Si bien hay superposición de funciones con la API de generateContent existente, la API de generateContent 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 a los modelos estándar de Gemini y a los agentes especializados directamente (como el agente de Deep Research de Gemini y los agentes personalizados administrados).
  • 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 lanzarán las nuevas funciones: En el futuro, todos los modelos, las capacidades multimodales, las herramientas y las funciones basadas en agentes nuevos se admitirán en la API de Interactions.

Cómo funciona la API de Interactions

La API de Interactions se centra en el recurso Interaction. Un objeto 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 ejecución de steps:

  • user_input: Son los mensajes de entrada, los archivos multimodales o los resultados de herramientas proporcionados para el turno. Las interacciones almacenadas que se recuperan con interactions.get incluyen pasos de user_input para brindar un contexto completo, mientras que las respuestas de interactions.create solo devuelven los pasos generados durante ese turno.
  • thought: Son los resúmenes de razonamiento intermedio que genera el modelo o el agente a medida que planifica su respuesta.
  • Pasos de llamada y resultado de la herramienta: Invocaciones y resultados de la herramienta del cliente o del servidor (como function_call y function_result).
  • model_output: Es el texto final, el JSON estructurado o el contenido multimodal que produce el modelo o el agente.

Cuando llamas a interactions.create, Agent Platform procesa tu entrada, ejecuta cualquier herramienta o bucle de agente configurado del servidor y devuelve el recurso Interaction resultante. Para ver muestras 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 multimodales:

  • gemini-omni-flash-preview: Modelo multimodal de alto rendimiento para la generación, edición y control cinemático de videos conversacionales.
  • 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 se admiten en interacciones sin estado con store=false).

Agentes admitidos

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: Es un agente autónomo de uso general diseñado para el razonamiento de varios pasos, la codificación, las operaciones con archivos y el uso de herramientas.
  • deep-research-preview-04-2026: Agente 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 estados 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: Fundamentan las respuestas del modelo en los almacenes de datos y repositorios de documentos empresariales privados con Agent Search y el motor RAG.
  • xAI Search: Conecta los modelos a la búsqueda social en tiempo real y a la fundamentación del 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: Permiten que los modelos se conecten a herramientas, APIs y bases de datos externos devolviendo argumentos de funciones estructurados.

La API de Interactions admite la fundamentación web para empresas y la fundamentación con la Búsqueda de Google. El uso que hagas 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 completadas 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 una solicitud de interacción falla 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 ni claves de encriptación administradas por el cliente (CMEK), y no cumple con los requisitos del nivel de impacto 5 (IL5) del Departamento de Defensa (DoD) ni con los de la Reglamentación Internacional sobre Tráfico de Armas (ITAR).
  • 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 se compromete con el almacenamiento de sesiones.
  • Endpoints: La versión preliminar de la API de Interactions solo admite extremos globales (locations/global).

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: Versión google-genai 2.3.0 o posterior
  • TypeScript / JavaScript: Versión @google/genai 2.3.0 o posterior
  • Ir: 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?