Berinteraksi dengan agen

Panduan ini menjelaskan cara berinteraksi dengan agen yang di-deploy di Managed Agents API di Agent Platform menggunakan Interactions API. Anda akan mempelajari cara berinteraksi dengan agen kustom yang dibuat menggunakan Agents API dan agen dasar Antigravity bawaan, termasuk cara mengonfigurasinya secara dinamis. Panduan ini juga menjelaskan cara mengelola dan menggunakan kembali lingkungan sandbox dengan ID lingkungan (env_id) dan mengganti konfigurasi secara dinamis, misalnya server Model Context Protocol (MCP), selama interaksi.

Untuk mengetahui informasi selengkapnya tentang API, lihat dokumentasi referensi Interaction API.

Sebelum memulai

Sebelum memulai interaksi dengan agen, siapkan lingkungan Anda:

  1. Login keakun Anda. Google Cloud 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.

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

    Roles required to select or create a project

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

    Go to project selector

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

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

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

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

    Roles required to select or create a project

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

    Go to project selector

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

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

    Check for the roles

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

      Go to IAM
    2. Select the project.

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

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

    Grant the roles

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

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

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

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

Berinteraksi dengan agen Antigravity

Cara paling sederhana untuk menggunakan Managed Agents API di Agent Platform adalah berinteraksi langsung dengan agen dasar Antigravity pihak pertama. Anda tidak perlu membuat resource agen kustom; Anda dapat memanggil agen secara langsung.

Untuk memulai interaksi, tentukan target agen dasar, seperti antigravity-preview-05-2026 (atau varian pratinjau terbaru), dan minta lingkungan jarak jauh secara langsung:

REST

Variabel permintaan

Sebelum memanggil API, ganti variabel berikut:

  • PROJECT_ID: Project ID Anda Google Cloud .
  • LOCATION: Lokasi regional untuk interaksi Anda. Hanya region global yang didukung.

Metode HTTP dan URL

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

Meminta isi JSON

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "antigravity-preview-05-2026",
  "environment": {
    "type": "remote"
  },
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Who are you, can you execute python code? Show me an example."
        }
      ]
    }
  ]
}

Perintah curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "antigravity-preview-05-2026",
      "environment": {"type": "remote"},
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Who are you, can you execute python code? Show me an example."
                  }
              ]
          }
      ]
  }'

Contoh respons

Setelah interaksi awal, layanan akan menampilkan respons streaming. interaction.id dan environment_id, yang disertakan dalam data interaction.complete, dapat digunakan dalam panggilan berikutnya untuk mempertahankan status sesi. interaction.id digunakan untuk melanjutkan histori percakapan, sedangkan environment_id memungkinkan penggunaan kembali lingkungan sandbox yang sama. Untuk mengetahui informasi selengkapnya, lihat Mengelola status sesi.

event: interaction.complete
data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 51132,
      "total_input_tokens": 48984,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 48984
        }
      ],
      "total_output_tokens": 769,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 769
        }
      ],
      "total_thought_tokens": 1379
    },
    "created": "2026-05-15T22:26:05Z",
    "updated": "2026-05-15T22:26:05Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

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

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Who are you, can you execute python code? Show me an example.",
    environment={"type": "remote"},
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

Respons streaming menghasilkan objek InteractionSSEEvent. Peristiwa terakhir interaction.complete berisi environment_id dan interaksi id, yang dapat Anda gunakan kembali dalam panggilan berikutnya untuk mempertahankan status sesi dan histori percakapan. Untuk mengetahui informasi selengkapnya, lihat Mengelola status sesi.

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 stream = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Who are you, can you execute python code? Show me an example.",
    environment: { type: "remote" },
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Respons streaming menghasilkan objek peristiwa. Peristiwa terakhir interaction.complete berisi environment_id dan interaksi id, yang dapat Anda gunakan kembali dalam panggilan berikutnya untuk mempertahankan status sesi dan histori percakapan. Untuk mengetahui informasi selengkapnya, lihat Mengelola status sesi.

Berinteraksi dengan agen kustom yang dibuat menggunakan Agents API

Untuk berinteraksi dengan agen kustom yang dibuat seperti yang dijelaskan dalam Membuat dan mengelola agen, Anda harus menentukannya menggunakan ID agennya.

Untuk mengetahui informasi selengkapnya tentang cara mengambil atau mencantumkan agen kustom untuk menemukan ID-nya, lihat Mencantumkan agen.

Konfigurasi dan inisialisasi lingkungan

Saat berinteraksi dengan agen kustom:

  • Perilaku default: Jika Anda membuat agen dengan lingkungan default, tentukan AGENT_ID dalam permintaan Anda.

  • Menentukan lingkungan secara eksplisit: Jika Anda tidak menentukan konfigurasi lingkungan saat membuat agen, Anda harus menentukan lingkungan secara eksplisit di blok environment permintaan interaksi awal.

    Contoh:

    "environment": {"type": "remote"}

