Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Interactions API 開發人員指南

Interactions API 提供統一的具狀態介面，方便您在 Gemini Enterprise Agent Platform 上，使用 Gemini 模型和自主代理建構生成式 AI 應用程式。使用 Interactions API 執行多輪對話、串流即時回應、強制執行結構化輸出內容、執行函式呼叫，以及協調長時間執行的背景工作。

本指南說明如何安裝 Google Gen AI SDK、驗證用戶端，以及實作常見的互動工作流程。如要瞭解互動生命週期的概念詳細資料，請參閱「Interactions API 總覽」。

事前準備

請先設定專案和開發環境，再向 Interactions API 傳送要求： Google Cloud

登入 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, 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

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

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, if it is not already enabled.

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)

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.

基本概念

請查看下列概念，瞭解 Interactions API 如何管理狀態和回應：

Interaction：Interactions API 的核心資源是 Interaction。Interaction 代表對話或工作中的完整回合，可追蹤模型想法、工具呼叫和最終輸出內容的時序。為提示-回覆互動和複雜的多步驟代理工作流程提供統一的封包。
保留狀態：互動內容預設會儲存在伺服器端 (Python 為 store=True，TypeScript/JavaScript 為 store: true)。儲存的互動記錄會保留 7 天，之後就會自動刪除。設定 store=False 會啟用無狀態模式，停用伺服器端保留功能，並符合零資料保留 (ZDR) 規定。無狀態模式也會停用 previous_interaction_id 鏈結和非同步執行 (background=True)。
回覆輔助程式：Google Gen AI SDK 2.3.0 以上版本會在互動回覆中提供便利的屬性，包括 interaction.output_text、interaction.output_image 和 interaction.output_audio。請使用 interaction.output_text 讀取文字回應，而不是手動將索引編入步驟陣列 (例如 interaction.steps[-1].content[0].text)。

需求條件

整合 Interactions API 前，請確認環境和要求符合下列規定：

支援的 SDK 版本：使用統一的 Google Gen AI SDK (>= 2.3.0 適用於 Python，或 @google/genai >= 2.3.0 適用於 TypeScript 和 JavaScript)。
- 如要使用回覆輔助屬性和代理程式功能，必須使用 2.3.0 以上版本，而 2.0.0 版則支援基本 steps 架構。
- 舊版 SDK (google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai) 不支援 Interactions API。
支援的模型：使用支援的 Gemini 3 模型或更新版本。較早的型號系列不支援這個 API。如需支援型號的完整清單，請參閱「支援的型號」和「遷移至最新模型版本」。
回合範圍參數：設定參數 (例如 tools、system_instruction 和 generation_config) 只適用於目前回合。如果工作流程需要在多輪對話中用到這些參數，請在後續的每次互動中傳遞這些參數。

安裝 Google Gen AI SDK

為偏好的語言安裝或升級 Google Gen AI SDK (>= 2.3.0)：

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

驗證用戶端

您可以透過下列任一驗證方法，連線至 Agent Platform 的 Interactions API：

使用 Google Cloud 專案和應用程式預設憑證 (ADC) 建立連線

建議您在 Google Cloud上，將這項驗證方法用於企業工作負載和正式版部署作業。如要使用應用程式預設憑證 (ADC) 進行驗證，請使用下列屬性初始化用戶端：

enterprise=True
project= Google Cloud project ID
location="global"

如果尚未設定本機憑證，請執行 gcloud auth application-default login。

在下列程式碼範例中，將 PROJECT_ID 替換為您的Google Cloud 專案 ID。

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

使用快捷模式連線 (API 金鑰)

建議您使用這種驗證方式進行快速原型設計、輕量型指令碼，或使用 API 金鑰驗證的環境。初始化用戶端時，或在 x-goog-api-key HTTP 標頭中傳遞 API 金鑰。

在下列程式碼範例中，請將 API_KEY 替換成您的 API 金鑰。

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1beta1/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

常見的互動工作流程

設定用戶端後，您可以使用 interactions.create 方法建構多輪對話、即時串流輸出權杖、產生通過結構定義驗證的 JSON、呼叫外部函式，以及執行自主代理程式。

管理有狀態的多輪對話

