Creazione e gestione degli agenti

Questa guida spiega come creare, recuperare, elencare, aggiornare ed eliminare risorse di agenti personalizzati che utilizzano l'API Managed Agents su Agent Platform e come configurare l'ambiente dell'agente, gli strumenti del server Model Context Protocol (MCP) e le competenze.

Prima di iniziare

Prima di configurare gli agenti, configura l'ambiente:

  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. Se prevedi di utilizzare gli strumenti Cloud de Confiance by S3NS Model Context Protocol (MCP) con il tuo agente, concedi il ruolo MCP Tool User (roles/mcp.toolUser) sia al tuo account utente sia al account di servizio associato.

Crea un agente

Per creare un nuovo agente personalizzato, utilizza il metodo CreateAgent. Si tratta di un'operazione a lunga esecuzione.

L'agente di base

base_agent è l'imbracatura di orchestrazione principale che fornisce all'agente funzionalità di ragionamento e accesso all'ambiente di esecuzione. Può inserire competenze e librerie nell'ambiente e ha accesso a strumenti lato servizio per l'esecuzione di codice, le operazioni sul file system e la ricerca con grounding.

Quando crei un agente, è supportato un solo valore per base_agent: antigravity-preview-05-2026.

Crea un agente di base

Per creare un agente di base con strumenti predefiniti e un target di montaggio di Google Cloud Storage, invia una richiesta POST:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.

  • AGENT_ID: l'identificatore personalizzato univoco per il nuovo agente. Gli ID agente personalizzati devono rispettare i seguenti vincoli:

    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.

  • BASE_AGENT: il nome dell'agente di base da estendere. Utilizza antigravity-preview-05-2026.

  • AGENT_DESCRIPTION: un breve riepilogo dell'ambito dell'agente.

  • INSTRUCTIONS: istruzioni di sistema o persona da impostare sull'agente.

  • GCS_BUCKET: il segmento del percorso della cartella del bucket Cloud Storage montato (ad esempio, gs://cymbal-bucket-name). Nota: per montare un bucket da un progetto diverso, concedi al account di servizio del progetto l'accesso read e write al bucket.

  • network: per motivi di sicurezza, l'accesso alla rete nell'ambiente è disattivato. Devi specificare un allowlist per abilitare l'accesso. L'utilizzo di * come dominio in allowlist consente le connessioni a tutti i domini, fornendo un accesso di rete illimitato.

Metodo HTTP e URL

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

Corpo JSON della richiesta

{
  "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": "*" }
      ]
    }
  }
}

Comando 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": "*" }
              ]
          }
      }
  }'

Esempio di risposta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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: "*" }],
        },
    },
});

Crea un agente con gli strumenti proprietari di Google

Per creare un agente con gli strumenti proprietari di Google (come il grounding con la Ricerca Google e il contesto dell'URL), aggiungi questi strumenti all'elenco tools nella configurazione dell'agente:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.

  • AGENT_ID: l'identificatore personalizzato univoco per il nuovo agente. Gli ID agente personalizzati devono rispettare i seguenti vincoli:

    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.

  • AGENT_DESCRIPTION: un breve riepilogo dell'ambito dell'agente.

Corpo JSON della richiesta

{
  "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": "*" }
      ]
    }
  }
}

Comando 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": "*" }
              ]
          }
      }
  }'

Crea un agente con configurazioni MCP

Puoi creare un agente con strumenti del server MCP preconfigurati utilizzando l'API Managed Agents su Agent Platform.

Prima di iniziare

Prima di creare un agente con strumenti del server MCP preconfigurati, segui questi passaggi:

  • Concedi il ruolo Identity and Access Management (IAM) Utente strumento MCP (roles/mcp.toolUser) sia al tuo account utente sia al account di servizio associato.

  • Verifica che i server MCP nella tua configurazione comunichino tramite HTTP POST standard per gli elenchi e l'esecuzione degli strumenti. L'API Managed Agents su Agent Platform richiede che i server MCP remoti siano server HTTP trasmissibili. I server MCP devono implementare il trasporto HTTP trasmissibile MCP, in cui tools/list e tools/call vengono inviati come JSON-RPC tramite HTTP POST.

    Il trasporto HTTP+SSE a due endpoint deprecato (uno stream GET /sse separato di lunga durata) non è supportato.

