Créer et gérer des agents

Ce produit est une offre de pré-DG, soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service, aux conditions des "Services d'IA agentique" des Conditions spécifiques du service et aux Conditions supplémentaires pour les produits d'IA générative en version preview. Les fonctionnalités et produits pré-DG sont susceptibles de présenter une compatibilité limitée, et les modifications apportées à ces fonctionnalités ou produits peuvent ne pas être compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ces produits en pré-GA sont à différents stades de tests et d'examen internes. Par conséquent, n'utilisez pas de données propriétaires, sensibles ou confidentielles avec ces produits. Ces produits sont mis à la disposition des Clients uniquement à des fins de test et d'évaluation limitées. Ils ne peuvent pas être utilisés à des fins commerciales ou de production.

Pour voir un exemple de création et de gestion d'agents, exécutez le notebook "Introduction to Managed Agents in Python" (Présentation des agents gérés en Python) dans l'un des environnements suivants :

Ouvrir dans Colab | Ouvrir dans Colab Enterprise | Ouvrir dans Agent Platform Workbench | Afficher sur GitHub

Ce guide explique comment créer, récupérer, lister, mettre à jour et supprimer des ressources d'agent personnalisé qui utilisent l'API Managed Agents sur l'Agent Platform, et comment configurer l'environnement de l'agent, les outils du serveur MCP (Model Context Protocol) et les compétences.

Remarque : L'utilisation du modèle pendant la preview est facturée aux tarifs standards. Pour en savoir plus, consultez la page des tarifs.

Avant de commencer

Avant de configurer vos agents, configurez votre environnement :

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.
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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API
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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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.
1. Si vous prévoyez d'utiliser Google Cloud les outils MCP (Model Context Protocol) avec votre agent, accordez le rôle Utilisateur d'outil MCP (roles/mcp.toolUser) à votre compte utilisateur et au compte de service associé.

Créer un agent

Pour créer un agent personnalisé, utilisez la méthode CreateAgent. Il s'agit d'une opération de longue durée.

Remarque : Pendant la période d'aperçu, le provisionnement du premier agent dans votre projet peut prendre entre deux et trois minutes. Les agents suivants sont généralement provisionnés en deux à trois secondes.

L'agent de base

base_agent est le harnais d'orchestration principal qui fournit à l'agent des capacités de raisonnement et un accès à l'environnement d'exécution. Il peut injecter des compétences et des bibliothèques dans l'environnement, et a accès à des outils côté service pour l'exécution de code, les opérations sur le système de fichiers et la recherche avec ancrage.

Lorsque vous créez un agent, une seule valeur est acceptée pour base_agent : antigravity-preview-05-2026.

Créer un agent de base

Pour créer un agent de base avec des outils par défaut et une cible de montage Google Cloud Storage, envoyez une requête POST :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

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

• AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :

  • Il doit comporter entre 1 et 63 caractères.
  • Doit être composé de lettres minuscules, de chiffres et de traits d'union.
  • Doit commencer par une lettre et se terminer par une lettre ou un chiffre.

• BASE_AGENT : nom de l'agent de base à étendre. Utilisez antigravity-preview-05-2026.

• AGENT_DESCRIPTION : bref résumé du champ d'application de l'agent.

• INSTRUCTIONS : instructions système ou persona à définir sur l'agent.

• GCS_BUCKET : segment de chemin d'accès au dossier de votre bucket Google Cloud Storage monté (par exemple, gs://cymbal-bucket-name). Remarque : Pour monter un bucket à partir d'un autre projet, accordez au compte de service du projet l'accès read et write au bucket.

• network : pour des raisons de sécurité, l'accès au réseau dans l'environnement est désactivé. Vous devez spécifier un allowlist pour activer l'accès. L'utilisation de * comme domaine dans allowlist autorise les connexions à tous les domaines, ce qui permet un accès réseau illimité.

Méthode HTTP et URL :

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

Corps JSON de la requête

