Interagir avec les agents

Ce guide explique comment interagir avec les agents déployés dans l'API Managed Agents sur Agent Platform à l'aide de l'API Interactions. Vous apprendrez à interagir avec des agents personnalisés créés à l'aide de l'API Agents et de l'agent de base prédéfini Antigravity, y compris à le configurer de manière dynamique. Elle vous explique également comment gérer et réutiliser les environnements de bac à sable avec des ID d'environnement (env_id) et comment remplacer dynamiquement les configurations, par exemple les serveurs MCP (Model Context Protocol), lors des interactions.

Pour en savoir plus sur l'API, consultez la documentation de référence de l'API Interactions.

Avant de commencer

Avant de commencer à interagir avec les agents, configurez votre environnement :

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  10. Si votre agent utilise des outils MCP (Model Context Protocol) Google Cloud , accordez le rôle Utilisateur d'outils MCP (roles/mcp.toolUser) à votre compte utilisateur et au compte de service associé.

Interagir avec les agents Antigravity

Le moyen le plus simple d'utiliser l'API Managed Agents sur Agent Platform consiste à interagir directement avec l'agent de base Antigravity first party. Vous n'avez pas besoin de créer une ressource d'agent personnalisé. Vous pouvez appeler l'agent à la volée.

Pour lancer une interaction, spécifiez la cible de l'agent de base, telle que antigravity-preview-05-2026 (ou la dernière variante d'aperçu), et demandez un environnement distant à la volée :

REST

Variables de requête

Avant d'appeler l'API, remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement régional de vos interactions. Seule la région global est acceptée.

Méthode HTTP et URL :

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Corps JSON de la requête

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {
    "type": "remote"
  },
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Who are you, can you execute python code? Show me an example."
        }
      ]
    }
  ]
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "antigravity-preview-05-2026",
      "environment": {"type": "remote"},
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Who are you, can you execute python code? Show me an example."
                  }
              ]
          }
      ]
  }'

Exemple de réponse

Après l'interaction initiale, le service renvoie une réponse en streaming. Les interaction.id et environment_id inclus dans les données interaction.complete peuvent être utilisés dans les appels suivants pour maintenir l'état de la session. interaction.id permet de poursuivre l'historique des conversations, tandis que environment_id permet de réutiliser le même environnement de bac à sable. Pour en savoir plus, consultez Gérer l'état de la session.

event: interaction.complete
data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 51132,
      "total_input_tokens": 48984,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 48984
        }
      ],
      "total_output_tokens": 769,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 769
        }
      ],
      "total_thought_tokens": 1379
    },
    "created": "2026-05-15T22:26:05Z",
    "updated": "2026-05-15T22:26:05Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Who are you, can you execute python code? Show me an example.",
    environment={"type": "remote"},
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

La réponse de streaming génère des objets InteractionSSEEvent. L'événement interaction.complete final contient environment_id et l'interaction id, que vous pouvez réutiliser dans les appels suivants pour conserver l'état de la session et l'historique des conversations. Pour en savoir plus, consultez Gérer l'état de la session.

JavaScript

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const stream = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Who are you, can you execute python code? Show me an example.",
    environment: { type: "remote" },
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

La réponse de streaming génère des objets d'événement. L'événement interaction.complete final contient environment_id et l'interaction id, que vous pouvez réutiliser dans les appels suivants pour conserver l'état de la session et l'historique des conversations. Pour en savoir plus, consultez Gérer l'état de la session.

Interagir avec un agent personnalisé créé à l'aide de l'API Agents

Pour interagir avec un agent personnalisé créé comme décrit dans Créer et gérer des agents, vous devez le spécifier à l'aide de son ID d'agent.

Pour savoir comment récupérer ou lister des agents personnalisés afin de trouver leurs ID, consultez Lister les agents.

Configuration et initialisation de l'environnement

Lorsque vous interagissez avec un agent personnalisé :

  • Comportement par défaut : si vous créez l'agent avec un environnement par défaut, spécifiez AGENT_ID dans votre requête.

  • Définissez explicitement l'environnement : si vous n'avez pas défini la configuration de l'environnement lors de la création de l'agent, vous devez le faire explicitement dans le bloc environment de votre demande d'interaction initiale.

    Exemple :

    "environment": {"type": "remote"}

