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

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

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 person_add 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 Add another role and add each additional role.
7. Click Save.

主要概念

请查看以下概念，了解 Interactions API 如何管理状态和回答：

• Interaction：Interactions API 围绕一个核心资源展开：Interaction。Interaction 表示对话或任务中的一个完整轮次，用于跟踪模型思考、工具调用和最终输出的时间顺序。它为提示-回答交互和复杂的多步骤 Agentic Workflows 提供了一个统一的封装。
• 有状态保留：默认情况下，互动会存储在服务器端（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（适用于 Python 的 >= 2.3.0 或适用于 TypeScript 和 JavaScript 的 @google/genai >= 2.3.0）。

  • 响应辅助属性和智能体功能需要 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)：

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

npm install "@google/genai>=2.3.0"

对客户端进行身份验证

您可以使用以下任一身份验证方法连接到 Agent Platform 上的 Interactions API：

• Google Cloud 项目（使用应用默认凭证）
• 使用 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。

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)

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

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 密钥。

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)

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

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、调用外部函数以及运行自主智能体。

管理有状态多轮对话

无状态聊天 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 链接后续轮次。

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

// 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 事件，以便在增量文本块到达时进行渲染：

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

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 中的 Type 架构对象）直接传递给多态 response_format 参数：

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)

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，以便在制定最终回答之前收集信息。在有状态交互工作流中，函数调用遵循两轮模式：

1. 声明并传递工具：在初始请求的 tools 参数中提供函数声明。
2. 执行并返回结果：检查响应步骤 (interaction.steps) 是否包含 function_call 步骤，使用模型提供的 arguments 运行本地函数，并发送包含由 call_id 和 previous_interaction_id 关联的 function_result 项的后续互动。

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

// 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 智能体。
• 自定义智能体：使用 client.agents.create() 配置和预配的自定义智能体资源。

由于智能体工作流通常需要几分钟才能完成，因此请通过设置 background=True 在后台异步运行它们。该 API 会立即返回一个 Interaction 对象，其中包含一个 id，您可以使用 client.interactions.get() 对其进行轮询，直到 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 Object Viewer (roles/storage.objectViewer)：对对象的读取权限（推荐）。
• Storage Object User (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 Cloud Storage URIs.

如需解决此问题，请向经过身份验证的调用方授予存储桶或对象的 Storage Object Viewer 角色 (roles/storage.objectViewer)。

如果指定的对象不存在，或者存储桶权限导致调用方无法查看该对象是否存在，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 是否正确，并确认经过身份验证的调用方对存储桶具有读取权限。

使用 CMEK 加密互动数据

有状态互动（Python 中的 store=True 或 TypeScript/JavaScript 中的 store: true）会将互动数据存储在静态位置，最长可存储 7 天。如需使用您自己的加密密钥（而非Google-owned and Google-managed encryption key）保护这些数据，请使用服务配置文件。服务配置文件会将 Cloud Key Management Service 密钥关联到项目、位置和 API 范围。只要存在服务配置文件，Agent Platform 就会自动加密存储的互动数据，而互动请求格式不会发生变化。

us 和 eu 多区域支持 Interactions API 的服务配置 CMEK。global 区域不受支持。

如需为 Interactions API 设置 CMEK，请执行以下操作：

1. 在项目中启用 Cloud KMS API 和 Agent Platform API。请参阅准备工作。
2. 在 us 或 eu 多区域中创建 Cloud KMS 密钥。请参阅创建密钥环和密钥。
3. 向 Gemini Enterprise Agent Platform 服务代理授予密钥的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。请参阅授予 Agent Platform 权限。

4. 在同一多区域（us 或 eu）中创建一个服务配置，将 scope 设置为 INTERACTIONS_API，并将 cmekConfig.encryptionSpec.kmsKeyName 设置为您的密钥：

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://aiplatform.LOCATION.rep.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/servingProfiles?servingProfileId=SERVING_PROFILE_ID" \
     -d '{
       "displayName": "Interactions API CMEK profile",
       "description": "CMEK for Interactions API",
       "scope": "INTERACTIONS_API",
       "cmekConfig": {
         "encryptionSpec": {
           "kmsKeyName": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME"
         }
       }
     }'
   

   等待长时间运行的创建操作完成 ("done": true)。如需详细了解如何管理、更新或删除服务配置，请参阅创建服务配置。

5. 将互动请求发送到与服务配置相同的 us 或 eu 多区域。global 端点不支持服务配置 CMEK。

   • Google Gen AI SDK：使用 location="us" 或 location="eu"（在 TypeScript/JavaScript 中为 location: "us" 或 location: "eu"）初始化客户端。
   • REST：向多区域端点 https://aiplatform.LOCATION.rep.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions 发送请求，其中 LOCATION 为 us 或 eu。

   如果您停用密钥或撤消服务代理的访问权限，则创建或读取存储的互动的请求将失败，并显示 FAILED_PRECONDITION 错误。

高级 REST 工作流

对于基于 shell 的自动化、CI/CD 流水线或没有 Python 或 TypeScript/JavaScript 运行时的环境，您可以使用 curl 通过 HTTP 直接调用 Interactions API。

REST 端点

向以下 Interactions API 端点发送 POST 请求：

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

替换请求中的以下变量：

• PROJECT_ID：您的 Google Cloud 项目 ID。
• LOCATION：设置为 global（或设置为 us 或 eu，并使用多区域主机 https://aiplatform.LOCATION.rep.googleapis.com，使用 CMEK 加密互动数据）。

设置环境变量和身份验证

在运行以下部分中的 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 参考文档中探索请求和响应 schema。
• 了解如何与托管代理互动以及使用 Gemini Deep Research 代理。