{
  "id": "AGENT_ID",
  "base_agent": "BASE_AGENT",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Exemple de réponse

{
  "name": "projects/1234567890/locations/global/agents/my-first-agent/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-12T23:50:16.933752Z",
      "updateTime": "2026-05-12T23:50:16.933752Z"
    }
  }
}

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",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    system_instruction="INSTRUCTIONS",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_BUCKET",
                "target": "/.agent",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

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 agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Créer un agent avec les outils propriétaires de Google

Pour créer un agent avec des outils propriétaires Google (comme l'ancrage avec la recherche Google et le contexte d'URL), ajoutez ces outils à la liste tools dans la configuration de l'agent :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

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

• AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :

  • Il doit comporter entre 1 et 63 caractères.
  • Doit être composé de lettres minuscules, de chiffres et de traits d'union.
  • Doit commencer par une lettre et se terminer par une lettre ou un chiffre.

• AGENT_DESCRIPTION : bref résumé du champ d'application de l'agent.

Corps JSON de la requête

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "base_environment": {
    "type": "remote",
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ],
      "base_environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Créer un agent avec des configurations MCP

Vous pouvez créer un agent avec des outils de serveur MCP préconfigurés à l'aide de l'API Managed Agents sur Agent Platform.

Avant de commencer

Avant de créer un agent avec des outils de serveur MCP préconfigurés, procédez comme suit :

• Attribuez le rôle IAM (Identity and Access Management) Utilisateur de l'outil MCP (roles/mcp.toolUser) à votre compte utilisateur et au compte de service associé.

• Vérifiez que les serveurs MCP de votre configuration communiquent via le HTTP POST standard pour les fiches et l'exécution des outils. L'API Managed Agents sur Agent Platform nécessite que les serveurs MCP distants soient des serveurs HTTP diffusables. Les serveurs MCP doivent implémenter le transport HTTP en flux continu MCP, où tools/list et tools/call sont envoyés en tant que JSON-RPC sur HTTP POST.

  Le transport HTTP+SSE à deux points de terminaison obsolète (un flux GET /sse distinct de longue durée) n'est pas pris en charge.

Autoriser les MCP hébergés par Google

Si vous utilisez un jeton du porteur pour autoriser les serveurs MCP hébergés par Google (tels que BigQuery), procédez comme suit :

1. Ajoutez des niveaux d'accès OAuth : ajoutez les niveaux d'accès OAuth 2.0 requis à votre jeton d'authentification. Par exemple, pour utiliser le MCP BigQuery, incluez les portées BigQuery pertinentes dans votre demande.
2. Valider l'accès : vérifiez si le serveur MCP est accessible avec vos nouveaux niveaux configurés en testant le flux d'autorisation dans OAuth Playground.
3. Utiliser les en-têtes : pour les CMP Google tels que BigQuery, vous devez inclure l'en-tête X-Goog-User-Project défini sur le nom de votre projet dans la carte headers.

Par exemple, le corps JSON de la requête utilisé pour créer un agent qui utilise le MCP BigQuery ressemblerait à ce qui suit :

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

Créer l'agent

Pour créer un agent avec des outils de serveur MCP préconfigurés, ajoutez des informations sous la section tools :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

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

• AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :

  • Il doit comporter entre 1 et 63 caractères.
  • Doit être composé de lettres minuscules, de chiffres et de traits d'union.
  • Doit commencer par une lettre et se terminer par une lettre ou un chiffre.

• AGENT_DESCRIPTION : bref résumé du champ d'application de l'agent.

• MCP_SERVER_NAME : nom descriptif de l'outil MCP.

• MCP_SERVER_URL : URL de la passerelle HTTP distante du serveur MCP.

• MCP_HEADER_KEY : facultatif. Nom de l'en-tête pour l'authentification (par exemple, Authorization).

• MCP_HEADER_VALUE : facultatif. Jeton de support d'authentification (par exemple, Bearer <token>).

