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.

Prerequisiti

Prima di configurare gli agenti, completa le seguenti operazioni:

  • Nella console Google Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

  • Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  • Attiva l'API Gemini Enterprise Agent Platform (aiplatform.googleapis.com) sul tuo progetto.

  • Assicurati di disporre di uno dei seguenti ruoli:

    • aiplatform.user: fornisce le autorizzazioni per interagire con le risorse AI Platform.
    • aiplatform.admin: fornisce il controllo completo delle risorse AI Platform, incluse le attività amministrative.

Crea un agente

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

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.

  • 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 di Google montato (ad esempio, gs://cymbal-bucket-name).

  • 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 limitazioni.

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

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

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

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

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

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 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 le skill a un agente

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

Puoi allegare le competenze utilizzando uno dei seguenti metodi:

  • Registro delle competenze:allega una competenza registrata nel tuo progetto nel Registro delle competenze.

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

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

Allegare una competenza dal registro delle competenze

Per caricare una competenza riutilizzabile direttamente dal registro delle competenze 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": "*" }
      ]
    }
  }
}
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 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 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 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 Cloud Storage di Google 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": "*" }
      ]
    }
  }
}
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 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

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

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

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

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

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 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 le 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:

  • Registro delle competenze:allega una competenza registrata nel tuo progetto nel Registro delle competenze.

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

Allegare una competenza dal registro delle competenze

Per allegare una competenza registrata nel Registro delle competenze:

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 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 della skill (limita a 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 skill 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": "*" }
      ]
    }
  }
}
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 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 un'abilità 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 Cloud Storage di Google 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": "*" }
      ]
    }
  }
}
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 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 agente personalizzata 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

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

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