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. La API de generateContent sigue siendo totalmente compatible junto con la API de Interactions.

¿Por qué usar la API de Interactions?

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

  • API única para modelos y agentes: Un extremo y un patrón unificados para llamar a los modelos de Gemini estándar y a los agentes especializados directamente (como el agente de Gemini Deep Research y los agentes administrados personalizados).
  • Nuevas funciones 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.

Cómo funciona la API de Interactions

La API de Interactions se centra en el recurso Interaction. Un 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: Son los mensajes de entrada, los archivos multimodales o los resultados de la herramienta proporcionados para el turno. Las interacciones almacenadas que se recuperan con interactions.get incluyen pasos de user_input para obtener el contexto completo, mientras que las respuestas de interactions.create solo devuelven los pasos generados durante ese turno.
  • thought: Son resúmenes de razonamiento intermedios que genera el modelo o el agente a medida que planifica su respuesta.
  • Pasos de llamada a la herramienta y resultado: Invocaciones y resultados de herramientas 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 del servidor o bucle de agente configurados y devuelve el recurso Interaction resultante. Para obtener 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 de Gemini de la lista anterior, la API de Interactions admite los siguientes modelos de música generativa: * 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 (compatibles con interacciones sin estado solo 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: Es un agente autónomo de uso general diseñado para el razonamiento de varios pasos, la programació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 síntesis web autónoma y de varios pasos.
  • Agentes administrados personalizados implementados en Agent Platform.

Funciones y especificaciones

En las siguientes secciones, se describen las funciones 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 las interacciones en el servidor (store=true) durante 7 días para que puedas encadenar conversaciones de varios turnos con previous_interaction_id y ejecutar tareas asíncronas en segundo plano (background=true). Para habilitar la ejecución sin estado y admitir flujos de trabajo de retención de datos cero (ZDR), establece store=false. Para obtener más información, consulta Administra el almacenamiento de sesiones y el estado de las conversaciones.

Límites de solicitudes y multimodales

La API de Interactions aplica los siguientes límites de carga útil de solicitudes y entradas multimodales:

  • Límites de carga útil de la solicitud: La carga útil de la solicitud HTTP comprimida no puede superar los 256 MiB para las solicitudes síncronas y de transmisión de interactions.create. Cuando service_tier se establece en deferred (lo que requiere que background y store sean true), la solicitud sin comprimir no puede superar los 9.75 MiB.
  • Límite de URI para archivos de Cloud Storage: Las solicitudes de interacción del modelo de Gemini estándar admiten hasta 100 URIs de Cloud Storage (gs://) distintas por solicitud, incluidas las URIs que se transfieren de turnos de conversación anteriores a través de previous_interaction_id. Las interacciones de agentes administrados, los modelos de Gemini Omni y los modelos de Lyria 3 se excluyen de este límite de 100 URIs. Para obtener información sobre los permisos y el manejo de URI de varios turnos, consulta Accede a los archivos de Cloud Storage subidos.
  • Límites de elementos y tokens multimodales: Los modelos de Gemini estándar aceptan los mismos recuentos de elementos por modalidad que generateContent (hasta 3,000 imágenes y PDFs combinados, 1,000 archivos de audio, 10 videos y hasta 6,500 archivos multimodales combinados cuando se incluyen archivos de texto sin formato), limitados por la ventana de contexto de 1,048,576 tokens del modelo. Los archivos individuales de Cloud Storage no pueden superar los 2 GiB menos 500 KiB, y las URLs públicas HTTP o HTTPS no pueden superar los 15 MiB. Para enviar más de 100 archivos en una sola solicitud, pasa archivos adjuntos adicionales intercalados dentro del límite de carga útil de la solicitud o llama a generateContent.

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 RAG Engine en Gemini Enterprise Agent Platform: Fundamenta las respuestas del modelo en almacenes de datos empresariales privados y repositorios de documentos con Agent Search y RAG Engine.
  • Búsqueda web de Exa: Fundamenta las respuestas del modelo con los resultados de la búsqueda web de la API de búsqueda de Exa.
  • Búsqueda web de Parallel: Fundamenta las respuestas del modelo con datos web públicos en tiempo real proporcionados por la API de búsqueda de Parallel Web Systems.
  • Contexto de URL: Recupera y analiza el contenido de las URLs web públicas incluidas en tu instrucción.
  • Ejecución de código: Permite que el modelo genere y ejecute código de Python en un entorno seguro de zona de pruebas.
  • Uso de la computadora: Habilita los flujos de trabajo de automatización del navegador y de la interfaz de usuario.
  • Llamada a funciones: Permite que los modelos se conecten a herramientas, APIs y bases de datos externas 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 controla de la siguiente manera:

  • Cancelaciones manuales: Si se cancela una interacción antes de completarse (por ejemplo, enviando una solicitud de cancelación), se te cobrarán los tokens consumidos hasta el momento de la cancelación.
  • Solicitudes con errores: 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 con errores.

Seguridad y cumplimiento

La API de Interactions admite los siguientes controles de seguridad, certificaciones de cumplimiento y parámetros de configuración de extremos:

  • Extremos: La API de Interactions admite el extremo global (locations/global en aiplatform.googleapis.com) y los extremos multirregionales us y eu (locations/us en aiplatform.us.rep.googleapis.com y locations/eu en aiplatform.eu.rep.googleapis.com). No se admiten los extremos de una sola región (como us-central1 o europe-west1).
  • Residencia de datos: La API de Interactions admite la residencia de datos tanto para el procesamiento de AA (en uso) como para los datos de interacción almacenados en reposo (store=true) cuando usas los extremos multirregionales us y eu (locations/us y locations/eu). Las solicitudes enviadas al extremo global no proporcionan garantías de residencia de datos.
  • Claves de encriptación administradas por el cliente (CMEK): La API de Interactions admite CMEK para los datos de interacciones almacenados a través de perfiles de entrega (con scope configurado como INTERACTIONS_API) en las multirregiones us y eu. El extremo global no es compatible con CMEK.
  • Controles del servicio de VPC (VPC-SC): La API de Interactions admite VPC-SC para ayudar a proteger el perímetro de la API y mitigar los riesgos de robo de datos.
  • Transparencia de acceso (AXT): La API de Interactions admite registros de AXT para obtener visibilidad casi en tiempo real cuando el personal de Google accede al contenido de las interacciones almacenado.
  • Certificaciones de seguridad y cumplimiento: La API de Interactions cumple con los requisitos de FedRAMP High dentro del límite de autorización de FedRAMP High de Google Cloud . La API de Interactions 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).

SDKs compatibles

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

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