Membuat dan mengelola agen

Produk ini adalah penawaran Pra-GA, yang tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan, persyaratan "Layanan AI Agentik" dalam Persyaratan Khusus Layanan, dan Persyaratan Tambahan untuk Produk Pratinjau AI Generatif. Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Produk pra-GA ini berada dalam berbagai tahap pengujian dan peninjauan internal. Oleh karena itu, jangan gunakan data eksklusif, sensitif, atau rahasia lainnya dengan produk ini. Produk ini disediakan untuk Pelanggan hanya untuk pengujian dan evaluasi terbatas, dan tidak boleh digunakan untuk tujuan komersial atau produksi.

Untuk melihat contoh pembuatan dan pengelolaan agen, jalankan notebook "Pengantar Agen Terkelola di Python" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di Agent Platform Workbench | Lihat di GitHub

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

Catatan: Penggunaan model selama pratinjau ditagih dengan tarif standar. Untuk mengetahui informasi selengkapnya, lihat halaman harga.

Sebelum memulai

Sebelum mengonfigurasi agen, siapkan lingkungan Anda:

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API
Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)
Check for the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

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

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.

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

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

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

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

Roles required to select or create a project

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

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

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

Enable the API

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

Check for the roles

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

   Go to IAM
2. Select the project.

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

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

Grant the roles

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

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

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

5. Click Select a role, then search for the role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.
1. Jika Anda berencana menggunakan alat Google Cloud Model Context Protocol (MCP) dengan agen Anda, berikan peran Pengguna Alat MCP (roles/mcp.toolUser) ke akun pengguna dan akun layanan terkait.

Buat agen

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

Catatan: Selama periode Pratinjau, penyediaan agen pertama dalam project Anda dapat memerlukan waktu antara dua hingga tiga menit. Agen berikutnya biasanya disediakan dalam waktu dua hingga tiga detik.

Agen dasar

base_agent adalah harness orkestrasi inti yang menyediakan kemampuan penalaran dan akses ke lingkungan eksekusi bagi agen. Fitur ini dapat menyuntikkan kemampuan dan library ke dalam lingkungan dan memiliki akses ke alat sisi layanan untuk eksekusi kode, operasi sistem file, dan penelusuran dengan perujukan.

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 Google Cloud Anda.
• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah global yang didukung.

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

  • Panjangnya harus 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: Instruksi 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 me-mount bucket dari project lain, berikan akses read dan write akun layanan project 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 batasan.

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 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 Perujukan dengan Google Penelusuran 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 Google Cloud Anda.
• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah global yang didukung.

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

  • Panjangnya harus 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 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) Pengguna Alat MCP (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 mewajibkan server MCP jarak jauh menjadi server HTTP yang Dapat Di-streaming. Server MCP harus menerapkan transpor HTTP yang dapat di-streaming MCP), 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 yang terpisah dan berjalan lama) 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: Verifikasi apakah 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 mirip dengan 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://mcp-bigquery.googleapis.com/v1",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

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 Google Cloud Anda.
• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah global yang didukung.

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

  • Panjangnya harus 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 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",
            },
        },
    ],
});

Menyematkan keterampilan ke agen

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

Anda dapat melampirkan keterampilan menggunakan salah satu metode berikut:

• Skill Registry: Lampirkan skill yang terdaftar dalam project Anda di Skill Registry.

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

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

Keterampilan CLI

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

• Keterampilan Agents API
• Keterampilan Interaction API

Melampirkan keahlian dari Registry Keahlian

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

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah global yang didukung.
• AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen Kustom harus mematuhi batasan berikut:
  • Panjangnya harus 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 keterampilan atau daftar keterampilan yang akan di-mount. 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 memasang hingga 100 skill dari project/location yang ditentukan ke lingkungan sandbox.
  Untuk mengetahui informasi selengkapnya, lihat daftar kemampuan.

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 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 skill dari Google Cloud Storage

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

Perhatikan persyaratan berikut saat memasang keterampilan dari Cloud Storage:

• Persyaratan upload: Anda harus mengupload seluruh folder keterampilan ke bucket.
• Tidak ada validasi konten: Backend tidak memvalidasi konten folder sebelum dipasang; berperilaku seperti upload folder standar.
• Batas ukuran: Semua file terlampir tunduk pada batas memori lingkungan sandbox (total hingga 4 GiB RAM).
• Praktik terbaik: Untuk kualitas skill yang optimal, susun dan siapkan file di folder skill Anda dengan mengikuti 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 Google Cloud Anda.
• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah global yang didukung.
• AGENT_ID: ID kustom unik untuk agen baru Anda. ID Agen Kustom harus mematuhi batasan berikut:
  • Panjangnya harus 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 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 tersimpan 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 Google Cloud Anda.
