Criar e gerenciar agentes

Este guia explica como criar, recuperar, listar, atualizar e excluir recursos de agente personalizados que usam a API Managed Agents na plataforma de agentes, além de como configurar o ambiente do agente, as ferramentas do servidor do Protocolo de Contexto de Modelo (MCP) e as habilidades.

Pré-requisitos

Antes de configurar os agentes, faça o seguinte:

  • No console do Google Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .

  • Verifique se o faturamento está ativado para o projeto do Google Cloud .

  • Ative a API Gemini Enterprise Agent Platform (aiplatform.googleapis.com) no seu projeto.

  • Verifique se você tem um dos seguintes papéis:

    • aiplatform.user: fornece permissões para interagir com recursos do AI Platform.
    • aiplatform.admin: oferece controle total sobre os recursos do AI Platform, incluindo tarefas administrativas.

Criar um agente

Para criar um agente personalizado, use o método CreateAgent. Essa é uma operação de longa duração.

Criar agente básico

Para criar um agente básico com ferramentas padrão e um destino de montagem do Google Cloud Storage, envie uma solicitação POST:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .

  • LOCATION: a localização regional do seu agente. Somente a região global é compatível.

  • AGENT_ID: o identificador personalizado exclusivo do novo agente. Os IDs de agente personalizados precisam obedecer às seguintes restrições:

    • Precisa ter de 1 a 63 caracteres.
    • Só pode ter letras minúsculas, números e hífens.
    • Precisa começar com uma letra e terminar com uma letra ou um número.

  • AGENT_DESCRIPTION: um breve resumo do escopo do agente.

  • INSTRUCTIONS: instruções do sistema ou persona a ser definida no agente.

  • GCS_BUCKET: o segmento do caminho da pasta do bucket do Cloud Storage montado (por exemplo, gs://cymbal-bucket-name).

  • network: por motivos de segurança, o acesso à rede no ambiente está desativado. É necessário especificar um allowlist para ativar o acesso. Usar * como um domínio no allowlist permite conexões com todos os domínios, fornecendo acesso irrestrito à rede.

Método HTTP e URL

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

Corpo JSON da solicitação

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

Exemplo de resposta

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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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: "*" }],
        },
    },
});

Criar um agente com ferramentas próprias do Google

Para criar um agente com ferramentas próprias do Google (como Grounding com a Pesquisa Google e contexto de URL), adicione essas ferramentas à lista tools na configuração do agente:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a localização regional do seu agente. Somente a região global é compatível.

  • AGENT_ID: o identificador personalizado exclusivo do novo agente. Os IDs de agente personalizados precisam obedecer às seguintes restrições:

    • Precisa ter de 1 a 63 caracteres.
    • Só pode ter letras minúsculas, números e hífens.
    • Precisa começar com uma letra e terminar com uma letra ou um número.

  • AGENT_DESCRIPTION: um breve resumo do escopo do agente.

Corpo JSON da solicitação

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

Criar um agente com configurações do MCP

Para criar um agente com ferramentas de servidor MCP pré-configuradas, adicione detalhes na seção "Ferramentas":

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a localização regional do seu agente. Somente a região global é compatível.

  • AGENT_ID: o identificador personalizado exclusivo do novo agente. Os IDs de agente personalizados precisam obedecer às seguintes restrições:

    • Precisa ter de 1 a 63 caracteres.
    • Só pode ter letras minúsculas, números e hífens.
    • Precisa começar com uma letra e terminar com uma letra ou um número.

  • AGENT_DESCRIPTION: um breve resumo do escopo do agente.

  • MCP_SERVER_NAME: um nome descritivo para a ferramenta do MCP.

  • MCP_SERVER_URL: o URL do gateway HTTP remoto do servidor MCP.

  • MCP_HEADER_KEY: opcional. O nome do cabeçalho para autenticação (por exemplo, Authorization).

  • MCP_HEADER_VALUE: opcional. O token de autenticação (por exemplo, Bearer <token>).

Corpo JSON da solicitação

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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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",
            },
        },
    ],
});

Atribuir habilidades a um agente

Para carregar uma habilidade reutilizável diretamente ao criar o agente, monte-a dentro de base_environment.sources.

É possível anexar habilidades usando um dos seguintes métodos:

  • Registro de habilidades:anexe uma habilidade registrada no projeto em Registro de habilidades.

  • Google Cloud Storage:anexe habilidades personalizadas diretamente de um bucket do Cloud Storage.

    Como prática recomendada, recomendamos montar habilidades na pasta /.agent/skills no ambiente para que o agente as encontre com mais facilidade.

Anexar uma habilidade do registro de habilidades

