Crear y administrar agentes

En esta guía, se explica cómo crear, recuperar, enumerar, actualizar y borrar recursos de agentes personalizados que usan la API de Agentes administrados en Agent Platform, y cómo configurar el entorno del agente, las herramientas del servidor del Protocolo de contexto del modelo (MCP) y las habilidades.

Antes de comenzar

Antes de configurar tus agentes, configura tu entorno:

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

    Roles required to select or create a project

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

    Go to project selector

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

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

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

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

    Roles required to select or create a project

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

    Go to project selector

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

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  10. Si planeas usar herramientas del Protocolo de contexto del modelo (MCP) Google Cloud con tu agente, otorga el rol de usuario de herramientas de MCP (roles/mcp.toolUser) tanto a tu cuenta de usuario como a la cuenta de servicio asociada.

Crea un agente

Para crear un nuevo agente personalizado, usa el método CreateAgent. Esta es una operación de larga duración.

El agente base

El base_agent es el arnés de orquestación principal que proporciona al agente capacidades de razonamiento y acceso al entorno de ejecución. Puede insertar habilidades y bibliotecas en el entorno, y tiene acceso a herramientas del servidor para la ejecución de código, las operaciones del sistema de archivos y la búsqueda con fundamentación.

Cuando creas un agente, solo se admite un valor para base_agent: antigravity-preview-05-2026.

Crear un agente básico

Para crear un agente básico con herramientas predeterminadas y un destino de montaje de Google Cloud Storage, envía una solicitud POST:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.

  • AGENT_ID: Es el identificador personalizado único de tu nuevo agente. Los IDs de agentes personalizados deben cumplir con las siguientes restricciones:

    • Debe tener entre 1 y 63 caracteres.
    • Solo debe contener letras minúsculas, números y guiones.
    • Debe empezar con una letra y terminar con una letra o un número.

  • BASE_AGENT: Es el nombre del agente base que se extenderá. Usa antigravity-preview-05-2026

  • AGENT_DESCRIPTION: Es un breve resumen del alcance del agente.

  • INSTRUCTIONS: Son las instrucciones del sistema o el arquetipo que se establecerán en el agente.

  • GCS_BUCKET: Es el segmento de la ruta de acceso a la carpeta de tu bucket de Google Cloud Storage que está activado (por ejemplo, gs://cymbal-bucket-name). Nota: Para activar un bucket de otro proyecto, otorga a la cuenta de servicio del proyecto acceso de read y write al bucket.

  • network: Por motivos de seguridad, el acceso a la red en el entorno está desactivado. Debes especificar un allowlist para habilitar el acceso. Usar * como dominio en allowlist permite conexiones a todos los dominios, lo que proporciona acceso irrestricto a la red.

Método HTTP y URL

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

Cuerpo JSON de la solicitud

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

Ejemplo de respuesta

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña REST.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

Crea un agente con las herramientas propias de Google

Para crear un agente con herramientas propias de Google (como Grounding con la Búsqueda de Google y el contexto de URL), agrega estas herramientas a la lista tools en la configuración del agente:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.

  • AGENT_ID: Es el identificador personalizado único de tu nuevo agente. Los IDs de agentes personalizados deben cumplir con las siguientes restricciones:

    • Debe tener entre 1 y 63 caracteres.
    • Solo debe contener letras minúsculas, números y guiones.
    • Debe empezar con una letra y terminar con una letra o un número.

  • AGENT_DESCRIPTION: Es un breve resumen del alcance del agente.

Cuerpo JSON de la solicitud

{
  "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 la configuración del MCP

Puedes crear un agente con herramientas del servidor de MCP preconfiguradas usando la API de Agentes administrados en Agent Platform.

Antes de comenzar

Antes de crear un agente con herramientas del servidor de MCP preconfiguradas, haz lo siguiente:

  • Otorga el rol de Identity and Access Management (IAM) de usuario de la herramienta de MCP (roles/mcp.toolUser) a tu cuenta de usuario y a la cuenta de servicio asociada.

  • Confirma que los servidores de MCP en tu configuración se comuniquen a través de HTTP POST estándar para la ejecución y las fichas de herramientas. La API de Managed Agents en Agent Platform requiere que los servidores de MCP remotos sean servidores HTTP transmitibles. Los servidores de MCP deben implementar el transporte HTTP transmitible de MCP, en el que tools/list y tools/call se envían como JSON-RPC a través de HTTP POST.

    No se admite el transporte HTTP + SSE de dos extremos que dejó de estar disponible (un flujo GET /sse independiente de larga duración).

Autoriza los MCP alojados en Google

Si usas un token de portador para la autorización de servidores de MCP alojados en Google (como BigQuery), completa los siguientes pasos:

  1. Agrega permisos de OAuth: Agrega los permisos de OAuth 2.0 necesarios a tu token de autenticación. Por ejemplo, para usar el MCP de BigQuery, incluye los permisos relevantes de BigQuery en tu solicitud.
  2. Validar el acceso: Verifica si se puede acceder al servidor de MCP con los permisos recién configurados probando el flujo de autorización en OAuth Playground.
  3. Use Headers: Para los MCP de Google, como BigQuery, debes incluir el encabezado X-Goog-User-Project establecido en el nombre de tu proyecto en el mapa headers.

Por ejemplo, el cuerpo JSON de la solicitud que se usa para crear un agente que usa el MCP de BigQuery se parecería al siguiente:

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

Crea el agente

Para crear un agente con herramientas de servidor de MCP preconfiguradas, agrega detalles en la sección tools:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.

  • AGENT_ID: Es el identificador personalizado único de tu nuevo agente. Los IDs de agentes personalizados deben cumplir con las siguientes restricciones:

    • Debe tener entre 1 y 63 caracteres.
    • Solo debe contener letras minúsculas, números y guiones.
    • Debe empezar con una letra y terminar con una letra o un número.

  • AGENT_DESCRIPTION: Es un breve resumen del alcance del agente.

  • MCP_SERVER_NAME: Es un nombre descriptivo para la herramienta de MCP.

  • MCP_SERVER_URL: Es la URL de la puerta de enlace HTTP remota del servidor de MCP.

  • MCP_HEADER_KEY: Opcional Nombre del encabezado para la autenticación (por ejemplo, Authorization).

  • MCP_HEADER_VALUE: Opcional Token de portador de autenticación (por ejemplo, Bearer <token>)

Cuerpo JSON de la solicitud

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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",
            },
        },
    ],
});

