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 Gemini et d'agents hébergés sur Gemini Enterprise Agent Platform. Bien qu'il existe un chevauchement de fonctionnalités avec l'API generateContent existante, cette generateContent dernière reste entièrement compatible.

Pourquoi utiliser l'API Interactions ?

L'API Interactions présente 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 des agents spécialisés (tels que Gemini Deep Research Agent 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'interface utilisateur, et l'exécution en arrière-plan pour les tâches de longue durée à l'aide de background=true.
  • Lancement de nouvelles fonctionnalités : à l'avenir, tous les nouveaux modèles, fonctionnalités multimodales compatibles, outils et fonctionnalités agentiques seront compatibles avec l'API Interactions.

Fonctionnement de l'API Interactions

L'API Interactions est axée sur la Interaction ressource. Un Interaction représente un tour complet dans une conversation ou une tâche et sert d'enregistrement de session contenant une séquence chronologique d'exécution 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 des étapes user_input 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 d'outils côté client ou côté serveur et sorties (tels que function_call et function_result).
  • model_output: texte final, 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 côté serveur ou boucles d'agent configurés, et renvoie la ressource Interaction résultante. Pour obtenir des exemples de code en Python, TypeScript/JavaScript et REST, consultez le guide du développeur de l'API Interactions.

Modèles compatibles

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

Cliquer pour développer les modèles compatibles

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

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

Agents compatibles

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: Gemini Deep Research Agent 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 fonctionnalités de base, 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 tirer parti des 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 et ancrage compatibles

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 les entreprises: ancre les réponses du modèle avec des informations Web en temps réel provenant de la recherche Google ou de l'ancrage Web pour les entreprises.
  • Agent Search et moteur RAG sur Gemini Enterprise Agent Platform : ancre les réponses du modèle par rapport aux datastores et aux dépôts de documents privés de l'entreprise à l'aide d'Agent Search et du moteur RAG.
  • xAI Search : connecte les modèles à la recherche sociale en temps réel et à l'ancrage des connaissances.
  • Parallel Search : 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 est compatible avec l'ancrage Web pour les entreprises 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 requêtes interrompues ou non satisfaites est gérée comme suit :

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

Sécurité et conformité

Pendant la version preview, l'API Interactions présente les considérations suivantes en matière de sécurité, de conformité et de résidence des données :

  • Certifications de sécurité et de conformité : la version preview de l'API Interactions n'est pas compatible avec FedRAMP et n'est pas conforme aux exigences du niveau d'impact 5 (IL5) du ministère de la Défense (DoD) ni aux exigences de l'International Traffic in Arms Regulations (ITAR).
  • Clés de chiffrement gérées par le client (CMEK) : l'API Interactions est compatible avec CMEK pour les données d'interaction stockées via les profils de diffusion (avec scope défini sur INTERACTIONS_API) dans les multirégions us et eu.
  • 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 : la version preview de l'API Interactions n'est pas compatible avec la résidence des données et ne s'engage pas à stocker les sessions.
  • Points de terminaison : la version preview de l'API Interactions est compatible avec le point de terminaison mondial (locations/global), ainsi qu'avec les points de terminaison multirégionaux us et eu (locations/us et locations/eu) lorsque vous utilisez CMEK.

SDK compatibles

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

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

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

Étape suivante