Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

與代理程式互動

本指南說明如何使用 Interactions API，在 Agent Platform 的 Managed Agents API 中與已部署的代理程式互動。您將瞭解如何與使用 Agents API 和預先建構的 Antigravity 基礎代理程式建構的自訂代理程式互動，包括動態設定。此外，本文也會說明如何使用環境 ID (env_id) 管理及重複使用沙箱環境，以及如何在互動期間動態覆寫設定，例如 Model Context Protocol (MCP) 伺服器。

如要進一步瞭解 API，請參閱「Interaction API」參考資料說明文件。

事前準備

與代理程式互動前，請先設定環境：

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access.
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role, then search for the role.
To grant additional roles, click Add another role and add each additional role.
Click Save.

如果代理程式使用 Google Cloud Model Context Protocol (MCP) 工具，請將 MCP 工具使用者 (roles/mcp.toolUser) 角色授予使用者帳戶和相關聯的服務帳戶。

與 Antigravity 代理互動

如要在 Agent Platform 上使用 Managed Agents API，最簡單的方式是直接與第一方 Antigravity 基礎代理互動。您不需要建立自訂代理資源，即可即時叫用代理。

如要啟動互動，請指定基礎代理目標，例如 antigravity-preview-05-2026 (或最新預覽變體)，並要求即時遠端環境：

REST

要求變數

呼叫 API 前，請先替換下列變數：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：互動的區域位置。僅支援 global 區域。

HTTP 方法和網址

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

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

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

回覆範例

在初始互動後，服務會傳回串流回應。後續呼叫可以使用 interaction.complete 資料中包含的 interaction.id 和 environment_id，維持工作階段狀態。interaction.id 可用於延續對話記錄，environment_id 則可重複使用相同的沙箱環境。詳情請參閱「管理工作階段狀態」。

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

執行這段程式碼前，請先設定「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)

串流回應會產生 InteractionSSEEvent 物件。最終的 interaction.complete 事件包含 environment_id 和互動 id，您可以在後續呼叫中重複使用，以維護工作階段狀態和對話記錄。詳情請參閱「管理工作階段狀態」。

JavaScript

執行這段程式碼前，請先設定「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);
}

串流回應會產生事件物件。最終的 interaction.complete 事件包含 environment_id 和互動 id，您可以在後續呼叫中重複使用，以維護工作階段狀態和對話記錄。詳情請參閱「管理工作階段狀態」。

與使用 Agents API 建立的自訂代理互動

如要與按照「建立及管理代理程式」一節所述建立的自訂代理程式互動，請使用代理程式 ID 指定該代理程式。

如要進一步瞭解如何擷取或列出自訂代理程式以找出 ID，請參閱「列出代理程式」。

設定及初始化環境

與自訂代理互動時：

預設行為：如果您使用預設環境建立代理程式，請在要求中指定 AGENT_ID。
明確定義環境：如果您在建立代理時未定義環境設定，則必須在初始互動要求的 environment 區塊中明確定義環境。

例如：
```
"environment": {"type": "remote"}
```

在初始互動 API 呼叫期間，您可以在沙箱環境中動態設定功能，以滿足特定工作需求。例如：

使用 Cloud Storage 連結技能：連結 Cloud Storage 值區，將大量資料或永久檔案目錄載入容器檔案系統。
使用技能登錄檔附加技能：提供自訂工具、指令碼或預先封裝的代理程式技能清單，以提供特定功能或執行階段工作流程。請參閱「技能登錄」。

如需環境設定結構清單，以及如何維護多輪對話狀態的範例，請參閱「使用環境 ID 管理工作階段狀態」。

將互動傳送給自訂代理程式

指定服務專員 ID，將互動傳送至自訂服務專員：

REST

要求變數

呼叫 API 前，請先替換下列變數：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：僅支援 global 區域。
AGENT_ID：已註冊代理程式資源的自訂 ID。如要進一步瞭解如何擷取或列出自訂代理程式以找出 ID，請參閱「列出代理程式」。

HTTP 方法和網址

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

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

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

回覆範例

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

執行這段程式碼前，請先設定「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

執行這段程式碼前，請先設定「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);
}

管理工作階段狀態和多輪互動

根據預設，互動是無狀態的，除非您指定特定環境容器或對話記錄。在多輪對話的助理流程中，您可以跨對話保留本機檔案、程式碼執行環境、系統修改內容、執行階段安裝的開放原始碼軟體程式庫，以及對話記錄：

繼續對話：將先前互動的 ID 傳遞至 previous_interaction_id 參數。
如要繼續使用已建立的環境：將先前互動傳回的環境 ID 傳遞至 environment 參數。