Corps JSON de la requête

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "mcp_server",
      "name": "MCP_SERVER_NAME",
      "url": "MCP_SERVER_URL",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "mcp_server",
              "name": "MCP_SERVER_NAME",
              "url": "MCP_SERVER_URL",
              "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",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    tools=[
        {
            "type": "mcp_server",
            "name": "MCP_SERVER_NAME",
            "url": "MCP_SERVER_URL",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
)

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 agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    tools: [
        {
            type: "mcp_server",
            name: "MCP_SERVER_NAME",
            url: "MCP_SERVER_URL",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
});

Associer des compétences à un agent

Pour charger une compétence réutilisable directement lors de la création de l'agent, installez-la dans base_environment.sources.

Vous pouvez associer des compétences à l'aide de l'une des méthodes suivantes :

• Registre de compétences : associez une compétence enregistrée dans votre projet dans le Registre de compétences.

• Google Cloud Storage : associez des compétences personnalisées directement depuis un bucket Cloud Storage.

  Nous vous recommandons de monter les compétences sous le dossier /.agent/skills dans l'environnement pour les rendre plus visibles pour l'agent.

Compétences CLI

Les développeurs peuvent également installer des compétences spécialisées dans l'CLI de leur choix pour gérer les agents et les interactions de manière programmatique :

• Skill Agents API
• Skill Interaction API

Associer une compétence depuis le registre de compétences

Pour charger une compétence réutilisable directement depuis le Skill Registry lors de la création de l'agent :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de votre agent. Seule la région global est acceptée.
• AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :
  • Il doit comporter entre 1 et 63 caractères.
  • Doit être composé de lettres minuscules, de chiffres et de traits d'union.
  • Doit commencer par une lettre et se terminer par une lettre ou un chiffre.
• SKILL_RESOURCE_NAME : chemin d'accès à la ressource de la skill ou de la liste de skills à installer. Vous pouvez spécifier l'un des formats suivants :
  • Skill (version par défaut) : projects/{projectID}/locations/{location}/skills/{skillName}
  • Version spécifique : projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
  • Liste des compétences : projects/{projectID}/locations/{location}/skills. Cela permet de monter jusqu'à 100 compétences à partir du project/location spécifié dans l'environnement de bac à sable.
  Pour en savoir plus, consultez list skills.

Corps JSON de la requête

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

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",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "skill_registry",
                "source": "SKILL_RESOURCE_NAME",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

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 agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "skill_registry",
                source: "SKILL_RESOURCE_NAME",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Joindre une compétence depuis Google Cloud Storage

Vous pouvez également associer des compétences personnalisées directement à partir d'un bucket Google Cloud Storage lorsque vous créez l'agent.

Tenez compte des exigences suivantes lorsque vous installez des compétences depuis Cloud Storage :

• Conditions d'importation : vous devez importer l'intégralité du dossier de compétence dans le bucket.
• Aucune validation du contenu : le backend ne valide pas le contenu du dossier avant le montage. Il se comporte comme un import de dossier standard.
• Limites de taille : tous les fichiers joints sont soumis aux limites de mémoire de l'environnement de bac à sable (jusqu'à 4 Gio de RAM au total).
• Bonnes pratiques : Pour une qualité optimale des compétences, structurez et préparez les fichiers de votre dossier de compétences en suivant les conventions décrites sur agentskills.io/home.

Pour associer une compétence depuis Google Cloud Storage lors de la création de l'agent :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de votre agent. Seule la région global est acceptée.
• AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :
  • Il doit comporter entre 1 et 63 caractères.
  • Doit être composé de lettres minuscules, de chiffres et de traits d'union.
  • Doit commencer par une lettre et se terminer par une lettre ou un chiffre.
• GCS_SOURCE_PATH : chemin d'accès au bucket Google Cloud Storage contenant le dossier de votre skill (par exemple, gs://cymbal-bucket-name/my-skill-folder).