Para carregar uma habilidade reutilizável diretamente do Skill Registry ao criar o agente:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do seu agente. Somente a região global é compatível.
  • AGENT_ID: o identificador personalizado exclusivo do novo agente. Os IDs de agente personalizados precisam obedecer às seguintes restrições:
    • Precisa ter de 1 a 63 caracteres.
    • Só pode ter letras minúsculas, números e hífens.
    • Precisa começar com uma letra e terminar com uma letra ou um número.
  • SKILL_RESOURCE_NAME: o caminho do recurso da habilidade ou da lista de habilidades a serem montadas. É possível especificar um dos seguintes formatos:
    • Skill (versão padrão): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versão específica: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • Lista de habilidades:projects/{projectID}/locations/{location}/skills. Isso monta até 100 habilidades do project/location especificado no ambiente de sandbox.
    Para mais informações, consulte listar habilidades.
Corpo JSON da solicitação
{
  "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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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: "*" }],
        },
    },
});

Anexar uma habilidade do Google Cloud Storage

Também é possível anexar habilidades personalizadas diretamente de um bucket do Cloud Storage ao criar o agente.

Observe os seguintes requisitos ao montar habilidades do Cloud Storage:

  • Requisitos de upload:faça upload de toda a pasta da skill para o bucket.
  • Sem validação de conteúdo:o back-end não valida o conteúdo da pasta antes da montagem. Ele se comporta como um upload de pasta padrão.
  • Limites de tamanho:todos os arquivos anexados estão sujeitos aos limites de memória do ambiente de sandbox (até 4 GiB de RAM no total).
  • Práticas recomendadas:para uma qualidade ideal da habilidade, estruture e prepare os arquivos na pasta dela seguindo as convenções descritas em agentskills.io/home.

Para anexar uma habilidade do Google Cloud Storage ao criar o agente:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do seu agente. Somente a região global é compatível.
  • AGENT_ID: o identificador personalizado exclusivo do novo agente. Os IDs de agente personalizados precisam obedecer às seguintes restrições:
    • Precisa ter de 1 a 63 caracteres.
    • Só pode ter letras minúsculas, números e hífens.
    • Precisa começar com uma letra e terminar com uma letra ou um número.
  • GCS_SOURCE_PATH: o caminho do bucket do Google Cloud Storage que contém a pasta da sua habilidade (por exemplo, gs://cymbal-bucket-name/my-skill-folder).
Corpo JSON da solicitação
{
  "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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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: "*" }],
        },
    },
});

Listar agentes

Para listar todos os agentes salvos no seu projeto, envie uma solicitação GET. É possível usar a paginação opcional para controlar o número de resultados por página.

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional para listar agentes. Somente a região global é compatível.
  • PAGE_SIZE: opcional. O número máximo de agentes a serem retornados por página. O valor padrão é 10, e o valor máximo é 100.
  • PAGE_TOKEN: opcional. Um token de página recebido de uma resposta ListAgents anterior. Forneça esse token para recuperar a página seguinte de resultados.

Quando o número de agentes a serem retornados é maior que o PAGE_SIZE, a resposta ListAgents inclui um campo nextPageToken. Para recuperar a próxima página de agentes, transmita o valor de nextPageToken como o parâmetro PAGE_TOKEN na próxima solicitação ListAgents. Repita esse processo até que o campo nextPageToken não seja mais retornado na resposta.

Método 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)"

Exemplo de resposta

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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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);
    }
}

Obter um agente

Para recuperar a configuração completa de um agente especificado, use uma solicitação GET.

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .

  • LOCATION: o local regional do seu agente. Somente a região global é compatível.

  • AGENT_ID: o ID exclusivo da configuração do agente personalizado que você está solicitando.

Método 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)"

Exemplo de resposta

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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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);

Atualizar um agente

Para atualizar a configuração de um agente, envie uma solicitação PATCH. Embora o ID do agente seja imutável, é possível modificar parâmetros como instruções, ferramentas e variáveis de ambiente. Use o parâmetro de consulta update_mask para especificar exatamente quais campos atualizar. Isso garante que apenas os campos que você pretende mudar sejam afetados, preservando outras configurações.

Atualizar um agente básico

Para atualizar as instruções do sistema de um agente, envie uma solicitação PATCH com update_mask=system_instruction:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do agente. Somente a região global é compatível.
  • AGENT_ID: configuração do agente de destino para atualização de patch.
  • NEW_INSTRUCTIONS: a estrutura ou descrição atualizada das instruções a serem substituídas.

Método HTTP e URL

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

Corpo JSON da solicitação

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

Atualizar um agente com ferramentas próprias do Google

Para atualizar um agente e ativar as ferramentas próprias (1P) do Google, como o embasamento com a Pesquisa Google e o contexto de URL, envie uma solicitação PATCH com update_mask=tools:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do agente. Somente a região global é compatível.
  • AGENT_ID: ID do agente de destino.

