Créer et gérer des agents

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

Avant de commencer

Avant de configurer vos agents, configurez votre environnement :

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    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

  4. 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 Cloud de Confiance 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 Cloud de Confiance 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 identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    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.
  5. Si vous prévoyez d'utiliser des outils Cloud de Confiance by S3NS MCP (Model Context Protocol) avec votre agent, attribuez le rôle Utilisateur de l'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.

L'agent de base

base_agent est le système d'orchestration de base qui fournit à l'agent des capacités de raisonnement et l'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.

Lors de la création d'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 d'installation 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 Cloud de Confiance by S3NS .
  • 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 :

    • 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 du chemin d'accès au dossier de votre bucket Google Cloud Storage installé (par exemple, gs://cymbal-bucket-name). Remarque : Pour installer 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 application-default 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 des outils propriétaires 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 Cloud de Confiance by S3NS .
  • 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 :

    • 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 application-default 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 protocole HTTP POST standard pour l'affichage 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 via HTTP POST.

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

Autoriser les MCP hébergés par Google

Si vous utilisez un jeton de support pour l'autorisation des serveurs MCP hébergés par Google (comme BigQuery), procédez comme suit :

  1. Ajouter des champs d'application OAuth : ajoutez les champs d'application OAuth 2.0 requis à votre jeton d'authentification. Par exemple, pour utiliser le MCP BigQuery, incluez les champs d'application BigQuery pertinents dans votre requête.
  2. Valider l'accès : vérifiez si le serveur MCP est accessible avec vos nouveaux champs d'application configurés en testant le flux d'autorisation dans OAuth Playground.
  3. Utiliser des en-têtes : pour les MCP Google comme BigQuery, vous devez inclure l'en-tête X-Goog-User-Project défini sur le nom de votre projet dans le mappage headers.

Par exemple, le corps JSON de la requête permettant de créer un agent qui utilise le MCP BigQuery ressemblerait à ceci :

{
  "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 détails dans la section tools :

REST

Variables de requête

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

  • PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
  • 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 :

    • 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 application-default 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 à partir d'un bucket Cloud Storage.

    Nous vous recommandons d'installer les compétences dans le dossier /.agent/skills de l'environnement pour que l'agent puisse les trouver plus facilement.

Compétences CLI

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

Associer une compétence du registre de compétences

Pour charger une compétence réutilisable directement depuis le registre de compétences 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de votre agent. Seule la région global est compatible.
  • AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :
    • 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 compétence ou de la liste de compétences à installer. Vous pouvez spécifier l'un des formats suivants :
    • Compétence (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. Cette option permet d'installer jusqu'à 100 compétences à partir du project/location spécifié dans l'environnement de bac à sable.
    Pour en savoir plus, consultez Lister les compétences.
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 application-default 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: "*" }],
        },
    },
});

Associer une compétence depuis Google Cloud Storage

Vous pouvez également associer des compétences personnalisées directement à partir d'un bucket Cloud Storage lors de la création de l'agent.

Tenez compte des exigences suivantes lorsque vous installez des compétences à partir de Cloud Storage :

  • Exigences d'importation : vous devez importer l'intégralité du dossier de compétences dans le bucket.
  • Aucune validation du contenu : le backend ne valide pas le contenu du dossier avant l'installation. Il se comporte comme une importation 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de votre agent. Seule la région global est compatible.
  • AGENT_ID : identifiant personnalisé unique de votre nouvel agent. Les ID d'agent personnalisés doivent respecter les contraintes suivantes :
    • 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 votre dossier de compétences (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 application-default 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional pour lister les agents. Seule la région global est compatible.
  • PAGE_SIZE : facultatif. Nombre maximal d'agents à renvoyer par page. La valeur par défaut est 10 et la valeur maximale 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 Cloud de Confiance by S3NS .

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

  • AGENT_ID : Identifiant unique de la configuration d'agent personnalisée 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 application-default 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 garantit que seuls les champs que vous souhaitez modifier sont affectés, ce qui préserve 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'agent. Seule la région global est compatible.
  • AGENT_ID : configuration de l'agent cible pour la mise à jour corrective.
  • NEW_INSTRUCTIONS : structure ou description des instructions mises à jour à 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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

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

Pour mettre à jour un agent afin d'activer les outils first party (1P) de Google (comme l'ancrage avec la Recherche Google et le contexte de l'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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'agent. Seule la région global est compatible.
  • 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 application-default 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'agent. Seule la région global est compatible.
  • 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 application-default 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

JavaScript

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 à partir d'un bucket Cloud Storage.

Associer une compétence du 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'agent. Seule la région global est compatible.
  • AGENT_ID : ID de l'agent cible.
  • NEW_SKILL_RESOURCE_NAME : chemin d'accès à la ressource de la compétence ou de la liste de compétences à installer. Vous pouvez spécifier l'un des formats suivants :
    • Compétence (version par défaut) : projects/{projectID}/locations/{location}/skills/{skillName}
    • Version de la compétence (épingler à une version spécifique) : projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (installer toutes les compétences) : projects/{projectID}/locations/{location}/skills. Cela permet d'installer jusqu'à 100 compétences dans le projet/l'emplacement dans l'environnement de bac à sable.
    Pour en savoir plus sur la recherche de la valeur name pour NEW_SKILL_RESOURCE_NAME, consultez Répertorier 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 application-default 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

JavaScript

Associer une compétence depuis Google Cloud Storage

Vous pouvez également associer des compétences personnalisées directement à partir d'un bucket Cloud Storage lors de la création de l'agent.

Tenez compte des exigences suivantes lorsque vous installez des compétences à partir de Cloud Storage :

  • Exigences d'importation : vous devez importer l'intégralité du dossier de compétences dans le bucket.
  • Aucune validation du contenu : le backend ne valide pas le contenu du dossier avant l'installation. Il se comporte comme une importation 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 joindre une compétence depuis Google Cloud Storage :

REST

Variables de requête

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

  • PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'agent. Seule la région global est compatible.
  • AGENT_ID : ID de l'agent cible.
  • NEW_GCS_SOURCE_PATH : chemin d'accès au bucket Google Cloud Storage contenant votre dossier de compétences (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 application-default 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

JavaScript

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. La suppression de l'environnement d'exécution de l'agent invalide son identité d'agent. Toute stratégie d'accès unifié (UAP) IAM qui accorde des autorisations à ce compte principal conserve le compte principal supprimé dans ses règles. De plus, la liaison de stratégie reste active. Pour supprimer un compte principal obsolète, mettez à jour la stratégie d'accès utilisateur afin de supprimer le compte principal de ses règles. Si la stratégie ne contient plus de comptes principaux actifs, supprimez la liaison de stratégie.

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 Cloud de Confiance by S3NS .
  • LOCATION : région de l'agent. Seule la région global est compatible.
  • 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 application-default 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 Cloud de Confiance by S3NS .
  • LOCATION : emplacement régional de l'opération. Seule la région global est compatible.
  • OPERATION_ID : ID d'opération extrait du champ name dans la réponse LRO initiale.

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 application-default print-access-token)"

Python

JavaScript

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 un accès illimité, utilisez *.

Par exemple, l'utilisation de * dans allowlist, comme illustré 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

Découvrez comment interagir avec les agents au moment de l'exécution, gérer l'état de la session et remplacer les configurations de manière dynamique.