Crear y administrar agentes

Este producto es una oferta previa a la DG, sujeta a las "Condiciones de las Ofertas Previas a la DG" en la sección de Condiciones Generales del Servicio de las Condiciones Específicas del Servicio, las condiciones de los "Servicios de IA de agentes" en las Condiciones Específicas del Servicio y las Condiciones Adicionales para Productos de IA Generativa en Versión Preliminar. Los productos y las características anteriores a la DG pueden tener asistencia limitada, y los cambios en estos productos y características podrían no ser compatibles con otras versiones a la fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Estos productos en fase previa a la DG se encuentran en varias etapas de pruebas y revisiones internas. Por lo tanto, no uses datos confidenciales, sensibles ni de propiedad exclusiva con estos productos. Estos productos se ponen a disposición de los Clientes solo para pruebas y evaluaciones limitadas, y no se pueden usar con fines comerciales ni de producción.

Para ver un ejemplo de cómo crear y administrar agentes, ejecuta el notebook “Introducción a los agentes administrados en Python” en uno de los siguientes entornos:

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

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

Nota: El uso del modelo durante la versión preliminar se factura según las tarifas estándar. Para obtener más información, consulta la página de precios.

Requisitos previos

Antes de configurar tus agentes, completa los siguientes pasos:

• En la consola de Google Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .

• Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

• Habilita la API de Gemini Enterprise Agent Platform (aiplatform.googleapis.com) en tu proyecto.

• Asegúrate de tener uno de los siguientes roles:

  • aiplatform.user: Proporciona permisos para interactuar con los recursos de AI Platform.
  • aiplatform.admin: Proporciona control total sobre los recursos de AI Platform, incluidas las tareas administrativas.

Crea un agente

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

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

• 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 Cloud Storage de Google que se activó (por ejemplo, gs://cymbal-bucket-name).

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

Comando curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

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 de origen 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 para 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

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

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 para 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 Es el token del 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 descubrir con mayor facilidad.

Cómo adjuntar una habilidad desde Skill Registry

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 para 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; 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 para 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 para enumerar agentes. 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 devolverán es mayor que PAGE_SIZE, la respuesta de 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 devuelva 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

Nota: El método update aún no está disponible en el SDK de Python. Usa la API de REST para actualizar agentes.

JavaScript

Nota: El método update aún no está disponible en el SDK de JavaScript. Usa la API de REST para actualizar agentes.

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

Nota: El método update aún no está disponible en el SDK de Python. Usa la API de REST para actualizar agentes.

JavaScript

Nota: El método update aún no está disponible en el SDK de JavaScript. Usa la API de REST para actualizar agentes.

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

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

Nota: El método update aún no está disponible en el SDK de Python. Usa la API de REST para actualizar las habilidades del agente.

JavaScript

Nota: El método update aún no está disponible en el SDK de JavaScript. Usa la API de REST para actualizar las habilidades del agente.

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

Nota: El método update aún no está disponible en el SDK de Python. Usa la API de REST para actualizar las habilidades del agente.

JavaScript

Nota: El método update aún no está disponible en el SDK de JavaScript. Usa la API de REST para actualizar las habilidades del agente.

Borra un agente

Para borrar una configuración de agente personalizada específica, envía una solicitud de 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

Nota: Cuando usas el SDK de Python, las operaciones como agents.create() y agents.delete() devuelven el resultado final directamente. Usa client.agents.get(id="AGENT_ID") para verificar el estado del aprovisionamiento.

JavaScript

Nota: Cuando se usa el SDK de JavaScript, las operaciones como agents.create() y agents.delete() devuelven el resultado final directamente. Usa client.agents.get("AGENT_ID") para verificar el estado del aprovisionamiento.

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

Interactúa con agentes

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.