Vous pouvez configurer dynamiquement des fonctionnalités dans l'environnement bac à sable lors de votre appel d'API d'interaction initiale pour répondre à des exigences de tâches spécifiques. Exemple :

  • Associer une compétence à l'aide de Cloud Storage : associez des buckets Cloud Storage pour charger de grands volumes de données ou des répertoires de fichiers persistants dans le système de fichiers du conteneur.

  • Associer des compétences à l'aide du Skill Registry : fournissez une liste d'outils, de scripts ou de compétences d'agent préconfigurés personnalisés pour fournir des fonctionnalités spécifiques ou votre workflow d'exécution. Consultez Skill Registry.

Pour obtenir la liste des structures de configuration d'environnement et des exemples de conservation de l'état des conversations multitours, consultez Gérer l'état des sessions avec des ID d'environnement.

Envoyer une interaction à un agent personnalisé

Envoyez une interaction à votre agent personnalisé en spécifiant son ID :

REST

Variables de requête

Avant d'appeler l'API, remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : seule la région global est acceptée.
  • AGENT_ID : identifiant personnalisé de votre ressource d'agent enregistré. Pour savoir comment récupérer ou lister des agents personnalisés afin de trouver leurs ID, consultez Lister les agents.

Méthode HTTP et URL :

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Corps JSON de la requête

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Tell me the name of python packages used for data analysis."
        }
      ]
    }
  ]
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Tell me the name of python packages used for data analysis."
                  }
              ]
          }
      ]
  }'

Exemple de réponse

Après l'interaction initiale, le service renvoie une réponse en streaming. Les interaction.id et environment_id inclus dans les données interaction.complete peuvent être utilisés dans les appels suivants pour maintenir l'état de la session. interaction.id permet de poursuivre l'historique des conversations, tandis que environment_id permet de réutiliser le même environnement de bac à sable. Pour en savoir plus, consultez Gérer l'état de la session.

data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 7558,
      "total_input_tokens": 6822,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 6822
        }
      ],
      "total_output_tokens": 278,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 278
        }
      ],
      "total_thought_tokens": 458
    },
    "created": "2026-05-15T22:38:56Z",
    "updated": "2026-05-15T22:38:56Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

Python

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Tell me the name of python packages used for data analysis.",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Tell me the name of python packages used for data analysis.",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Gérer l'état de la session et les interactions multitours

Par défaut, les interactions sont sans état, sauf si vous ciblez un conteneur d'environnement ou un historique de conversation spécifiques. Dans les flux d'assistant multitours, vous pouvez conserver les fichiers locaux, le contexte d'exécution du code, les modifications du système, les bibliothèques de logiciels Open Source installées au moment de l'exécution et l'historique des conversations :

  • Pour poursuivre une conversation : transmettez l'ID de l'interaction précédente au paramètre previous_interaction_id.
  • Pour continuer à utiliser un environnement créé : transmettez l'ID d'environnement renvoyé par l'interaction précédente au paramètre environment.

Vous pouvez sélectionner des configurations d'environnement clés à l'aide des paramètres suivants dans le champ environment :

Structure JSON Description
"environment": {"type": "remote"} Provisionne un environnement bac à sable standard et vierge. Utilisez cette option lors des interactions initiales.
"environment": "env_CAEQ..." Réutilise le conteneur sandbox persistant existant, en conservant toutes les bibliothèques, tous les scripts, tous les fichiers et tous les états associés à cet ID d'environnement.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Provisionne un nouveau bac à sable à distance et le précharge avec des compétences ou des fichiers personnalisés à partir des "sources" spécifiées, telles que celles stockées dans Google Cloud Storage.

Pour envoyer une demande d'interaction ultérieure qui réutilise le même conteneur de bac à sable et poursuit une conversation, transmettez le environment_id renvoyé dans le champ environment et spécifiez previous_interaction_id. Les exemples suivants montrent comment poursuivre une session avec état lorsque vous interagissez avec l'agent.

REST

Variables de requête