Autorizza gli MCP ospitati da Google

Se utilizzi un token di connessione per l'autorizzazione dei server MCP ospitati da Google (come BigQuery), completa i seguenti passaggi:

  1. Aggiungi ambiti OAuth: aggiungi gli ambiti OAuth 2.0 richiesti al tuo token di autenticazione. Ad esempio, per utilizzare l'MCP di BigQuery, includi gli ambiti BigQuery pertinenti nella richiesta.
  2. Convalida l'accesso:verifica se il server MCP è accessibile con gli ambiti appena configurati testando il flusso di autorizzazione in OAuth Playground.
  3. Utilizza le intestazioni: per gli MCP di Google come BigQuery, devi includere l'intestazione X-Goog-User-Project impostata sul nome del progetto nella mappa headers.

Ad esempio, il corpo JSON della richiesta utilizzato per creare un agente che utilizza l'MCP BigQuery sarà simile al seguente:

{
  "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"
}

Crea l'agente

Per creare un agente con strumenti del server MCP preconfigurati, aggiungi i dettagli nella sezione tools:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.

  • AGENT_ID: l'identificatore personalizzato univoco per il nuovo agente. Gli ID agente personalizzati devono rispettare i seguenti vincoli:

    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.

  • AGENT_DESCRIPTION: un breve riepilogo dell'ambito dell'agente.

  • MCP_SERVER_NAME: un nome descrittivo per lo strumento MCP.

  • MCP_SERVER_URL: l'URL del gateway HTTP remoto del server MCP.

  • MCP_HEADER_KEY: (Facoltativo) Il nome dell'intestazione per l'autenticazione (ad esempio, Authorization).

  • MCP_HEADER_VALUE: (Facoltativo) Il token di connessione di autenticazione (ad esempio, Bearer <token>).

Corpo JSON della richiesta

{
  "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"
      }
    }
  ]
}

Comando 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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",
            },
        },
    ],
});

Collega le skill a un agente

Per caricare una skill riutilizzabile direttamente durante la creazione dell'agente, montala all'interno di base_environment.sources.

Puoi collegare le skill utilizzando uno dei seguenti metodi:

  • Skill Registry: collega una skill registrata all'interno del tuo progetto in Skill Registry.

  • Google Cloud Storage: collega le competenze personalizzate direttamente da un bucket Cloud Storage.

    Come best practice, ti consigliamo di montare le skill nella cartella /.agent/skills nell'ambiente per renderle più rilevabili per l'agente.

Competenze relative all'interfaccia a riga di comando

Gli sviluppatori possono anche installare skill specializzate nell'interfaccia a riga di comando che preferiscono per gestire in modo programmatico agenti e interazioni:

Collega una skill dal registro delle skill

Per caricare una skill riutilizzabile direttamente dal registro delle skill durante la creazione dell'agente:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato univoco per il nuovo agente. Gli ID agente personalizzati devono rispettare i seguenti vincoli:
    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.
  • SKILL_RESOURCE_NAME: il percorso della risorsa della skill o dell'elenco di skill da montare. Puoi specificare uno dei seguenti formati:
    • Skill (versione predefinita): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versione specifica: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • Elenco delle skill: projects/{projectID}/locations/{location}/skills. In questo modo, vengono montate fino a 100 competenze della project/location specificata nell'ambiente sandbox.
    Per saperne di più, consulta Elenca skill.
Corpo JSON della richiesta
{
  "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": "*" }
      ]
    }
  }
}
Comando 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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: "*" }],
        },
    },
});

Collega una skill da Google Cloud Storage

In alternativa, puoi collegare skill personalizzate direttamente da un bucket Cloud Storage durante la creazione dell'agente.

Tieni presente i seguenti requisiti quando monti le skill da Cloud Storage:

  • Requisiti di caricamento:devi caricare l'intera cartella della skill nel bucket.
  • Nessuna convalida dei contenuti: il backend non convalida i contenuti della cartella prima del montaggio; si comporta come un caricamento di cartelle standard.
  • Limiti di dimensioni: tutti i file allegati sono soggetti ai limiti di memoria dell'ambiente sandbox (fino a 4 GiB di RAM in totale).
  • Best practice: per una qualità ottimale delle skill, struttura e prepara i file nella cartella delle skill seguendo le convenzioni descritte su agentskills.io/home.