Corps JSON de la requête

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_SOURCE_PATH",
                  "target": "./skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

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",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_SOURCE_PATH",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

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 agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_SOURCE_PATH",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Lister des agents

Pour lister tous les agents enregistrés dans votre projet, envoyez une requête GET. Vous pouvez utiliser la pagination facultative pour contrôler le nombre de résultats par page.

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional des agents de fiche. Seule la région global est acceptée.
• PAGE_SIZE : facultatif. Nombre maximal d'agents à renvoyer par page. La valeur par défaut est 10 et la valeur maximale est 100.
• PAGE_TOKEN : facultatif. Jeton de page reçu d'une réponse ListAgents précédente. Fournissez ce jeton pour récupérer la page de résultats suivante.

Lorsque le nombre d'agents à renvoyer est supérieur à PAGE_SIZE, la réponse ListAgents inclut un champ nextPageToken. Pour récupérer la page d'agents suivante, transmettez la valeur de ce nextPageToken en tant que paramètre PAGE_TOKEN dans votre prochaine requête ListAgents. Répétez ce processus jusqu'à ce que le champ nextPageToken ne soit plus renvoyé dans la réponse.

Méthode HTTP et URL :

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Commande curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Exemple de réponse

{
  "agents": [
    {
      "name": "projects/1234567890/locations/global/agents/my-first-agent",
      "id": "my-first-agent",
      "created": "2026-05-12T23:50:16.933Z",
      "updated": "2026-05-12T23:50:21.159Z",
      "systemInstruction": "You are a helpful assistant to user."
    }
  ],
  "nextPageToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ=="
}

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",
)

response = client.agents.list()

for agent in response.agents:
    print(agent)

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 response = await client.agents.list();

if (response.agents) {
    for (const agent of response.agents) {
        console.log(agent);
    }
}

Obtenir un agent

Pour récupérer la configuration complète d'un agent spécifié, utilisez une requête GET.

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .

• LOCATION : emplacement régional de votre agent. Seule la région global est acceptée.

• AGENT_ID : ID unique de la configuration d'agent personnalisé que vous demandez.

Méthode HTTP et URL :

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

Commande curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Exemple de réponse

{
  "name": "projects/vertex-agent-fishfood/locations/global/agents/my-first-agent",
  "id": "my-first-agent",
  "created": "2026-05-12T23:50:16.933Z",
  "updated": "2026-05-12T23:50:21.159Z",
  "systemInstruction": "You are a helpful assistant to user.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "baseEnvironment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-api-sample-skills",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        {"domain": "*"}
      ]
    }
  },
  "baseAgent": "antigravity-preview-05-2026",
  "object": "agent"
}

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",
)

agent = client.agents.get(id="AGENT_ID")
print(agent)

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 agent = await client.agents.get("AGENT_ID");
console.log(agent);

Mettre à jour un agent

Pour mettre à jour la configuration d'un agent existant, envoyez une requête PATCH. Bien que l'ID de l'agent soit immuable, vous pouvez modifier des paramètres tels que les instructions, les outils et les variables d'environnement. Utilisez le paramètre de requête update_mask pour spécifier exactement les champs à mettre à jour. Cela permet de s'assurer que seuls les champs que vous souhaitez modifier sont affectés, tout en préservant les autres configurations.

Mettre à jour un agent de base

Pour mettre à jour les instructions système d'un agent, envoyez une requête PATCH avec update_mask=system_instruction :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'agent. Seule la région global est acceptée.
• AGENT_ID : configuration de l'agent cible à mettre à jour.
• NEW_INSTRUCTIONS : structure ou description des instructions modifiées à remplacer.

Méthode HTTP et URL :

PATCH https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction

Corps JSON de la requête

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

Commande curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

Remarque : La méthode update n'est pas encore disponible dans le SDK Python. Utilisez l'API REST pour mettre à jour les agents.

JavaScript

Remarque : La méthode update n'est pas encore disponible dans le SDK JavaScript. Utilisez l'API REST pour mettre à jour les agents.