與無狀態的 Chat API 不同，您不必在每次要求時重新傳送完整訊息記錄，Interactions API 預設會在伺服器上管理對話狀態 (Python 中的 store=True 或 TypeScript/JavaScript 中的 store: true)。

如要繼續現有對話，請將先前互動的 id 傳遞至 previous_interaction_id 參數。Agent Platform 會自動擷取儲存的對話內容，並附加新的輪次。如果您設定 store=False (TypeScript/JavaScript 中的 store: false)，伺服器端持續性會停用，且您無法使用 previous_interaction_id 串連後續回合。

Python

# Turn 1: Start a conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

// Turn 1: Start a conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

即時串流回覆

如要減少互動式應用程式的感知延遲，可以在生成模型回覆時串流傳輸。呼叫 interactions.create 時，請設定 stream=True (TypeScript/JavaScript 中的 stream: true)，以接收伺服器傳送事件的可疊代串流。篩選 step.delta 事件，在收到遞增文字區塊時算繪：

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

生成結構化輸出內容

如果應用程式需要以可預測的機器可讀格式回覆，您可以限制模型輸出內容，使其符合特定 JSON 結構定義。將目標結構定義 (例如 Python 中的 Pydantic 模型 JSON 結構定義，或 TypeScript/JavaScript 中的結構定義物件) 直接傳遞至多型 response_format 參數：Type

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

import { Type } from "@google/genai";

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

使用函式呼叫 (工具使用)

模型可透過函式呼叫要求執行自訂函式或外部 API，在擬定最終回覆前收集資訊。在有狀態的互動工作流程中，函式呼叫會遵循兩輪模式：

宣告及傳遞工具：在初始要求的 tools 參數中提供函式宣告。
執行並傳回結果：檢查回應步驟 (interaction.steps) 的 function_call 步驟，使用模型提供的 arguments 執行本機函式，然後傳送後續互動，其中包含由 call_id 和 previous_interaction_id 連結的 function_result 項目。

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

執行代理程式和長期執行的背景工作

除了基礎模型，您也可以使用 Interactions API，透過 agent 參數叫用專門的自主代理：

antigravity-preview-05-2026：一般用途的受管理代理程式，可在安全的 Linux 沙箱環境中執行程式碼、管理檔案及瀏覽網頁。詳情請參閱「與代理程式互動」。
deep-research-preview-04-2026：Gemini Deep Research 代理，可規劃及執行多步驟的網路研究工作，並將多個來源的搜尋結果統整成詳盡報告。詳情請參閱「使用 Gemini Deep Research Agent」。
自訂代理：使用 client.agents.create() 設定及佈建的自訂代理資源。

由於代理程式工作流程通常需要幾分鐘才能完成，因此請設定 background=True，在背景中以非同步方式執行工作流程。API 會立即傳回 Interaction 物件和 id，您可以使用 client.interactions.get() 輪詢 id，直到 interaction.status 轉換為 completed 為止：

試用這個範例前，請先將 PROJECT_ID 替換為您的Google Cloud 專案 ID。

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

存取上傳的 Cloud Storage 檔案

您可以使用 Interactions API 存取上傳的 Cloud Storage 檔案。請參閱以下範例：

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Summarize the attached document:"},
        {
            "type": "document",
            "uri": "gs://my-secure-bucket/quarterly_report.pdf",
            "mime_type": "application/pdf"
        }
    ],
)

print(interaction.output_text)

