Membuat dan mengelola agen

Panduan ini menjelaskan cara membuat, mengambil, mencantumkan, memperbarui, dan menghapus resource agen kustom yang menggunakan Managed Agents API di Agent Platform, serta cara mengonfigurasi lingkungan agen, alat server Model Context Protocol (MCP), dan keterampilan.

Sebelum memulai

Sebelum mengonfigurasi agen, siapkan lingkungan Anda:

  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. Jika Anda berencana menggunakan alat Cloud de Confiance by S3NS Model Context Protocol (MCP) dengan agen Anda, berikan peran MCP Tool User (roles/mcp.toolUser) ke akun pengguna Anda dan akun layanan terkait.

Buat agen

Untuk membuat agen kustom baru, gunakan metode CreateAgent. Ini adalah operasi yang berjalan lama.

Agen dasar

base_agent adalah harness orkestrasi inti yang memberi agen kemampuan penalaran dan akses ke lingkungan eksekusi. Agen ini dapat memasukkan keterampilan dan library ke dalam lingkungan dan memiliki akses ke alat sisi layanan untuk eksekusi kode, operasi sistem file, dan penelusuran dengan grounding.

Saat membuat agen, hanya satu nilai yang didukung untuk base_agent: antigravity-preview-05-2026.

Membuat agen dasar

Untuk membuat agen dasar dengan alat default dan target pemasangan Google Cloud Storage, kirim permintaan POST:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.

  • AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen kustom harus mematuhi batasan berikut:

    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.

  • BASE_AGENT: Nama agen dasar yang akan diperluas. Gunakan antigravity-preview-05-2026.

  • AGENT_DESCRIPTION: Ringkasan singkat cakupan agen.

  • INSTRUCTIONS: Petunjuk sistem atau persona yang akan ditetapkan pada agen.

  • GCS_BUCKET: Segmen jalur folder dari bucket Google Cloud Storage yang di-mount (misalnya, gs://cymbal-bucket-name). Catatan: Untuk memasang bucket dari project lain, beri akun layanan project akses read dan write ke bucket.

  • network: Untuk alasan keamanan, akses jaringan di lingkungan dinonaktifkan. Anda harus menentukan allowlist untuk mengaktifkan akses. Menggunakan * sebagai domain di allowlist memungkinkan koneksi ke semua domain, sehingga memberikan akses jaringan tanpa batas.

Metode HTTP dan URL

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

Isi JSON permintaan

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

curl perintah

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

Contoh Respons

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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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: "*" }],
        },
    },
});

Membuat agen dengan alat pihak pertama Google

Untuk membuat agen dengan alat pihak pertama Google (seperti Grounding dengan Google Search dan konteks URL), tambahkan alat ini ke daftar tools dalam konfigurasi agen:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.

  • AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen kustom harus mematuhi batasan berikut:

    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.

  • AGENT_DESCRIPTION: Ringkasan singkat cakupan agen.

Isi JSON permintaan

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

curl perintah

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

Membuat agen dengan konfigurasi MCP

Anda dapat membuat agen dengan alat server MCP yang telah dikonfigurasi sebelumnya menggunakan Managed Agents API di Agent Platform.

Sebelum memulai

Sebelum membuat agen dengan alat server MCP yang telah dikonfigurasi sebelumnya, lakukan hal berikut:

  • Berikan peran Identity and Access Management (IAM) MCP Tool User (roles/mcp.toolUser) ke akun pengguna Anda dan akun layanan terkait.

  • Pastikan server MCP dalam konfigurasi Anda berkomunikasi melalui HTTP POST standar untuk listingan dan eksekusi alat. Managed Agents API di Agent Platform mengharuskan server MCP jarak jauh berupa server HTTP yang dapat di-streaming. Server MCP harus mengimplementasikan transpor HTTP MCP yang Dapat Di-streaming), dengan tools/list dan tools/call dikirim sebagai JSON-RPC melalui HTTP POST.

    Transportasi HTTP+SSE dua endpoint yang tidak digunakan lagi (aliran GET /sse berumur panjang yang terpisah) tidak didukung.

Memberikan otorisasi pada MCP yang dihosting oleh Google