Cómo adjuntar habilidades a un agente

Para cargar una habilidad reutilizable directamente cuando crees el agente, móntala dentro de base_environment.sources.

Puedes adjuntar habilidades con cualquiera de los siguientes métodos:

  • Skill Registry: Adjunta una habilidad registrada en tu proyecto en Skill Registry.

  • Google Cloud Storage: Adjunta habilidades personalizadas directamente desde un bucket de Cloud Storage.

    Como práctica recomendada, te recomendamos que montes las habilidades en la carpeta /.agent/skills del entorno para que el agente las pueda detectar con mayor facilidad.

Habilidades de la CLI

Los desarrolladores también pueden instalar habilidades especializadas en la CLI que prefieran para administrar agentes e interacciones de forma programática:

Cómo adjuntar una habilidad desde el Registro de habilidades

Para cargar una habilidad reutilizable directamente desde el Registro de habilidades cuando crees el agente, haz lo siguiente:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.
  • AGENT_ID: Es el identificador personalizado único de tu nuevo agente. Los IDs de agentes personalizados deben cumplir con las siguientes restricciones:
    • Debe tener entre 1 y 63 caracteres.
    • Solo debe contener letras minúsculas, números y guiones.
    • Debe empezar con una letra y terminar con una letra o un número.
  • SKILL_RESOURCE_NAME: Es la ruta de acceso del recurso de la skill o la lista de skills que se activarán. Puedes especificar uno de los siguientes formatos:
    • Habilidad (versión predeterminada): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versión específica: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • Lista de habilidades: projects/{projectID}/locations/{location}/skills. Esto activa hasta 100 habilidades del project/location especificado en el entorno de zona de pruebas.
    Para obtener más información, consulta cómo enumerar habilidades.
Cuerpo JSON de la solicitud
{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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: "*" }],
        },
    },
});

Cómo adjuntar una habilidad desde Google Cloud Storage

Como alternativa, puedes adjuntar habilidades personalizadas directamente desde un bucket de Cloud Storage cuando crees el agente.

