Criar e gerenciar agentes

Este produto é uma oferta pré-GA, sujeita aos "Termos das ofertas pré-GA" na seção Termos gerais de serviço dos Termos específicos de serviço, aos termos de "Serviços de IA autônoma" nos Termos específicos de serviço e aos Termos adicionais para produtos de pré-lançamento de IA generativa. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

Esses produtos pré-GA estão em várias etapas de teste e revisão internos. Por isso, não use dados reservados, sensíveis ou confidenciais com esses produtos. Esses produtos são disponibilizados aos clientes apenas para testes e avaliações limitados e não podem ser usados para fins comerciais ou de produção.

Para conferir um exemplo de como criar e gerenciar agentes, execute o notebook "Introdução aos agentes gerenciados em Python" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Agent Platform Workbench | Ver no GitHub

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

Observação: o uso do modelo durante o pré-lançamento é cobrado com taxas padrão. Para mais informações, consulte a página de preços.

Antes de começar

Antes de configurar os agentes, configure o ambiente:

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
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
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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.
1. Se você planeja usar ferramentas do Google Cloud Protocolo de Contexto de Modelo (MCP) com seu agente, conceda a função de usuário da ferramenta MCP (roles/mcp.toolUser) à sua conta de usuário e à conta de serviço associada.

Criar um agente

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

Observação: durante o período de prévia, o provisionamento do primeiro agente no seu projeto pode levar de dois a três minutos. Os agentes subsequentes normalmente são provisionados em dois a três segundos.

O agente básico

O base_agent é o mecanismo de orquestração principal que fornece ao agente recursos de raciocínio e acesso ao ambiente de execução. Ele pode injetar habilidades e bibliotecas no ambiente e tem acesso a ferramentas do lado do serviço para execução de código, operações do sistema de arquivos e pesquisa com embasamento.

Ao criar um agente, apenas um valor é compatível com base_agent: antigravity-preview-05-2026.

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.

• BASE_AGENT: o nome do agente de base a ser estendido. Use antigravity-preview-05-2026.

• 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 Google Cloud Storage montado (por exemplo, gs://cymbal-bucket-name). Observação: para montar um bucket de outro projeto, conceda à conta de serviço do projeto acesso read e write ao bucket.

• 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": "BASE_AGENT",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth 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

É possível criar um agente com ferramentas de servidor MCP pré-configuradas usando a API Agentes Gerenciados na Agent Platform.

Antes de começar

Antes de criar um agente com ferramentas de servidor MCP pré-configuradas, faça o seguinte:

• Conceda o papel Usuário da ferramenta MCP (roles/mcp.toolUser) do Identity and Access Management (IAM) à sua conta de usuário e à conta de serviço associada.

• Confirme se os servidores MCP na sua configuração se comunicam pelo HTTP POST padrão para listagens e execução de ferramentas. A API Managed Agents na Agent Platform exige que os servidores MCP remotos sejam servidores HTTP transmitíveis. Os servidores do MCP precisam implementar o transporte HTTP transmissível do MCP, em que tools/list e tools/call são enviados como JSON-RPC por HTTP POST.

  O transporte HTTP+SSE de dois endpoints descontinuado (um fluxo GET /sse separado de longa duração) está indisponível.

Autorizar MCPs hospedados pelo Google

Se você estiver usando um token de portador para autorização de servidores MCP hospedados pelo Google (como o BigQuery), siga estas etapas:

1. Adicionar escopos do OAuth:adicione os escopos do OAuth 2.0 necessários ao seu token de autenticação. Por exemplo, para usar a MCP do BigQuery, inclua os escopos relevantes do BigQuery na sua solicitação.
2. Validar acesso:verifique se o servidor MCP está acessível com seus escopos recém-configurados testando o fluxo de autorização no OAuth Playground.
3. Usar cabeçalhos:para MCPs do Google, como o BigQuery, inclua o cabeçalho X-Goog-User-Project definido como o nome do projeto no mapa headers.

Por exemplo, o corpo JSON da solicitação usado para criar um agente que usa o MCP do BigQuery seria semelhante a este:

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

Criar um agente

Para criar um agente com ferramentas de servidor MCP pré-configuradas, adicione detalhes na seção 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: 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 seu 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.

Habilidades de CLI

Os desenvolvedores também podem instalar habilidades especializadas na CLI de preferência para gerenciar agentes e interações de forma programática:

• Skill da API Agents
• Skill da API Interaction

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: 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.
• 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: 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.
• 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 agentes de listagem. 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 application-default 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: a localização 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

Observação: o método update ainda não está disponível no SDK do Python. Use a API REST para atualizar agentes.

JavaScript

Observação: o método update ainda não está disponível no SDK para JavaScript. Use a API REST para atualizar agentes.

Atualizar um agente com ferramentas nativas 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

Observação: o método update ainda não está disponível no SDK do Python. Use a API REST para atualizar agentes.

JavaScript

Observação: o método update ainda não está disponível no SDK para JavaScript. Use a API REST para atualizar agentes.

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

Observação:o método update ainda não está disponível no SDK do Python. Use a API REST para atualizar as habilidades do agente.

JavaScript

Observação:o método update ainda não está disponível no SDK para JavaScript. Use a API REST para atualizar as habilidades do agente.

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

Observação:o método update ainda não está disponível no SDK do Python. Use a API REST para atualizar as habilidades do agente.

JavaScript

Observação:o método update ainda não está disponível no SDK para JavaScript. Use a API REST para atualizar as habilidades do agente.

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

Observação: ao usar o SDK para Python, operações como agents.create() e agents.delete() retornam o resultado final diretamente. Use client.agents.get(id="AGENT_ID") para verificar o status do provisionamento.

JavaScript

Observação: ao usar o SDK para JavaScript, operações como agents.create() e agents.delete() retornam o resultado final diretamente. Use client.agents.get("AGENT_ID") para verificar o status do provisionamento.

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

Interaja com agentes

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