Jika Anda menggunakan token pemilik untuk otorisasi server MCP yang dihosting oleh Google (seperti BigQuery), selesaikan langkah-langkah berikut:

  1. Tambahkan Cakupan OAuth: Tambahkan cakupan OAuth 2.0 yang diperlukan ke token autentikasi Anda. Misalnya, untuk menggunakan BigQuery MCP, sertakan cakupan BigQuery yang relevan dalam permintaan Anda.
  2. Validasi Akses: Pastikan server MCP dapat diakses dengan cakupan yang baru dikonfigurasi dengan menguji alur otorisasi di OAuth Playground.
  3. Gunakan Header: Untuk MCP Google seperti BigQuery, Anda harus menyertakan header X-Goog-User-Project yang ditetapkan ke nama project Anda di peta headers.

Misalnya, isi JSON permintaan yang digunakan untuk membuat agen yang menggunakan BigQuery MCP akan terlihat seperti berikut:

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

Membuat agen

Untuk membuat agen dengan alat server MCP yang telah dikonfigurasi sebelumnya, tambahkan detail di bagian tools:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.

  • AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen kustom harus mematuhi batasan berikut:

    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.

  • AGENT_DESCRIPTION: Ringkasan singkat cakupan agen.

  • MCP_SERVER_NAME: Nama deskriptif untuk alat MCP.

  • MCP_SERVER_URL: URL gateway HTTP jarak jauh server MCP.

  • MCP_HEADER_KEY: Opsional. Nama header untuk autentikasi (misalnya, Authorization).

  • MCP_HEADER_VALUE: Opsional. Token pemilik autentikasi (misalnya, Bearer <token>).

Isi JSON permintaan

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

curl perintah

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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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",
            },
        },
    ],
});

Menambahkan keahlian ke agen

Untuk memuat keterampilan yang dapat digunakan kembali secara langsung saat membuat agen, pasang keterampilan tersebut di dalam base_environment.sources.

Anda dapat melampirkan keterampilan menggunakan salah satu metode berikut:

  • Registry Keahlian: Lampirkan keahlian yang terdaftar dalam project Anda di Registry Keahlian.

  • Google Cloud Storage: Lampirkan keahlian kustom langsung dari bucket Cloud Storage.

    Sebagai praktik terbaik, sebaiknya pasang skill di folder /.agent/skills dalam lingkungan agar lebih mudah ditemukan oleh agen.

Keterampilan CLI

Developer juga dapat menginstal keterampilan khusus di CLI pilihan mereka untuk mengelola agen dan interaksi secara terprogram:

Melampirkan keahlian dari Registry Keahlian

Untuk memuat keahlian yang dapat digunakan kembali langsung dari Skill Registry saat membuat agen:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.
  • AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen Kustom harus mematuhi batasan berikut:
    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.
  • SKILL_RESOURCE_NAME: Jalur resource kemampuan atau daftar kemampuan yang akan dipasang. Anda dapat menentukan salah satu format berikut:
    • Skill (versi default): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versi tertentu: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • Daftar keterampilan: projects/{projectID}/locations/{location}/skills. Tindakan ini akan memasang hingga 100 keterampilan dari project/location yang ditentukan ke dalam lingkungan sandbox.
    Untuk mengetahui informasi selengkapnya, lihat daftar keterampilan.
Isi JSON permintaan
{
  "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": "*" }
      ]
    }
  }
}
curl perintah
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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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: "*" }],
        },
    },
});

Melampirkan keahlian dari Google Cloud Storage

Atau, Anda dapat melampirkan keahlian kustom langsung dari bucket Cloud Storage Google saat membuat agen.

Perhatikan persyaratan berikut saat memasang skill dari Cloud Storage:

  • Persyaratan upload: Anda harus mengupload seluruh folder skill ke bucket.
  • Tidak ada validasi konten: Backend tidak memvalidasi konten folder sebelum memasang; backend berperilaku seperti upload folder standar.
  • Batas ukuran: Semua file yang dilampirkan tunduk pada batas memori lingkungan sandbox (total hingga 4 GiB RAM).
  • Praktik terbaik: Untuk kualitas keahlian yang optimal, susun dan siapkan file di folder keahlian Anda sesuai dengan konvensi yang dijelaskan di agentskills.io/home.

Untuk melampirkan skill dari Google Cloud Storage saat membuat agen:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.
  • AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen Kustom harus mematuhi batasan berikut:
    • Harus terdiri dari 1 hingga 63 karakter.
    • Hanya boleh berisi huruf kecil, angka, dan tanda hubung.
    • Harus diawali dengan huruf dan diakhiri dengan huruf atau angka.
  • GCS_SOURCE_PATH: Jalur bucket Google Cloud Storage yang berisi folder skill Anda (misalnya, gs://cymbal-bucket-name/my-skill-folder).
Isi JSON permintaan
{
  "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": "*" }
      ]
    }
  }
}
curl perintah
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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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: "*" }],
        },
    },
});