Mettre à jour un agent avec des outils propriétaires Google

Pour mettre à jour un agent afin d'activer les outils propriétaires Google (tels que l'ancrage avec la recherche Google et le contexte d'URL), envoyez une requête PATCH avec update_mask=tools :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'agent. Seule la région global est acceptée.
• AGENT_ID : ID de l'agent cible.

Corps JSON de la requête

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

Commande curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

Mettre à jour un agent avec des configurations MCP

Pour modifier les outils MCP associés à votre agent, envoyez une requête PATCH avec update_mask=tools :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'agent. Seule la région global est acceptée.
• AGENT_ID : ID de l'agent cible.
• NEW_MCP_SERVER_NAME : libellé mis à jour de vos outils MCP.
• NEW_MCP_SERVER_URL : nouveau paramètre de point de terminaison d'URL du serveur.
• NEW_MCP_HEADER_KEY : facultatif. Nom de l'en-tête pour l'authentification (par exemple, Authorization).
• NEW_MCP_HEADER_VALUE : facultatif. Jeton de support d'authentification (par exemple, Bearer <token>).

Corps JSON de la requête

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "mcp_server",
      "name": "NEW_MCP_SERVER_NAME",
      "url": "NEW_MCP_SERVER_URL",
      "headers": {
        "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
      }
    }
  ]
}

