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 Managed Agents en Agent Platform, y cómo configurar el entorno del agente, las herramientas del servidor de Protocolo de contexto del modelo (MCP) y las habilidades.

Antes de comenzar

Antes de configurar tus agentes, configura tu entorno:

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    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

  4. 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 Cloud de Confiance 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 Cloud de Confiance 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 identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    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.
  5. Si planeas usar herramientas del Cloud de Confiance by S3NS Protocolo de contexto del modelo (MCP) con tu agente, otorga el rol de usuario de la herramienta de MCP (roles/mcp.toolUser) tanto a tu cuenta de usuario como a la cuenta de servicio asociada.

Crea un agente

Para crear un agente personalizado nuevo, 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 organización central 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 lado del servicio para la ejecución de código, operaciones del sistema de archivos y 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 activación 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 Cloud de Confiance by S3NS .
  • 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 agente nuevo. 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 perfil que se establecerán en el agente.

  • GCS_BUCKET: Es el segmento de la ruta de acceso de la carpeta de tu bucket de Google Cloud Storage activado (por ejemplo, gs://cymbal-bucket-name). Nota: Para activar un bucket de un proyecto diferente, 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 sin restricciones 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 application-default 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 la Fundamentación 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 Cloud de Confiance by S3NS .
  • 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 agente nuevo. 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 application-default 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 parámetros de configuración de MCP

Puedes crear un agente con herramientas de servidor de MCP preconfiguradas con la API de Managed Agents en Agent Platform.

Antes de comenzar

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

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

  • Confirma que los servidores de MCP de tu configuración se comuniquen a través de HTTP POST estándar para la ejecución y la lista de herramientas. La API de Managed Agents en Agent Platform requiere que los servidores de MCP remotos sean servidores HTTP que admitan transmisión. Los servidores de MCP deben implementar el transporte HTTP transmisible 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 obsoleto (un flujo GET /sse independiente de larga duración).

Autoriza los MCP alojados en Google

Si usas un token del 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 de BigQuery relevantes en tu solicitud.
  2. Valida el acceso: Verifica si se puede acceder al servidor de MCP con tus permisos recién configurados probando el flujo de autorización en OAuth Playground.
  3. Usa encabezados: 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 use el MCP de BigQuery se vería de la siguiente manera:

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

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 Cloud de Confiance by S3NS .
  • 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 agente nuevo. 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 Es el 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 application-default 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",
            },
        },
    ],
});

Adjunta habilidades a un agente

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

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

  • Registro de habilidades: Adjunta una habilidad registrada en tu proyecto en el Registro de habilidades.

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

    Como práctica recomendada, te sugerimos activar las habilidades en la carpeta /.agent/skills del entorno para que el agente las descubra con mayor facilidad.

Habilidades de la CLI

Los desarrolladores también pueden instalar habilidades especializadas en la CLI que elijan para administrar de forma programática los agentes y las interacciones:

Adjunta una habilidad del Registro de habilidades

Para cargar una habilidad reutilizable directamente desde el Registro de habilidades cuando crees el agente, sigue estos pasos:

REST

Variables de solicitud

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

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • 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 agente nuevo. 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 habilidad o la lista de habilidades 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 Lista de 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 application-default 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: "*" }],
        },
    },
});

Adjunta 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 actives habilidades desde Cloud Storage:

  • Requisitos de carga: Debes subir toda la carpeta de habilidades al bucket.
  • No hay validación de contenido: El backend no valida el contenido de la carpeta antes de activarla; 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 las habilidades, estructura y prepara los archivos en tu carpeta de habilidades siguiendo las convenciones descritas en agentskills.io/home.

Para adjuntar una habilidad desde Google Cloud Storage cuando crees el agente, sigue estos pasos:

REST

Variables de solicitud

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

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • 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 agente nuevo. 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 del bucket de Google Cloud Storage que contiene la carpeta de habilidades (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 application-default 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 Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional para enumerar los 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 desde una respuesta ListAgents anterior. Proporciona este token para recuperar la página siguiente de resultados.

Cuando la cantidad de agentes que se mostrarán 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 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 application-default 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 específico, 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 Cloud de Confiance by S3NS .

  • 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 application-default 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, lo que preserva 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 Cloud de Confiance by S3NS .
  • 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 aplicar la actualización de 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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

Actualiza un agente con las 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 Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente de destino.

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 application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

Actualiza un agente con parámetros de configuración de MCP

Para modificar las herramientas de 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 Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente de destino.
  • NEW_MCP_SERVER_NAME: Se actualizó la etiqueta de tus herramientas de MCP.
  • NEW_MCP_SERVER_URL: Es el nuevo parámetro de URL del extremo del servidor.
  • NEW_MCP_HEADER_KEY: Opcional Es el nombre del encabezado para la autenticación (por ejemplo, Authorization).
  • NEW_MCP_HEADER_VALUE: Opcional Es el token del 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 application-default 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

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

  • Registro de habilidades: Adjunta una habilidad registrada en tu proyecto en el Registro de habilidades.

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

Adjunta una habilidad del Registro de habilidades

Para adjuntar una habilidad registrada en el Registro de habilidades, sigue estos pasos:

REST

Variables de solicitud

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

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente de destino.
  • NEW_SKILL_RESOURCE_NAME: Es la ruta de acceso del recurso de la habilidad o la lista de habilidades 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 habilidad (fijar a 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 Enumera 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 application-default 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

Adjunta 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 actives habilidades desde Cloud Storage:

  • Requisitos de carga: Debes subir toda la carpeta de habilidades al bucket.
  • No hay validación de contenido: El backend no valida el contenido de la carpeta antes de activarla; 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 las habilidades, estructura y prepara los archivos en tu carpeta de habilidades siguiendo las convenciones descritas en agentskills.io/home.

Para adjuntar una habilidad desde Google Cloud Storage, sigue estos pasos:

REST

Variables de solicitud

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

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente de destino.
  • NEW_GCS_SOURCE_PATH: Es la ruta de acceso del bucket de Google Cloud Storage que contiene la carpeta de habilidades (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 application-default 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 una configuración de agente personalizada específica, envía una solicitud DELETE. Esta es una operación de larga duración y borra la configuración de forma permanente. Si borras el Agent Runtime, se invalidará su Agent Identity. Cualquier política de acceso unificado (UAP) de IAM que otorgue permisos a esa principal conserva la principal inactiva en sus reglas. Además, la vinculación de política permanece activa. Para quitar una principal que ya no existe, actualiza la UAP para quitar la principal de sus reglas. Si la política ya no contiene principales activas, borra la vinculación de la política.

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 Cloud de Confiance by S3NS .
  • LOCATION: Es la región del agente. Solo se admite la región global.
  • AGENT_ID: Es el ID del agente que borrarás.

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 application-default 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 devuelve un campo name que contiene el ID de la 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 Cloud de Confiance by S3NS .
  • LOCATION: Es la ubicación regional de la operación. Solo se admite la región global.
  • OPERATION_ID: Es el ID de la 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 application-default 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 durante el tiempo de ejecución, administrar el estado de la sesión y anular parámetros de configuración de forma dinámica.