Corpo JSON da solicitação

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

Atualizar um agente com configurações do MCP

Para modificar as ferramentas do MCP anexadas ao seu agente, envie uma solicitação PATCH com update_mask=tools:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do agente. Somente a região global é compatível.
  • AGENT_ID: ID do agente de destino.
  • NEW_MCP_SERVER_NAME: rótulo atualizado das suas ferramentas do MCP.
  • NEW_MCP_SERVER_URL: o novo parâmetro de endpoint de URL do servidor.
  • NEW_MCP_HEADER_KEY: opcional. O nome do cabeçalho para autenticação (por exemplo, Authorization).
  • NEW_MCP_HEADER_VALUE: opcional. O token de autorização de autenticação (por exemplo, Bearer <token>).

Corpo JSON da solicitação

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

Atribuir habilidades a um agente

Para anexar ou modificar habilidades no base_environment.sources durante uma atualização do agente, envie uma solicitação PATCH usando update_mask=base_environment.

É possível anexar habilidades usando um dos seguintes métodos:

  • Registro de habilidades:anexe uma habilidade registrada no projeto em Registro de habilidades.

  • Google Cloud Storage:anexe habilidades personalizadas diretamente de um bucket do Cloud Storage.

Anexar uma habilidade do registro de habilidades

Para anexar uma habilidade registrada no Registro de habilidades:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do agente. Somente a região global é compatível.
  • AGENT_ID: ID do agente de destino.
  • NEW_SKILL_RESOURCE_NAME: o caminho do recurso da habilidade ou lista de habilidades a serem montadas. Você pode especificar um dos seguintes formatos:
    • Skill (versão padrão): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versão da skill (fixar em uma versão específica): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (montar todas as habilidades): projects/{projectID}/locations/{location}/skills. Isso monta até 100 habilidades no projeto/local no ambiente de sandbox.
    Para mais informações sobre como encontrar o valor de name para NEW_SKILL_RESOURCE_NAME, consulte Listar habilidades.
Corpo JSON da solicitação
{
  "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

Anexar uma habilidade do Google Cloud Storage

Também é possível anexar habilidades personalizadas diretamente de um bucket do Cloud Storage ao criar o agente.

Observe os seguintes requisitos ao montar habilidades do Cloud Storage:

  • Requisitos de upload:faça upload de toda a pasta da skill para o bucket.
  • Sem validação de conteúdo:o back-end não valida o conteúdo da pasta antes da montagem. Ele se comporta como um upload de pasta padrão.
  • Limites de tamanho:todos os arquivos anexados estão sujeitos aos limites de memória do ambiente de sandbox (até 4 GiB de RAM no total).
  • Práticas recomendadas:para uma qualidade ideal da habilidade, estruture e prepare os arquivos na pasta dela seguindo as convenções descritas em agentskills.io/home.

Para anexar uma habilidade do Google Cloud Storage:

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional do agente. Somente a região global é compatível.
  • AGENT_ID: ID do agente de destino.
  • NEW_GCS_SOURCE_PATH: o caminho do bucket do Google Cloud Storage que contém a pasta da sua habilidade (por exemplo, gs://cymbal-bucket-name/my-skill-folder).
Corpo JSON da solicitação
{
  "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

Excluir um agente

Para excluir uma configuração de agente personalizada específica, envie uma solicitação DELETE. Essa é uma operação de longa duração e exclui a configuração permanentemente.

Ao excluir um agente, forneça todas as informações necessárias no URL e não inclua um corpo de solicitação JSON.

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região do agente. Somente a região global é compatível.
  • AGENT_ID: o ID do agente que você está excluindo.

Método 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)"

Exemplo de resposta

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

Antes de executar esse código, defina as variáveis descritas na guia "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

Antes de executar esse código, defina as variáveis descritas na guia "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);

Acessar os detalhes de uma operação de longa duração

Operações como CreateAgent, UpdateAgent e DeleteAgent são assíncronas. A resposta inicial da API retorna um campo name que contém o ID da operação. Use GetOperation nesse ID para consultar o progresso.

REST

Variáveis de solicitação

Antes de chamar a API, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local regional da operação. Somente a região global é compatível.
  • OPERATION_ID: o ID da operação extraído do campo name na resposta inicial da LRO.

Método 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

Configurar o acesso à rede

Por padrão, o sandbox desativa o acesso à rede quando você cria agentes usando a API Agents. Para permitir acesso irrestrito, use *.

Por exemplo, usar * em allowlist, conforme mostrado no código a seguir, dá acesso a todos os domínios:

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

A seguir

Guia

Saiba como interagir com agentes em tempo de execução, gerenciar o estado da sessão e substituir configurações de forma dinâmica.