Per collegare una skill da Google Cloud Storage durante la creazione dell'agente:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'identificatore personalizzato univoco per il nuovo agente. Gli ID agente personalizzati devono rispettare i seguenti vincoli:
    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.
  • GCS_SOURCE_PATH: il percorso del bucket Google Cloud Storage contenente la cartella delle competenze (ad esempio, gs://cymbal-bucket-name/my-skill-folder).
Corpo JSON della richiesta
{
  "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": "*" }
      ]
    }
  }
}
Comando 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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: "*" }],
        },
    },
});

Elenca agenti

Per elencare tutti gli agenti salvati nel tuo progetto, invia una richiesta GET. Puoi utilizzare l'impaginazione facoltativa per controllare il numero di risultati per pagina.

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale per elencare gli agenti. È supportata solo la regione global.
  • PAGE_SIZE: (Facoltativo) Il numero massimo di agenti da restituire per pagina. Il valore predefinito è 10 e il valore massimo è 100.
  • PAGE_TOKEN: (Facoltativo) Un token di pagina, ricevuto da una risposta ListAgents precedente. Fornisci questo token per recuperare la pagina di risultati successiva.

Quando il numero di agenti da restituire è maggiore di PAGE_SIZE, la risposta ListAgents include un campo nextPageToken. Per recuperare la pagina successiva di agenti, passa il valore di questo nextPageToken come parametro PAGE_TOKEN nella richiesta ListAgents successiva. Ripeti questa procedura finché il campo nextPageToken non viene più restituito nella risposta.

Metodo HTTP e URL

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

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

Esempio di risposta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);
    }
}

Ottieni un agente

Per recuperare la configurazione completa di un agente specificato, utilizza una richiesta GET.

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .

  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.

  • AGENT_ID: l'ID univoco della configurazione dell'agente personalizzato che stai richiedendo.

Metodo HTTP e URL

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

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

Esempio di risposta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);

Aggiorna un agente

Per aggiornare la configurazione di un agente esistente, invia una richiesta PATCH. Sebbene l'ID dell'agente sia immutabile, puoi modificare parametri come istruzioni, strumenti e variabili di ambiente. Utilizza il parametro di query update_mask per specificare esattamente i campi da aggiornare. In questo modo, solo i campi che intendi modificare vengono interessati, mentre le altre configurazioni vengono conservate.

Aggiorna un agente di base

Per aggiornare le istruzioni di sistema di un agente, invia una richiesta PATCH con update_mask=system_instruction:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: Configurazione dell'agente di destinazione per l'aggiornamento della patch.
  • NEW_INSTRUCTIONS: la struttura o la descrizione delle istruzioni aggiornate da sostituire.

Metodo HTTP e URL

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

Corpo JSON della richiesta

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

Comando 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

Aggiorna un agente con gli strumenti proprietari di Google

Per aggiornare un agente in modo da attivare gli strumenti proprietari (1P) di Google (come il grounding con la Ricerca Google e il contesto dell'URL), invia una richiesta PATCH con update_mask=tools:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'ID dell'agente di destinazione.

Corpo JSON della richiesta

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

Comando 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"
          }
      ]
  }'

Aggiorna un agente con le configurazioni MCP

Per modificare gli strumenti MCP collegati all'agente, invia una richiesta PATCH con update_mask=tools:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'ID dell'agente di destinazione.
  • NEW_MCP_SERVER_NAME: etichetta aggiornata degli strumenti MCP.
  • NEW_MCP_SERVER_URL: il nuovo parametro dell'endpoint URL del server.
  • NEW_MCP_HEADER_KEY: (Facoltativo) Il nome dell'intestazione per l'autenticazione (ad esempio, Authorization).
  • NEW_MCP_HEADER_VALUE: (Facoltativo) Il token di connessione di autenticazione (ad esempio, Bearer <token>).

Corpo JSON della richiesta

{
  "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"
      }
    }
  ]
}

Comando 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

Collega le skill a un agente

Per collegare o modificare le skill all'interno di base_environment.sources durante l'aggiornamento di un agente, invia una richiesta PATCH utilizzando update_mask=base_environment.