• LOCATION: Lokasi regional untuk mencantumkan agen. Hanya wilayah 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 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 tertentu, gunakan permintaan GET.

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda.

• LOCATION: Lokasi regional untuk agen Anda. Hanya wilayah 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 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 Google Cloud Anda.
• LOCATION: Lokasi regional agen. Hanya wilayah 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 print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

Catatan: Metode update belum tersedia di Python SDK. Gunakan REST API untuk memperbarui agen.

JavaScript

Catatan: Metode update belum tersedia di JavaScript SDK. Gunakan REST API untuk memperbarui agen.

Memperbarui agen dengan alat pihak pertama Google

Untuk memperbarui agen agar dapat menggunakan 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 Google Cloud Anda.
• LOCATION: Lokasi regional agen. Hanya wilayah 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 print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

Mengupdate agen dengan konfigurasi MCP

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

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• LOCATION: Lokasi regional agen. Hanya wilayah global yang didukung.
• AGENT_ID: ID agen target.
• NEW_MCP_SERVER_NAME: Label alat MCP yang diperbarui.
• 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 bearer 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 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

Catatan: Metode update belum tersedia di Python SDK. Gunakan REST API untuk memperbarui agen.

JavaScript

Catatan: Metode update belum tersedia di JavaScript SDK. Gunakan REST API untuk memperbarui agen.

Menyematkan keterampilan 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:

• Skill Registry: Lampirkan skill yang terdaftar dalam project Anda di Skill Registry.

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

Melampirkan keahlian dari Registry Keahlian

Untuk melampirkan skill yang terdaftar di Registry Skill:

REST

Variabel permintaan

Sebelum memanggil API, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• LOCATION: Lokasi regional agen. Hanya wilayah global yang didukung.
• AGENT_ID: ID agen target.
• NEW_SKILL_RESOURCE_NAME: Jalur resource skill atau daftar skill yang akan di-mount. 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 (Mount all skills): projects/{projectID}/locations/{location}/skills. Tindakan ini memasang hingga 100 skill dalam project/lokasi ke lingkungan sandbox.
  Untuk mengetahui informasi selengkapnya tentang cara menemukan nilai name untuk NEW_SKILL_RESOURCE_NAME, lihat Keterampilan daftar.

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

Catatan: Metode update belum tersedia di Python SDK. Gunakan REST API untuk memperbarui keterampilan agen.

JavaScript

Catatan: Metode update belum tersedia di JavaScript SDK. Gunakan REST API untuk memperbarui keterampilan agen.

Melampirkan skill dari Google Cloud Storage

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

Perhatikan persyaratan berikut saat memasang keterampilan dari Cloud Storage:

• Persyaratan upload: Anda harus mengupload seluruh folder keterampilan ke bucket.
• Tidak ada validasi konten: Backend tidak memvalidasi konten folder sebelum dipasang; berperilaku seperti upload folder standar.
• Batas ukuran: Semua file terlampir tunduk pada batas memori lingkungan sandbox (total hingga 4 GiB RAM).
• Praktik terbaik: Untuk kualitas skill yang optimal, susun dan siapkan file di folder skill Anda dengan mengikuti 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 Google Cloud Anda.
• LOCATION: Lokasi regional agen. Hanya wilayah 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 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

Catatan: Metode update belum tersedia di Python SDK. Gunakan REST API untuk memperbarui keterampilan agen.

JavaScript

Catatan: Metode update belum tersedia di JavaScript SDK. Gunakan REST API untuk memperbarui keterampilan agen.

Menghapus agen

Untuk menghapus konfigurasi agen kustom tertentu, kirim permintaan DELETE. Tindakan ini adalah operasi yang berjalan lama dan menghapus konfigurasi secara permanen.

Saat 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 Google Cloud Anda.
• LOCATION: Region agen. Hanya wilayah 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 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 Google Cloud Anda.
• LOCATION: Lokasi regional operasi. Hanya wilayah 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 print-access-token)"

Python

Catatan: Saat menggunakan Python SDK, operasi seperti agents.create() dan agents.delete() menampilkan hasil akhir secara langsung. Gunakan client.agents.get(id="AGENT_ID") untuk memverifikasi status penyediaan.

JavaScript

Catatan: Saat menggunakan JavaScript SDK, operasi seperti agents.create() dan agents.delete() menampilkan hasil akhir secara langsung. Gunakan client.agents.get("AGENT_ID") untuk memverifikasi status penyediaan.

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

Berinteraksi dengan agen

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