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 skill.

Prima di iniziare

Prima di configurare gli agenti, configura l'ambiente:

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

    Roles required to select or create a project

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

    Go to project selector

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

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the 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

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

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

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

    Roles required to select or create a project

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

    Go to project selector

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

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the 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

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  10. Se prevedi di utilizzare gli strumenti Model Context Protocol (MCP) con il tuo agente, concedi il ruolo Utente strumento MCP (roles/mcp.toolUser) sia al tuo account utente sia al account di servizio associato. Google Cloud

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'orchestratore 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 server 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 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 Google Cloud .
  • LOCATION: la posizione regionale del tuo 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 Google Cloud Storage montato (ad esempio, gs://cymbal-bucket-name). Nota: per montare un bucket da un altro progetto, concedi all'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 connessioni a tutti i domini, fornendo un accesso di rete senza restrizioni.

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

curl comando

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

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: "*" }],
        },
    },
});

Creare un agente con gli strumenti proprietari di Google

Per creare un agente con strumenti proprietari di Google (come Grounding con la Ricerca Google e il contesto 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 Google Cloud .
  • LOCATION: la posizione regionale del tuo 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": "*" }
      ]
    }
  }
}

curl comando

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

Crea un agente con le 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:

  • 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 su HTTP POST.

    Il trasporto HTTP+SSE con due endpoint (un flusso GET /sse separato a lunga durata) è deprecato e non è supportato.

Autorizza le CMP ospitate da Google

Se utilizzi un token di autenticazione 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 token di autenticazione. Ad esempio, per utilizzare BigQuery MCP, includi gli ambiti BigQuery pertinenti nella richiesta.
  2. Convalida l'accesso:verifica se il server MCP è accessibile con i nuovi ambiti configurati testando il flusso di autorizzazione in OAuth Playground.
  3. Utilizza intestazioni:per i partner Google MCP 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 il progetto BigQuery avrebbe un aspetto 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://mcp-bigquery.googleapis.com/v1",
      "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 gli 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 Google Cloud .
  • LOCATION: la posizione regionale del tuo 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"
      }
    }
  ]
}

curl comando

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

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",
            },
        },
    ],
});

Collegare skill a un agente

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

Puoi allegare le competenze utilizzando uno dei seguenti metodi:

  • Skill Registry: allega una skill registrata nel tuo progetto in Skill Registry.

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

    Come best practice, ti consigliamo di montare le competenze nella cartella /.agent/skills dell'ambiente per renderle più rilevabili dall'agente.

Competenze CLI

Gli sviluppatori possono anche installare competenze specializzate nella CLI che preferiscono per gestire in modo programmatico agenti e interazioni:

Allegare una skill da Skill Registry

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 Google Cloud .
  • LOCATION: la posizione regionale del tuo 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 dell'abilità o dell'elenco di abilità 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 competenze: projects/{projectID}/locations/{location}/skills. Vengono montate fino a 100 competenze dal project/location nell'ambiente sandbox.
    Per saperne di più, consulta Elenco delle competenze.
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": "*" }
      ]
    }
  }
}
curl comando
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

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: "*" }],
        },
    },
});

Allegare 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 cartella standard.
  • Limiti di dimensione: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 allegare 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 Google Cloud .
  • LOCATION: la posizione regionale del tuo 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 della tua skill (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": "*" }
      ]
    }
  }
}
curl comando
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

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 Google Cloud .
  • LOCATION: La posizione regionale per gli agenti immobiliari. È 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 precedente risposta ListAgents. Fornisci questo token per recuperare la pagina successiva dei risultati.

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, trasmetti 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

curl comando

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 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);
    }
}

Recuperare 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 Google Cloud .

  • LOCATION: la posizione regionale del tuo 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

curl comando

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

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);

Aggiornare un agente

Per aggiornare la configurazione di un agente esistente, invia una richiesta PATCH. Anche se l'ID dell'agente è 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, vengono interessati solo i campi che intendi modificare, preservando le altre configurazioni.

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 Google Cloud .
  • LOCATION: la posizione 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 aggiornata delle istruzioni 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"
}

curl comando

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

JavaScript

Aggiornare un agente con gli strumenti proprietari di Google

Per aggiornare un agente in modo da attivare gli strumenti proprietari di Google (come 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 Google Cloud .
  • LOCATION: la posizione regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: ID agente di destinazione.

Corpo JSON della richiesta

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

curl comando

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

Aggiornare un agente con le configurazioni MCP

Per modificare gli strumenti MCP collegati al tuo 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 Google Cloud .
  • LOCATION: la posizione regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: ID 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 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"
      }
    }
  ]
}

curl comando

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

JavaScript

Collegare skill a un agente

Per allegare o modificare le competenze all'interno di base_environment.sources durante un aggiornamento dell'agente, invia una richiesta PATCH utilizzando update_mask=base_environment.

Puoi allegare le competenze utilizzando uno dei seguenti metodi:

  • Skill Registry: allega una skill registrata nel tuo progetto in Skill Registry.

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

Allegare una skill da Skill Registry

Per allegare una competenza registrata in Skill Registry:

REST

Variabili di richiesta

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

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la posizione regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: ID 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 una versione specifica): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (Mount all skills): projects/{projectID}/locations/{location}/skills. In questo modo vengono montate fino a 100 competenze nel progetto/nella località nell'ambiente sandbox.
    Per saperne di più su come trovare il valore di name per NEW_SKILL_RESOURCE_NAME, consulta Elenca le competenze.
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": "*" }
      ]
    }
  }
}
curl comando
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

JavaScript

Allegare 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 cartella standard.
  • Limiti di dimensione: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 allegare una competenza da Google Cloud Storage:

REST

Variabili di richiesta

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

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la posizione regionale dell'agente. È supportata solo la regione global.
  • AGENT_ID: ID agente di destinazione.
  • NEW_GCS_SOURCE_PATH: il percorso del bucket Google Cloud Storage contenente la cartella della tua skill (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": "*" }
      ]
    }
  }
}
curl comando
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

JavaScript

Eliminare un agente

Per eliminare una configurazione di agenti personalizzati specifica, invia una richiesta DELETE. Questa è un'operazione a lunga esecuzione ed elimina la configurazione in modo permanente.

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 Google Cloud .
  • 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

curl comando

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

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);

Visualizzare i dettagli di un'operazione a lunga esecuzione

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 monitorare l'avanzamento.

REST

Variabili di richiesta

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

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la posizione 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

curl comando

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

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 seguente codice, 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.