Présentation de l'API Interactions

L'API Interactions fournit une interface unifiée avec état pour créer des applications d'IA générative et des workflows agentiques à l'aide de modèles et d'agents Gemini hébergés sur Gemini Enterprise Agent Platform. Bien que certaines fonctionnalités se chevauchent avec l'API generateContent existante, l'API generateContent reste entièrement compatible.

Pourquoi utiliser l'API Interactions ?

L'API Interactions offre plusieurs avantages clés pour la création d'applications d'IA générative et de workflows agentiques :

  • Une seule API pour les modèles et les agents : un point de terminaison et un modèle unifiés pour appeler directement les modèles Gemini standards ainsi que les agents spécialisés (tels que l'agent Gemini Deep Research et les agents gérés personnalisés).
  • Nouvelles fonctionnalités prêtes à l'emploi : fonctionnalités telles que l'état de conversation côté serveur facultatif à l'aide de previous_interaction_id, les étapes d'exécution observables pour le débogage et le rendu de l'UI, et l'exécution en arrière-plan pour les tâches de longue durée à l'aide de background=true.
  • Où les nouvelles fonctionnalités seront-elles lancées ? À l'avenir, tous les nouveaux modèles, outils, fonctionnalités multimodales et fonctionnalités d'agent seront compatibles avec l'API Interactions.

Fonctionnement de l'API Interactions

L'API Interactions est axée sur la ressource Interaction. Un Interaction représente un tour complet dans une conversation ou une tâche et sert d'enregistrement de session contenant une séquence d'exécution chronologique steps :

  • user_input : messages d'entrée, fichiers multimodaux ou résultats d'outils fournis pour le tour. Les interactions stockées récupérées avec interactions.get incluent user_input étapes pour un contexte complet, tandis que les réponses interactions.create ne renvoient que les étapes générées au cours de ce tour.
  • thought : résumés de raisonnement intermédiaires générés par le modèle ou l'agent lors de la planification de sa réponse.
  • Étapes d'appel et de résultat d'outil : appels et sorties d'outils côté client ou côté serveur (comme function_call et function_result).
  • model_output : texte final, contenu JSON structuré ou contenu multimodal produit par le modèle ou l'agent.

Lorsque vous appelez interactions.create, Agent Platform traite votre entrée, exécute tous les outils ou boucles d'agent côté serveur configurés, et renvoie la ressource Interaction résultante.

Modèles compatibles

Les modèles Gemini suivants sont compatibles avec l'API Interactions :

Cliquer pour développer les modèles compatibles

En plus des modèles listés ci-dessus, l'API Interactions est compatible avec les modèles spécialisés de génération multimodale et audio suivants :

  • gemini-omni-flash-preview : modèle multimodal hautes performances pour la génération et le montage de vidéos conversationnelles, et le contrôle cinématographique.
  • lyria-3-clip-preview et lyria-3-pro-preview : modèles de musique générative pour les extraits audio haute fidélité et la composition de chansons complètes (compatibles uniquement avec les interactions sans état avec store=false).

Agents acceptés

Vous pouvez appeler les agents suivants via l'API Interactions en spécifiant le paramètre agent au lieu de model :

  • antigravity-preview-05-2026 : agent autonome à usage général conçu pour le raisonnement en plusieurs étapes, le codage, les opérations sur les fichiers et l'utilisation d'outils.
  • deep-research-preview-04-2026 : Agent Gemini Deep Research conçu pour la recherche et la synthèse Web autonomes en plusieurs étapes.
  • Agents gérés personnalisés déployés sur Agent Platform.

Fonctionnalités et caractéristiques

Les sections suivantes décrivent les principales fonctionnalités, les spécifications techniques et les considérations opérationnelles de l'API Interactions.

Gestion de l'état

Par défaut, l'API Interactions stocke les requêtes afin que vous puissiez exploiter les fonctionnalités de gestion de l'état côté serveur à l'aide de previous_interaction_id. Vous pouvez activer le comportement sans état en définissant store=false.

Outils compatibles et ancrage

Les outils intégrés, les fournisseurs d'ancrage et les fonctionnalités de recherche suivants sont compatibles avec les modèles Gemini 3 dans l'API Interactions :

  • Ancrage avec la recherche Google et Ancrage Web pour Enterprise : ancrent les réponses du modèle avec des informations Web en temps réel issues de la recherche Google ou de l'ancrage Web pour Enterprise.
  • Agent Search et moteur RAG sur Gemini Enterprise Agent Platform : ancrent les réponses du modèle dans des datastores et des dépôts de documents d'entreprise privés à l'aide d'Agent Search et du moteur RAG.
  • xAI Search : associe les modèles à la recherche sociale en temps réel et à l'ancrage des connaissances.
  • Recherche parallèle : ancre les réponses du modèle avec des données Web publiques en temps réel fournies par l'API de recherche de Parallel Web Systems.
  • Exécution de code : permet au modèle de générer et d'exécuter du code Python dans un environnement sécurisé en bac à sable.
  • Appel de fonction : permet aux modèles de se connecter à des outils, des API et des bases de données externes en renvoyant des arguments de fonction structurés.

L'API Interactions prend en charge l'ancrage Web pour Enterprise et l'ancrage avec la Recherche Google. Votre utilisation de ces fonctionnalités est également soumise à leurs Conditions spécifiques au service.

Facturation

L'utilisation de l'API Interactions est facturée en fonction de la consommation de jetons.

La facturation des demandes interrompues ou non traitées est gérée comme suit :

  • Annulations manuelles : si une interaction est annulée avant la fin (par exemple, en envoyant une demande d'annulation), les jetons consommés jusqu'au moment de l'annulation vous sont facturés.
  • Demandes ayant échoué : si une demande d'interaction échoue en raison d'une erreur système interne ou d'une défaillance du backend, elle ne vous est pas facturée.

Sécurité et conformité

Pendant la version bêta, l'API Interactions présente les considérations suivantes en termes de sécurité, de conformité et de résidence des données :

  • Certifications de sécurité et de conformité : l'aperçu de l'API Interactions n'est pas compatible avec FedRAMP ni avec les clés de chiffrement gérées par le client (CMEK). Il n'est pas non plus conforme aux exigences du niveau d'impact 5 (IL5) du ministère de la Défense (DoD) ni à celles de l'International Traffic in Arms Regulations (ITAR).
  • VPC Service Controls : la version preview de l'API Interactions est compatible avec VPC Service Controls (VPC-SC) pour sécuriser votre périmètre d'API.
  • Résidence des données : l'aperçu de l'API Interactions n'est pas compatible avec la résidence des données et ne prend aucun engagement concernant le stockage des sessions.
  • Points de terminaison : l'aperçu de l'API Interactions n'est compatible qu'avec les points de terminaison globaux (locations/global).

SDK compatibles

Vous pouvez accéder à l'API Interactions à l'aide du SDK Google Gen AI unifié ou d'appels REST directs :

  • Python : version google-genai 2.3.0 ou ultérieure
  • TypeScript / JavaScript : @google/genai version 2.3.0 ou ultérieure
  • Aller à : google.golang.org/genai
  • Java : com.google.genai:google-genai

Les anciens SDK (google-cloud-aiplatform, @google-cloud/vertexai et google-generativeai) ne sont pas compatibles avec l'API Interactions.

Étapes suivantes