Avant d'appeler l'API, remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : seule la région global est acceptée.
  • AGENT_ID : identifiant personnalisé de votre ressource d'agent enregistré (ou antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID : ID de l'interaction renvoyé par l'interaction précédente.
  • ENV_ID : ID de l'environnement renvoyé par l'interaction précédente.

Méthode HTTP et URL :

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Corps JSON de la requête

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "environment": "ENV_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "What did I ask you before and what did you do?"
        }
      ]
    }
  ]
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
      "environment": "ENV_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "What did I ask you before and what did you do?"
                  }
              ]
          }
      ]
  }'

Python

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

stream = client.interactions.create(
    agent="AGENT_ID",
    input="What did I ask you before and what did you do?",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    environment="ENV_ID",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

Dans le SDK Python, transmettez la chaîne environment_id directement en tant que paramètre environment pour réutiliser un conteneur sandbox existant. Utilisez previous_interaction_id pour continuer l'historique des conversations.

JavaScript

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "What did I ask you before and what did you do?",
    previous_interaction_id: "PREVIOUS_INTERACTION_ID",
    environment: "ENV_ID",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Dans le SDK JavaScript, transmettez la chaîne environment_id directement en tant que paramètre environment pour réutiliser un conteneur sandbox existant. Utilisez previous_interaction_id pour continuer l'historique des conversations.

Remplacer les configurations lors de l'interaction

Bien que les définitions d'agent personnalisé incluent généralement des configurations par défaut pour les outils, les compétences et les connexions tierces, vous pouvez ajuster dynamiquement ces définitions pour chaque interaction sans modifier la configuration de la ressource d'agent sous-jacente.

Un cas d'utilisation courant consiste à remplacer dynamiquement les connexions aux serveurs MCP (Model Context Protocol) au moment de l'exécution. Tous les outils ou serveurs MCP spécifiés dans le corps de la requête d'interaction remplacent complètement les outils préconfigurés de l'agent pendant la durée de ce tour d'interaction.

Pour remplacer ou définir un serveur MCP au moment de l'interaction, ajoutez un outil de type mcp_server dans la liste tools de votre demande d'interaction :

REST

Variables de requête

Avant d'appeler l'API, remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : emplacement de votre interaction. Seule la région global est acceptée.
  • AGENT_ID : identifiant personnalisé de votre ressource d'agent.
  • MCP_SERVER_URL : URL de la passerelle HTTP distante du nouveau serveur MCP.
  • MCP_SERVER_NAME : libellé descriptif pour le domaine hôte MCP cible.
  • MCP_HEADER_KEY : facultatif. Nom de la clé d'en-tête (par exemple, Authorization).
  • MCP_HEADER_VALUE : facultatif. Valeur des identifiants (par exemple, Bearer <token>).

Méthode HTTP et URL :

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Corps JSON de la requête

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "agents/AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Analyze our database and summarize recent purchase events."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp_server",
      "url": "MCP_SERVER_URL",
      "name": "MCP_SERVER_NAME",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
     "stream": true,
     "background": true,
     "store": true,
     "agent": "agents/AGENT_ID",
     "input": [
         {
             "type": "user_input",
             "content": [
                 {
                     "type": "text",
                     "text": "Analyze our database and summarize recent purchase events."
                 }
             ]
         }
     ],
     "tools": [
         {
             "type": "mcp_server",
             "url": "MCP_SERVER_URL",
             "name": "MCP_SERVER_NAME",
             "headers": {
                 "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
             }
         }
     ]
  }'

Python

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Analyze our database and summarize recent purchase events.",
    tools=[
        {
            "type": "mcp_server",
            "url": "MCP_SERVER_URL",
            "name": "MCP_SERVER_NAME",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

JavaScript

Avant d'exécuter ce code, définissez les variables décrites dans l'onglet REST.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Analyze our database and summarize recent purchase events.",
    tools: [
        {
            type: "mcp_server",
            url: "MCP_SERVER_URL",
            name: "MCP_SERVER_NAME",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Étapes suivantes

Présentation

Découvrez l'API Managed Agents sur Agent Platform, un environnement axé sur la configuration et REST pour créer des agents autonomes.

Référence

Découvrez le conteneur bac à sable isolé, les autorisations et les packages/outils préinstallés.