將 Cloud Storage URI (例如 gs://bucket-name/path/to/file) 傳遞至 Interactions API 時，系統會使用使用者憑證 (EUC) 評估要求。API 會使用已驗證呼叫者的身分擷取 Cloud Storage 物件，而不是背景專案服務代理程式。

如要在互動要求中傳遞 Cloud Storage 檔案，呼叫主體 (使用者帳戶、服務帳戶或聯合身分) 必須擁有所有參照物件的 storage.objects.get 權限。

設定存取 Cloud Storage 檔案的 IAM 角色

授予其中一個包含 storage.objects.get 權限的標準預先定義角色：

Storage 物件檢視者 (roles/storage.objectViewer)：物件的讀取權 (建議)。
Storage 物件使用者 (roles/storage.objectUser)：物件的讀寫權限。

如要使用 Google Cloud CLI 授予使用者帳戶存取權，請使用下列指令：

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

如要授予特定呼叫服務帳戶存取權，請使用下列指令：

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

排解 Cloud Storage 檔案存取問題

如果呼叫主體的權限不足，Interactions API 會傳回類似下列內容的 403 Forbidden 錯誤：

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more GCS URIs.

如要解決這個問題，請將值區或物件的「Storage 物件檢視者」角色 (roles/storage.objectViewer) 授予已通過驗證的呼叫端。

如果指定的物件不存在，或 Bucket 權限禁止呼叫端查看物件是否存在，Interactions API 會傳回類似下列內容的 404 Not Found 錯誤：

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

如要解決這個問題，請確認 Cloud Storage URI 正確無誤，並確認經過驗證的呼叫端具有 bucket 的讀取權。

進階 REST 工作流程

如要進行以殼層為基礎的自動化作業、CI/CD 管道，或沒有 Python 或 TypeScript/JavaScript 執行階段的環境，可以使用 curl，透過 HTTP 直接呼叫 Interactions API。

REST 端點

將 POST 要求傳送至下列 Interactions API 端點：

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

請在要求中替換下列變數：

PROJECT_ID： Google Cloud 專案 ID。
LOCATION：設為 global (或設定要求的支援自訂區域)。

設定環境變數和驗證

在執行下列各節中的 curl 範例之前，請匯出專案 ID、目標模型或代理程式 ID，以及從應用程式預設憑證產生的 OAuth 2.0 存取權杖：

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

同步回應格式

同步 POST 要求會傳回 JSON interaction 物件，其中包含互動 id、執行 status、對話 steps 和權杖 usage 的專屬中繼資料：

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

繼續多輪有狀態的互動

如要透過 REST 繼續進行已儲存的對話，請在 JSON 要求主體的 previous_interaction_id 欄位中，傳遞先前回應中的 id。

嘗試這個範例前，請先將 PREVIOUS_INTERACTION_ID 換成先前互動傳回的 id。

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

使用伺服器傳送事件串流輸出內容

如要透過 REST 串流增量更新，請在 JSON 要求主體中加入 "stream": true：

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

設定 "stream": true 後，伺服器會回應 Transfer-Encoding: chunked 和 Content-Type: text/event-stream (伺服器傳送的事件)。串流中的每個事件都包含 data: 前置字元，其中含有 JSON 酬載，以及 event_type 和步驟差異內容。curl 會自動保持 HTTP 連線開啟，並即時將傳入的區塊寫入 stdout，直到互動完成為止。

在背景執行受管理代理程式

如要透過 REST 啟動長時間執行的受管理代理程式工作，請指定目標 agent、設定 "background": true，並設定 "environment": "remote"：

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

後續步驟

進一步瞭解Interactions API 總覽中的重要概念。
請參閱Interactions API 參考資料，瞭解要求和回應結構定義。
瞭解如何與受管理代理互動，以及使用 Gemini Deep Research 代理。

Interactions API 開發人員指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

Check for the roles

Grant the roles

Check for the roles

Grant the roles

基本概念

需求條件

安裝 Google Gen AI SDK

Python

TypeScript / JavaScript

驗證用戶端

使用 Google Cloud 專案和應用程式預設憑證 (ADC) 建立連線

Python

TypeScript / JavaScript

REST

使用快捷模式連線 (API 金鑰)

Python

TypeScript / JavaScript

REST

常見的互動工作流程

管理有狀態的多輪對話

Python

TypeScript / JavaScript

即時串流回覆

Python

TypeScript / JavaScript

生成結構化輸出內容

Python

TypeScript / JavaScript

使用函式呼叫 (工具使用)

Python

TypeScript / JavaScript

執行代理程式和長期執行的背景工作

存取上傳的 Cloud Storage 檔案

設定存取 Cloud Storage 檔案的 IAM 角色

排解 Cloud Storage 檔案存取問題

進階 REST 工作流程

REST 端點

設定環境變數和驗證

同步回應格式

繼續多輪有狀態的互動

使用伺服器傳送事件串流輸出內容

在背景執行受管理代理程式

後續步驟

Interactions API 開發人員指南