Ten en cuenta los siguientes requisitos cuando montes habilidades desde Cloud Storage:

  • Requisitos de carga: Debes subir toda la carpeta de la skill al bucket.
  • Sin validación de contenido: El backend no valida el contenido de la carpeta antes de la vinculación, sino que se comporta como una carga de carpeta estándar.
  • Límites de tamaño: Todos los archivos adjuntos están sujetos a los límites de memoria del entorno de zona de pruebas (hasta 4 GiB de RAM en total).
  • Prácticas recomendadas: Para obtener una calidad óptima de la skill, estructura y prepara los archivos de la carpeta de la skill según las convenciones que se describen en agentskills.io/home.

Para adjuntar una habilidad desde Google Cloud Storage cuando crees el agente, haz lo siguiente:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.
  • AGENT_ID: Es el identificador personalizado único de tu nuevo agente. Los IDs de agentes personalizados deben cumplir con las siguientes restricciones:
    • Debe tener entre 1 y 63 caracteres.
    • Solo debe contener letras minúsculas, números y guiones.
    • Debe empezar con una letra y terminar con una letra o un número.
  • GCS_SOURCE_PATH: Es la ruta de acceso al bucket de Google Cloud Storage que contiene la carpeta de tu skill (por ejemplo, gs://cymbal-bucket-name/my-skill-folder).
Cuerpo JSON de la solicitud
{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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: "*" }],
        },
    },
});

Mostrar lista de agentes

Para enumerar todos los agentes guardados en tu proyecto, envía una solicitud GET. Puedes usar la paginación opcional para controlar la cantidad de resultados por página.

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de los agentes de la ficha. Solo se admite la región global.
  • PAGE_SIZE: Opcional Es la cantidad máxima de agentes que se devolverán por página. El valor predeterminado es 10 y el valor máximo es 100.
  • PAGE_TOKEN: Opcional Es un token de página, recibido de una respuesta ListAgents anterior. Proporciona este token para recuperar la página siguiente de resultados.

Cuando la cantidad de agentes que se deben devolver es mayor que PAGE_SIZE, la respuesta ListAgents incluye un campo nextPageToken. Para recuperar la siguiente página de agentes, pasa el valor de este nextPageToken como el parámetro PAGE_TOKEN en tu próxima solicitud de ListAgents. Repite este proceso hasta que el campo nextPageToken ya no se muestre en la respuesta.

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

Ejemplo de respuesta

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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);
    }
}

Obtén un agente

Para recuperar la configuración completa de un agente especificado, usa una solicitud GET.

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .

  • LOCATION: Es la ubicación regional de tu agente. Solo se admite la región global.

  • AGENT_ID: Es el ID único de la configuración del agente personalizado que solicitas.

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

Ejemplo de respuesta

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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);

Actualiza un agente

Para actualizar la configuración de un agente existente, envía una solicitud PATCH. Si bien el ID del agente es inmutable, puedes modificar parámetros como instrucciones, herramientas y variables de entorno. Usa el parámetro de consulta update_mask para especificar exactamente qué campos actualizar. Esto garantiza que solo se vean afectados los campos que deseas cambiar y se conserven otras configuraciones.

Actualiza un agente básico

Para actualizar las instrucciones del sistema de un agente, envía una solicitud PATCH con update_mask=system_instruction:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: Es la configuración del agente de destino para actualizar el parche.
  • NEW_INSTRUCTIONS: Es la estructura o descripción de las instrucciones actualizadas que se reemplazarán.

Método HTTP y URL

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

Cuerpo JSON de la solicitud

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

Actualiza un agente con herramientas propias de Google

Para actualizar un agente y habilitar las herramientas propias (1P) de Google (como la fundamentación con la Búsqueda de Google y el contexto de URL), envía una solicitud PATCH con update_mask=tools:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: ID del agente objetivo.

Cuerpo JSON de la solicitud

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

Actualiza un agente con la configuración del MCP

Para modificar las herramientas del MCP adjuntas a tu agente, envía una solicitud PATCH con update_mask=tools:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: ID del agente objetivo.
  • NEW_MCP_SERVER_NAME: Es la etiqueta actualizada de tus herramientas del MCP.
  • NEW_MCP_SERVER_URL: Es el nuevo parámetro del extremo de URL del servidor.
  • NEW_MCP_HEADER_KEY: Opcional Nombre del encabezado para la autenticación (por ejemplo, Authorization).
  • NEW_MCP_HEADER_VALUE: Opcional Token de portador de autenticación (por ejemplo, Bearer <token>)