Mencantumkan agen

Untuk mencantumkan semua agen yang disimpan di project Anda, kirim permintaan GET. Anda dapat menggunakan penomoran halaman opsional untuk mengontrol jumlah hasil per halaman.

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional untuk mencantumkan agen. Hanya region global yang didukung.
  • PAGE_SIZE: Opsional. Jumlah maksimum agen yang akan ditampilkan per halaman. Nilai defaultnya adalah 10, dan nilai maksimumnya adalah 100.
  • PAGE_TOKEN: Opsional. Token halaman, yang diterima dari respons ListAgents sebelumnya. Berikan token ini untuk mengambil halaman hasil berikutnya.

Jika jumlah agen yang akan ditampilkan lebih besar dari PAGE_SIZE, respons ListAgents akan menyertakan kolom nextPageToken. Untuk mengambil halaman agen berikutnya, teruskan nilai nextPageToken ini sebagai parameter PAGE_TOKEN dalam permintaan ListAgents berikutnya. Ulangi proses ini hingga kolom nextPageToken tidak lagi ditampilkan dalam respons.

Metode HTTP dan URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

curl perintah

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

Contoh Respons

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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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);
    }
}

Mendapatkan agen

Untuk mengambil konfigurasi lengkap agen yang ditentukan, gunakan permintaan GET.

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.

  • LOCATION: Lokasi regional untuk agen Anda. Hanya region global yang didukung.

  • AGENT_ID: ID unik konfigurasi agen kustom yang Anda minta.

Metode HTTP dan URL

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

curl perintah

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

Contoh Respons

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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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);

Memperbarui agen

Untuk memperbarui konfigurasi agen yang ada, kirim permintaan PATCH. Meskipun ID agen tidak dapat diubah, Anda dapat mengubah parameter seperti petunjuk, alat, dan variabel lingkungan. Gunakan parameter kueri update_mask untuk menentukan dengan tepat kolom mana yang akan diperbarui. Hal ini memastikan bahwa hanya kolom yang ingin Anda ubah yang terpengaruh, sehingga konfigurasi lainnya tetap dipertahankan.

Memperbarui agen dasar

Untuk memperbarui petunjuk sistem agen, kirim permintaan PATCH dengan update_mask=system_instruction:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional agen. Hanya region global yang didukung.
  • AGENT_ID: Konfigurasi agen target untuk update patch.
  • NEW_INSTRUCTIONS: Struktur atau deskripsi petunjuk yang diperbarui untuk diganti.

Metode HTTP dan URL

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

Isi JSON permintaan

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

curl perintah

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

Mengupdate agen dengan alat pihak pertama Google

Untuk mengupdate agen agar mengaktifkan alat pihak pertama (1P) Google (seperti Grounding with Google Search dan Konteks URL), kirim permintaan PATCH dengan update_mask=tools:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional agen. Hanya region global yang didukung.
  • AGENT_ID: ID agen target.

Isi JSON permintaan

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

curl perintah

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

Mengupdate agen dengan konfigurasi MCP

Untuk mengubah alat MCP yang terpasang pada agen Anda, kirim permintaan PATCH dengan update_mask=tools:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional agen. Hanya region global yang didukung.
  • AGENT_ID: ID agen target.
  • NEW_MCP_SERVER_NAME: Label yang diperbarui untuk alat MCP Anda.
  • NEW_MCP_SERVER_URL: Parameter endpoint URL baru server.
  • NEW_MCP_HEADER_KEY: Opsional. Nama header untuk autentikasi (misalnya, Authorization).
  • NEW_MCP_HEADER_VALUE: Opsional. Token pemilik autentikasi (misalnya, Bearer <token>).

Isi JSON permintaan

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

curl perintah

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

Menambahkan keahlian ke agen

Untuk melampirkan atau mengubah keterampilan dalam base_environment.sources selama update agen, kirim permintaan PATCH menggunakan update_mask=base_environment.

Anda dapat melampirkan keterampilan menggunakan salah satu metode berikut:

  • Registry Keahlian: Lampirkan keahlian yang terdaftar dalam project Anda di Registry Keahlian.

  • Google Cloud Storage: Lampirkan keahlian kustom langsung dari bucket Cloud Storage.