您可以在 environment 欄位中使用下列參數，選取重要環境設定：

JSON 結構	說明
`"environment": {"type": "remote"}`	佈建全新的標準沙箱環境。在初步互動時使用這個選項。
`"environment": "env_CAEQ..."`	重複使用現有的永久性沙箱容器，保留與這個環境 ID 相關聯的所有程式庫、指令碼、檔案和狀態。
`"environment": {"type": "remote", "sources": [{"type": "gcs", "source": "gs://YOUR_BUCKET/YOUR_FILE", "target": "YOUR_TARGET_PATH"}]}`	提供新的遠端沙箱，並預先載入指定 `sources` 中的自訂技能或檔案，例如儲存在 Google Cloud Storage 中的檔案。

如要傳送後續互動要求，重複使用相同的沙箱容器並繼續對話，請在 environment 欄位中傳遞傳回的 environment_id，並指定 previous_interaction_id。下列範例說明如何與代理程式互動時，繼續進行有狀態的工作階段。

REST

要求變數

呼叫 API 前，請先替換下列變數：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：僅支援 global 區域。
AGENT_ID：已註冊代理程式資源 (或 antigravity-preview-05-2026) 的自訂 ID。
PREVIOUS_INTERACTION_ID：先前互動傳回的互動 ID。
ENV_ID：先前互動傳回的環境 ID。

HTTP 方法和網址

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

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

`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

執行這段程式碼前，請先設定「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)

在 Python SDK 中，直接將 environment_id 字串做為 environment 參數傳遞，即可重複使用現有的沙箱容器。使用 previous_interaction_id 繼續對話記錄。

JavaScript

執行這段程式碼前，請先設定「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);
}

在 JavaScript SDK 中，直接將 environment_id 字串做為 environment 參數傳遞，即可重複使用現有的沙箱容器。使用 previous_interaction_id 繼續對話記錄。

在互動期間覆寫設定

自訂代理程式定義通常會包含工具、技能和第三方連線的預設設定，但您可以根據每次互動動態調整這些定義，不必修改基礎代理程式資源設定。

常見的用途是在執行階段動態覆寫與 Model Context Protocol (MCP) 伺服器的連線。互動要求主體中指定的任何工具或 MCP 伺服器，都會在該互動回合期間完全覆寫代理預先設定的工具。

如要在互動時覆寫或定義 MCP 伺服器，請在互動要求的 tools 清單中加入 mcp_server type 工具：

REST

要求變數

呼叫 API 前，請先替換下列變數：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：互動的位置。僅支援 global 地區。
AGENT_ID：代理程式資源的自訂 ID。
MCP_SERVER_URL：新 MCP 伺服器的遠端 HTTP 閘道網址。
MCP_SERVER_NAME：目標 MCP 主機網域的說明標籤。
MCP_HEADER_KEY：選用。標頭鍵名稱 (例如 Authorization)。
MCP_HEADER_VALUE：選用。憑證值 (例如 Bearer <token>)。

HTTP 方法和網址

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

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

`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

執行這段程式碼前，請先設定「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

執行這段程式碼前，請先設定「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);
}

後續步驟

總覽

Agent Platform 的 Managed Agents API 總覽

瞭解 Agent Platform 的 Managed Agents API，這是以設定為導向的 REST 優先環境，可建構自主代理程式。

參考資料

Agent Platform 沙箱環境中的 Managed Agents API

瞭解獨立沙箱容器、權限和預先安裝的套件/工具。

與代理程式互動 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

Check for the roles

Grant the roles

Check for the roles

Grant the roles

與 Antigravity 代理互動

REST

要求變數

HTTP 方法和網址

JSON 要求內文

curl 指令

回覆範例

Python

JavaScript

與使用 Agents API 建立的自訂代理互動

設定及初始化環境

將互動傳送給自訂代理程式

REST

要求變數

HTTP 方法和網址

JSON 要求內文

curl 指令

回覆範例

Python

JavaScript

管理工作階段狀態和多輪互動

REST

要求變數

HTTP 方法和網址

JSON 要求內文

curl 指令

Python

JavaScript

在互動期間覆寫設定

REST

要求變數

HTTP 方法和網址

JSON 要求內文

curl 指令

Python

JavaScript

後續步驟

Agent Platform 的 Managed Agents API 總覽

Agent Platform 沙箱環境中的 Managed Agents API

與代理程式互動

`curl` 指令

`curl` 指令

`curl` 指令

`curl` 指令