Anda dapat mengonfigurasi fitur secara dinamis di lingkungan sandbox selama panggilan API interaksi awal untuk memenuhi persyaratan tugas tertentu. Contoh:

  • Melampirkan kemampuan menggunakan Cloud Storage: Lampirkan bucket Cloud Storage untuk memuat volume data besar atau direktori file persisten ke dalam container sistem file.

  • Melampirkan kemampuan menggunakan Skill Registry: Berikan daftar alat, skrip, atau kemampuan agen yang dikemas sebelumnya untuk menyediakan kemampuan fungsional tertentu atau alur kerja runtime Anda. Lihat Skill Registry.

Untuk mengetahui daftar struktur konfigurasi lingkungan dan contoh cara mempertahankan status percakapan multi-turn, lihat Mengelola status sesi dengan ID lingkungan.

Mengirim interaksi ke agen kustom

Kirim interaksi ke agen kustom Anda dengan menentukan ID agen:

REST

Variabel permintaan

Sebelum memanggil API, ganti variabel berikut:

  • PROJECT_ID: Project ID Anda Google Cloud .
  • LOCATION: Hanya region global yang didukung.
  • AGENT_ID: ID kustom resource agen terdaftar Anda. Untuk mengetahui informasi selengkapnya tentang cara mengambil atau mencantumkan agen kustom untuk menemukan ID-nya, lihat Mencantumkan agen.

Metode HTTP dan URL

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

Meminta isi JSON

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Tell me the name of python packages used for data analysis."
        }
      ]
    }
  ]
}

Perintah curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "Tell me the name of python packages used for data analysis."
                  }
              ]
          }
      ]
  }'

Contoh Respons

Setelah interaksi awal, layanan akan menampilkan respons streaming. interaction.id dan environment_id, yang disertakan dalam data interaction.complete, dapat digunakan dalam panggilan berikutnya untuk mempertahankan status sesi. interaction.id digunakan untuk melanjutkan histori percakapan, sedangkan environment_id memungkinkan penggunaan kembali lingkungan sandbox yang sama. Untuk mengetahui informasi selengkapnya, lihat Mengelola status sesi.

data: {
  "interaction": {
    "id": "1234567890",
    "status": "completed",
    "usage": {
      "total_tokens": 7558,
      "total_input_tokens": 6822,
      "input_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 6822
        }
      ],
      "total_output_tokens": 278,
      "output_tokens_by_modality": [
        {
          "modality": "text",
          "tokens": 278
        }
      ],
      "total_thought_tokens": 458
    },
    "created": "2026-05-15T22:38:56Z",
    "updated": "2026-05-15T22:38:56Z",
    "environment_id": "env_CAE1234567890",
    "object": "interaction"
  },
  "event_type": "interaction.complete"
}

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Tell me the name of python packages used for data analysis.",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

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 stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Tell me the name of python packages used for data analysis.",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Mengelola status sesi dan interaksi multi-turn

Secara default, interaksi tidak memiliki status kecuali jika Anda menargetkan container lingkungan atau histori percakapan tertentu. Dalam alur asisten multi-turn, Anda dapat mempertahankan file lokal, konteks eksekusi kode, modifikasi sistem, library software open source yang diinstal runtime, dan histori percakapan di seluruh percakapan:

  • Untuk melanjutkan percakapan: Teruskan ID dari interaksi sebelumnya ke parameter previous_interaction_id.
  • Untuk terus menggunakan lingkungan yang dibuat: Teruskan ID lingkungan yang ditampilkan dari interaksi sebelumnya ke parameter environment.

Anda dapat memilih konfigurasi lingkungan utama menggunakan parameter berikut di kolom environment:

Struktur JSON Deskripsi
"environment": {"type": "remote"} Menyediakan lingkungan sandbox standar yang baru. Gunakan opsi ini selama interaksi awal.
"environment": "env_CAEQ..." Menggunakan kembali container sandbox persisten yang ada, dengan mempertahankan semua library, skrip, file, dan status yang terkait dengan ID lingkungan ini.
"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]} Menyediakan sandbox jarak jauh baru dan memuatnya terlebih dahulu dengan kemampuan atau file kustom dari `sources` yang ditentukan, seperti yang disimpan di Google Cloud Storage.

Untuk mengirim permintaan interaksi berikutnya yang menggunakan kembali container sandbox yang sama dan melanjutkan percakapan, teruskan environment_id yang ditampilkan di kolom environment dan tentukan previous_interaction_id. Contoh berikut menunjukkan cara melanjutkan sesi stateful saat berinteraksi dengan agen.

REST

Variabel permintaan