Puoi collegare le skill utilizzando uno dei seguenti metodi:

  • Skill Registry: collega una skill registrata all'interno del tuo progetto in Skill Registry.

  • Google Cloud Storage: collega le competenze personalizzate direttamente da un bucket Cloud Storage.

Collega una skill dal registro delle skill

Per collegare una skill registrata in Skill Registry:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'ID dell'agente di destinazione.
  • NEW_SKILL_RESOURCE_NAME: il percorso della risorsa della skill o dell'elenco di skill da montare. Puoi specificare uno dei seguenti formati:
    • Skill (versione predefinita): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versione della skill (blocca a una versione specifica): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (monta tutte le skill): projects/{projectID}/locations/{location}/skills. In questo modo, nell'ambiente sandbox vengono montate fino a 100 skill nel progetto/nella località.
    Per saperne di più su come trovare il valore name per NEW_SKILL_RESOURCE_NAME, consulta Elenca skill.
Corpo JSON della richiesta
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Comando 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

Collega una skill da Google Cloud Storage

In alternativa, puoi collegare skill personalizzate direttamente da un bucket Cloud Storage durante la creazione dell'agente.

Tieni presente i seguenti requisiti quando monti le skill da Cloud Storage:

  • Requisiti di caricamento:devi caricare l'intera cartella della skill nel bucket.
  • Nessuna convalida dei contenuti: il backend non convalida i contenuti della cartella prima del montaggio; si comporta come un caricamento di cartelle standard.
  • Limiti di dimensioni: tutti i file allegati sono soggetti ai limiti di memoria dell'ambiente sandbox (fino a 4 GiB di RAM in totale).
  • Best practice: per una qualità ottimale delle skill, struttura e prepara i file nella cartella delle skill seguendo le convenzioni descritte su agentskills.io/home.

Per collegare una skill da Google Cloud Storage:

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'ID dell'agente di destinazione.
  • NEW_GCS_SOURCE_PATH: il percorso del bucket Google Cloud Storage contenente la cartella delle competenze (ad esempio, gs://cymbal-bucket-name/my-skill-folder).
Corpo JSON della richiesta
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
Comando 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

Elimina un agente

Per eliminare una configurazione dell'agente personalizzato specifica, invia una richiesta DELETE. Si tratta di un'operazione a lunga esecuzione che elimina definitivamente la configurazione. L'eliminazione dell'Agent Runtime invalida l'Agent Identity. Qualsiasi policy di accesso unificato (UAP) IAM che concede autorizzazioni a quell'entità conserva l'entità non più attiva nelle sue regole. Inoltre, l'associazione delle policy rimane attiva. Per rimuovere un'entità non più attiva, aggiorna la UAP per rimuovere l'entità dalle sue regole. Se la policy non contiene più entità attive, elimina l'associazione della policy.

Quando elimini un agente, fornisci tutte le informazioni necessarie nell'URL e non includere un corpo della richiesta JSON.

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione dell'agente. È supportata solo la regione global.
  • AGENT_ID: l'ID dell'agente che stai eliminando.

Metodo HTTP e URL

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

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

Esempio di risposta

{
  "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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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

Prima di eseguire questo codice, imposta le variabili descritte nella scheda 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);

Ottieni i dettagli di un'operazione a lunga esecuzione

Le operazioni come CreateAgent, UpdateAgent e DeleteAgent sono asincrone. La risposta iniziale dell'API restituisce un campo name contenente l'ID operazione. Utilizza GetOperation su questo ID per eseguire il polling dell'avanzamento.

REST

Variabili di richiesta

Prima di chiamare l'API, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la località regionale dell'operazione. È supportata solo la regione global.
  • OPERATION_ID: l'ID operazione estratto dal campo name nella risposta LRO iniziale.

Metodo HTTP e URL

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

Comando 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

Configurare l'accesso alla rete

Per impostazione predefinita, la sandbox disabilita l'accesso alla rete quando crei agenti utilizzando l'API Agents. Per consentire l'accesso illimitato, utilizza *.

Ad esempio, l'utilizzo di * in allowlist, come mostrato nel codice seguente, consente l'accesso a tutti i domini:

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

Passaggi successivi

Guida

Scopri come interagire con gli agenti in fase di runtime, gestire lo stato della sessione ed eseguire l'override dinamico delle configurazioni.