Cuerpo JSON de la solicitud

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

Cómo adjuntar habilidades a un agente

Para adjuntar o modificar habilidades en base_environment.sources durante una actualización del agente, envía una solicitud PATCH con update_mask=base_environment.

Puedes adjuntar habilidades con cualquiera de los siguientes métodos:

  • Skill Registry: Adjunta una habilidad registrada en tu proyecto en Skill Registry.

  • Google Cloud Storage: Adjunta habilidades personalizadas directamente desde un bucket de Cloud Storage.

Cómo adjuntar una habilidad desde el Registro de habilidades

Para adjuntar una habilidad registrada en el Registro de habilidades, haz lo siguiente:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: ID del agente objetivo.
  • NEW_SKILL_RESOURCE_NAME: Es la ruta de acceso del recurso de la skill o la lista de skills que se activarán. Puedes especificar uno de los siguientes formatos:
    • Habilidad (versión predeterminada): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versión de la skill (fija una versión específica): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (Mount all skills): projects/{projectID}/locations/{location}/skills. Esto activa hasta 100 habilidades en el proyecto o la ubicación en el entorno de zona de pruebas.
    Para obtener más información sobre cómo encontrar el valor de name para NEW_SKILL_RESOURCE_NAME, consulta Cómo enumerar habilidades.
Cuerpo JSON de la solicitud
{
  "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

Cómo adjuntar una habilidad desde Google Cloud Storage

Como alternativa, puedes adjuntar habilidades personalizadas directamente desde un bucket de Cloud Storage cuando crees el agente.

Ten en cuenta los siguientes requisitos cuando montes habilidades desde Cloud Storage:

  • Requisitos de carga: Debes subir toda la carpeta de la skill al bucket.
  • Sin validación de contenido: El backend no valida el contenido de la carpeta antes de la vinculación, sino que se comporta como una carga de carpeta estándar.
  • Límites de tamaño: Todos los archivos adjuntos están sujetos a los límites de memoria del entorno de zona de pruebas (hasta 4 GiB de RAM en total).
  • Prácticas recomendadas: Para obtener una calidad óptima de la skill, estructura y prepara los archivos de la carpeta de la skill según las convenciones que se describen en agentskills.io/home.

Para adjuntar una habilidad desde Google Cloud Storage, haz lo siguiente:

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: ID del agente objetivo.
  • NEW_GCS_SOURCE_PATH: Es la ruta de acceso al bucket de Google Cloud Storage que contiene la carpeta de tu skill (por ejemplo, gs://cymbal-bucket-name/my-skill-folder).
Cuerpo JSON de la solicitud
{
  "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

Borra un agente

Para borrar la configuración de un agente personalizado específico, envía una solicitud DELETE. Esta es una operación de larga duración que borra la configuración de forma permanente.

Cuando borres un agente, proporciona toda la información necesaria en la URL y no incluyas un cuerpo de solicitud JSON.

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente que borras.

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

Ejemplo de respuesta

{
  "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 ejecutar este código, configura las variables que se describen en la pestaña 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 ejecutar este código, configura las variables que se describen en la pestaña 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);

Obtén detalles de una operación de larga duración

Las operaciones como CreateAgent, UpdateAgent y DeleteAgent son asíncronas. La respuesta inicial de la API muestra un campo name que contiene el ID de operación. Usa GetOperation en este ID para sondear el progreso.

REST

Variables de solicitud

Antes de llamar a la API, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación regional de la operación. Solo se admite la región global.
  • OPERATION_ID: Es el ID de operación extraído del campo name en la respuesta inicial de la LRO.

Método HTTP y 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 el acceso a la red

De forma predeterminada, la zona de pruebas inhabilita el acceso a la red cuando creas agentes con la API de Agents. Para permitir el acceso sin restricciones, usa *.

Por ejemplo, usar * en allowlist, como se muestra en el siguiente código, otorga acceso a todos los dominios:

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

¿Qué sigue?

Guía

Aprende a interactuar con los agentes en el tiempo de ejecución, administrar el estado de la sesión y anular la configuración de forma dinámica.