Commande curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "mcp_server",
              "name": "NEW_MCP_SERVER_NAME",
              "url": "NEW_MCP_SERVER_URL",
              "headers": {
                  "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

Remarque : La méthode update n'est pas encore disponible dans le SDK Python. Utilisez l'API REST pour mettre à jour les agents.

JavaScript

Remarque : La méthode update n'est pas encore disponible dans le SDK JavaScript. Utilisez l'API REST pour mettre à jour les agents.

Associer des compétences à un agent

Pour associer ou modifier des compétences dans base_environment.sources lors de la mise à jour d'un agent, envoyez une requête PATCH à l'aide de update_mask=base_environment.

Vous pouvez associer des compétences à l'aide de l'une des méthodes suivantes :

• Registre de compétences : associez une compétence enregistrée dans votre projet dans le Registre de compétences.

• Google Cloud Storage : associez des compétences personnalisées directement depuis un bucket Cloud Storage.

Associer une compétence depuis le registre de compétences

Pour associer une compétence enregistrée dans le registre de compétences :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'agent. Seule la région global est acceptée.
• AGENT_ID : ID de l'agent cible.
• NEW_SKILL_RESOURCE_NAME : chemin d'accès à la ressource de la skill ou liste des skills à installer. Vous pouvez spécifier l'un des formats suivants :
  • Skill (version par défaut) : projects/{projectID}/locations/{location}/skills/{skillName}
  • Version de la skill (épingler à une version spécifique) : projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
  • ListSkills (Monter toutes les compétences) : projects/{projectID}/locations/{location}/skills. Cette commande permet de monter jusqu'à 100 skills dans le projet/lieu dans l'environnement de bac à sable.
  Pour savoir comment trouver la valeur name pour NEW_SKILL_RESOURCE_NAME, consultez Lister les compétences.

Corps JSON de la requête

{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "NEW_SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

Remarque : La méthode update n'est pas encore disponible dans le SDK Python. Utilisez l'API REST pour mettre à jour les compétences des agents.

JavaScript

Remarque : La méthode update n'est pas encore disponible dans le SDK JavaScript. Utilisez l'API REST pour mettre à jour les compétences des agents.

Joindre une compétence depuis Google Cloud Storage

Vous pouvez également associer des compétences personnalisées directement à partir d'un bucket Google Cloud Storage lorsque vous créez l'agent.

Tenez compte des exigences suivantes lorsque vous installez des compétences depuis Cloud Storage :

• Conditions d'importation : vous devez importer l'intégralité du dossier de compétence dans le bucket.
• Aucune validation du contenu : le backend ne valide pas le contenu du dossier avant le montage. Il se comporte comme un import de dossier standard.
• Limites de taille : tous les fichiers joints sont soumis aux limites de mémoire de l'environnement de bac à sable (jusqu'à 4 Gio de RAM au total).
• Bonnes pratiques : Pour une qualité optimale des compétences, structurez et préparez les fichiers de votre dossier de compétences en suivant les conventions décrites sur agentskills.io/home.

Pour associer une skill depuis Google Cloud Storage :

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'agent. Seule la région global est acceptée.
• AGENT_ID : ID de l'agent cible.
• NEW_GCS_SOURCE_PATH : chemin d'accès au bucket Google Cloud Storage contenant le dossier de votre skill (par exemple, gs://cymbal-bucket-name/my-skill-folder).

Corps JSON de la requête

{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Commande curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "NEW_GCS_SOURCE_PATH",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

Remarque : La méthode update n'est pas encore disponible dans le SDK Python. Utilisez l'API REST pour mettre à jour les compétences des agents.

JavaScript

Remarque : La méthode update n'est pas encore disponible dans le SDK JavaScript. Utilisez l'API REST pour mettre à jour les compétences des agents.

Supprimer un agent

Pour supprimer une configuration d'agent personnalisée spécifique, envoyez une requête DELETE. Il s'agit d'une opération de longue durée qui supprime définitivement la configuration.

Lorsque vous supprimez un agent, fournissez toutes les informations nécessaires dans l'URL et n'incluez pas de corps de requête JSON.

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : région de l'agent. Seule la région global est acceptée.
• AGENT_ID : ID de l'agent que vous supprimez.

Méthode HTTP et URL :

DELETE https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

Commande curl

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Exemple de réponse

{
  "name": "projects/1234567890/locations/global/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-13T02:15:45.936287Z",
      "updateTime": "2026-05-13T02:15:45.936287Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

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",
)

response = client.agents.delete(id="AGENT_ID")
print(response)

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 response = await client.agents.delete("AGENT_ID");
console.log(response);

Obtenir les détails d'une opération de longue durée

Les opérations telles que CreateAgent, UpdateAgent et DeleteAgent sont asynchrones. La réponse initiale de l'API renvoie un champ name contenant l'ID de l'opération. Utilisez GetOperation sur cet ID pour interroger la progression.

REST

Variables de requête

Avant d'appeler l'API, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement régional de l'opération. Seule la région global est acceptée.
• OPERATION_ID : ID de l'opération extrait du champ name de la réponse initiale de l'opération de longue durée.

Méthode HTTP et URL :

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

Commande curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Python

Remarque : Lorsque vous utilisez le SDK Python, les opérations telles que agents.create() et agents.delete() renvoient directement le résultat final. Utilisez client.agents.get(id="AGENT_ID") pour vérifier l'état du provisionnement.

JavaScript

Remarque : Lorsque vous utilisez le SDK JavaScript, les opérations telles que agents.create() et agents.delete() renvoient directement le résultat final. Utilisez client.agents.get("AGENT_ID") pour vérifier l'état du provisionnement.

Configurer l'accès au réseau

Par défaut, le bac à sable désactive l'accès au réseau lorsque vous créez des agents à l'aide de l'API Agents. Pour autoriser l'accès sans restriction, utilisez *.

Par exemple, l'utilisation de * dans allowlist, comme indiqué dans le code suivant, donne accès à tous les domaines :

"base_environment": {
    "type": "remote",
    "sources": [
        {
            "type": "skill_registry",
            "source": "SKILL_RESOURCE_NAME",
            "target": "./skills"
        }
    ],
    "network": {
        "allowlist": [{"domain": "*"}]
    }
}

Étapes suivantes

Guide

Interagir avec les agents

Découvrez comment interagir avec les agents au moment de l'exécution, gérer l'état des sessions et remplacer dynamiquement les configurations.