Melampirkan keahlian dari Registry Keahlian

Untuk melampirkan keahlian yang terdaftar di Skill Registry:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional agen. Hanya region global yang didukung.
  • AGENT_ID: ID agen target.
  • NEW_SKILL_RESOURCE_NAME: Jalur resource keterampilan atau daftar keterampilan yang akan dipasang. Anda dapat menentukan salah satu format berikut:
    • Skill (versi default): projects/{projectID}/locations/{location}/skills/{skillName}
    • Versi skill (Sematkan ke versi tertentu): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ListSkills (Memasang semua keterampilan): projects/{projectID}/locations/{location}/skills. Tindakan ini akan memasang hingga 100 keterampilan dalam project/lokasi ke lingkungan sandbox.
    Untuk mengetahui informasi selengkapnya tentang cara menemukan nilai name untuk NEW_SKILL_RESOURCE_NAME, lihat Mencantumkan keterampilan.
Isi JSON permintaan
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl perintah
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

Melampirkan keterampilan dari Google Cloud Storage

Atau, Anda dapat melampirkan keahlian kustom langsung dari bucket Cloud Storage Google saat membuat agen.

Perhatikan persyaratan berikut saat memasang skill dari Cloud Storage:

  • Persyaratan upload: Anda harus mengupload seluruh folder skill ke bucket.
  • Tidak ada validasi konten: Backend tidak memvalidasi konten folder sebelum memasang; backend berperilaku seperti upload folder standar.
  • Batas ukuran: Semua file yang dilampirkan tunduk pada batas memori lingkungan sandbox (total hingga 4 GiB RAM).
  • Praktik terbaik: Untuk kualitas keahlian yang optimal, susun dan siapkan file di folder keahlian Anda sesuai dengan konvensi yang dijelaskan di agentskills.io/home.

Untuk melampirkan keterampilan dari Google Cloud Storage:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional agen. Hanya region global yang didukung.
  • AGENT_ID: ID agen target.
  • NEW_GCS_SOURCE_PATH: Jalur bucket Google Cloud Storage yang berisi folder skill Anda (misalnya, gs://cymbal-bucket-name/my-skill-folder).
Isi JSON permintaan
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
curl perintah
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

Menghapus agen

Untuk menghapus konfigurasi agen kustom tertentu, kirim permintaan DELETE. Ini adalah operasi yang berjalan lama dan menghapus konfigurasi secara permanen. Menghapus runtime agen akan membatalkan validitas identitas agennya. Setiap Unified Access Policy (UAP) IAM yang memberikan izin kepada akun utama tersebut akan mempertahankan akun utama yang tidak aktif dalam aturannya. Selain itu, binding kebijakan tetap aktif. Untuk menghapus akun utama yang tidak berfungsi, perbarui UAP untuk menghapus akun utama dari aturannya. Jika kebijakan tidak lagi berisi akun utama yang aktif, hapus binding kebijakan.

Saat Anda menghapus agen, berikan semua informasi yang diperlukan di URL dan jangan sertakan isi permintaan JSON.

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Region agen. Hanya region global yang didukung.
  • AGENT_ID: ID agen yang Anda hapus.

Metode HTTP dan URL

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

curl perintah

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

Contoh Respons

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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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

Sebelum menjalankan kode ini, tetapkan variabel yang dijelaskan di tab 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);

Mendapatkan detail operasi yang berjalan lama

Operasi seperti CreateAgent, UpdateAgent, dan DeleteAgent bersifat asinkron. Respons API awal menampilkan kolom name yang berisi ID operasi. Gunakan GetOperation pada ID ini untuk melakukan polling progres.

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
  • LOCATION: Lokasi regional operasi. Hanya region global yang didukung.
  • OPERATION_ID: ID operasi yang diekstrak dari kolom name dalam respons LRO awal.

Metode HTTP dan URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

curl perintah

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

Mengonfigurasi akses jaringan

Secara default, sandbox menonaktifkan akses jaringan saat Anda membuat agen menggunakan Agents API. Untuk mengizinkan akses tanpa batas, gunakan *.

Misalnya, menggunakan * di allowlist seperti yang ditunjukkan dalam kode berikut akan memberikan akses ke semua domain:

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

Langkah berikutnya

Panduan

Pelajari cara berinteraksi dengan agen saat runtime, mengelola status sesi, dan mengganti konfigurasi secara dinamis.