Sebelum memanggil API, ganti variabel berikut:

  • PROJECT_ID: Project ID Anda Google Cloud .
  • LOCATION: Hanya region global yang didukung.
  • AGENT_ID: ID kustom resource agen terdaftar Anda (atau antigravity-preview-05-2026).
  • PREVIOUS_INTERACTION_ID: ID interaksi yang ditampilkan dari interaksi sebelumnya.
  • ENV_ID: ID lingkungan yang ditampilkan dari interaksi sebelumnya.

Metode HTTP dan URL

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

Meminta isi JSON

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "AGENT_ID",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "environment": "ENV_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "What did I ask you before and what did you do?"
        }
      ]
    }
  ]
}

Perintah curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "stream": true,
      "background": true,
      "store": true,
      "agent": "AGENT_ID",
      "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
      "environment": "ENV_ID",
      "input": [
          {
              "type": "user_input",
              "content": [
                  {
                      "type": "text",
                      "text": "What did I ask you before and what did you do?"
                  }
              ]
          }
      ]
  }'

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

stream = client.interactions.create(
    agent="AGENT_ID",
    input="What did I ask you before and what did you do?",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    environment="ENV_ID",
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

Di Python SDK, teruskan string environment_id secara langsung sebagai parameter environment untuk menggunakan kembali container sandbox yang ada. Gunakan previous_interaction_id untuk melanjutkan histori percakapan.

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 stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "What did I ask you before and what did you do?",
    previous_interaction_id: "PREVIOUS_INTERACTION_ID",
    environment: "ENV_ID",
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Di JavaScript SDK, teruskan string environment_id secara langsung sebagai parameter environment untuk menggunakan kembali container sandbox yang ada. Gunakan previous_interaction_id untuk melanjutkan histori percakapan.

Mengganti konfigurasi selama interaksi

Meskipun definisi agen kustom biasanya menyertakan konfigurasi default untuk alat, kemampuan, dan koneksi pihak ketiga, Anda dapat menyesuaikan definisi ini secara dinamis berdasarkan per interaksi tanpa mengubah konfigurasi resource agen yang mendasarinya.

Kasus penggunaan umum adalah mengganti koneksi secara dinamis ke server Model Context Protocol (MCP) saat runtime. Alat atau server MCP apa pun yang ditentukan dalam isi permintaan interaksi akan sepenuhnya mengganti alat yang telah dikonfigurasi sebelumnya oleh agen selama durasi interaksi tersebut.

Untuk mengganti atau menentukan server MCP pada waktu interaksi, tambahkan alat jenis mcp_server di dalam daftar tools permintaan interaksi Anda:

REST

Variabel permintaan

Sebelum memanggil API, ganti variabel berikut:

  • PROJECT_ID: Project ID Anda Google Cloud .
  • LOCATION: Lokasi untuk interaksi Anda. Hanya region global yang didukung.
  • AGENT_ID: ID kustom resource agen Anda.
  • MCP_SERVER_URL: URL gateway HTTP jarak jauh server MCP baru.
  • MCP_SERVER_NAME: Label deskriptif untuk domain host MCP target.
  • MCP_HEADER_KEY: Opsional. Nama kunci header (misalnya, Authorization).
  • MCP_HEADER_VALUE: Opsional. Nilai kredensial (misalnya, Bearer <token>).

Metode HTTP dan URL

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

Meminta isi JSON

{
  "stream": true,
  "background": true,
  "store": true,
  "agent": "agents/AGENT_ID",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Analyze our database and summarize recent purchase events."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp_server",
      "url": "MCP_SERVER_URL",
      "name": "MCP_SERVER_NAME",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

Perintah curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
     "stream": true,
     "background": true,
     "store": true,
     "agent": "agents/AGENT_ID",
     "input": [
         {
             "type": "user_input",
             "content": [
                 {
                     "type": "text",
                     "text": "Analyze our database and summarize recent purchase events."
                 }
             ]
         }
     ],
     "tools": [
         {
             "type": "mcp_server",
             "url": "MCP_SERVER_URL",
             "name": "MCP_SERVER_NAME",
             "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",
)

stream = client.interactions.create(
    agent="AGENT_ID",
    input="Analyze our database and summarize recent purchase events.",
    tools=[
        {
            "type": "mcp_server",
            "url": "MCP_SERVER_URL",
            "name": "MCP_SERVER_NAME",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
    stream=True,
    background=True,
    store=True,
)

for event in stream:
    print(event)

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 stream = await client.interactions.create({
    agent: "AGENT_ID",
    input: "Analyze our database and summarize recent purchase events.",
    tools: [
        {
            type: "mcp_server",
            url: "MCP_SERVER_URL",
            name: "MCP_SERVER_NAME",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
    stream: true,
    background: true,
    store: true,
});

for await (const event of stream) {
    console.log(event);
}

Langkah berikutnya

Ringkasan

Pelajari Managed Agents API di Agent Platform, lingkungan berbasis konfigurasi dan REST-first untuk membangun agen otonom.

Referensi

Pelajari container sandbox terisolasi, izin, dan paket/alat yang telah diinstal sebelumnya.