Gemini 中文指南
获取 API 密钥 ↗

托管智能体快速入门

↓ 下载 MarkdownInteractions API

本指南将引导您在 Gemini API 上创建和使用托管智能体,使用 Antigravity 智能体。您将进行第一个智能体呼叫,继续多轮对话,流式传输响应,从沙箱下载文件,并使用 Antigravity 托管智能体。

运行您的第一个智能体交互 #

一次调用 Interactions API 配置 Linux 沙箱,运行智能体循环,并返回结果。您将定义三个参数:

  • 通过在 agent 作为 "antigravity-preview-09-2026",这是我们预定义的通用托管智能体的当前版本。
  • 定义 environment="remote",提供全新的沙箱环境。
  • 创建一个输入,定义您希望智能体执行的操作。
py
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

# Print the agent's final output
print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")

响应返回一个 Interaction 对象。商店 interaction.id 和 interaction.environment_id 在同一个沙箱中继续对话。使用 interaction.output_text 访问智能体的最终响应。 interaction.steps 列出了智能体采取的每个步骤(推理、工具调用、代码执行)。

继续对话(多轮) #

API 跟踪两个独立的状态维度:

  • 对话上下文: 聊天记录、推理轨迹、工具使用、使用 previous_interaction_id.
  • 环境状态: 文件、已安装的包和沙箱状态,使用 environment.

将两者传递到各自的位置以恢复:

py
interaction_2 = client.interactions.create(
    agent="antigravity-preview-09-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
)

print(interaction_2.output_text)

文件从 1 (fibonacci.txt)依次保留 2. 智能体还保留对话上下文。

您可以独立地混合和匹配这些:

  • 清晰对话,保留文件: 省略 previous_interaction_id,仅使用环境 ID 传递 environment 在同一工作空间中进行新的对话。
  • 保持对话,新工作区: 通行证 previous_interaction_id, 设置 environment="remote" 一个新鲜的沙箱。

自动上下文压缩 #

在长时间运行的多轮对话中,推理步骤、工具调用和大文件内容的原始历史记录可能会快速增长并消耗大量上下文空间。为了防止 token 限制错误并保持智能体的焦点(防止“上下文腐烂”),托管智能体 API 具有约 135k token 的本机上下文压缩步骤。这是自动发生的。

流式传输响应 #

对于长时间运行的任务,您可以流式传输响应以实时查看智能体的工作情况:

py
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

stream = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment="remote",
    stream=True,
)

for event in stream:
    print(event)
    if event.event_type == "step.stop" and event.usage:
        print(event.usage)

流式传输返回具有增量更新的步骤增量。当一个步骤完成时, step.stop 事件包括累积的使用统计数据。了解更多信息 串流指南.

从环境中下载文件 #

当智能体在沙箱内创建文件时。使用 Files API 和直接 HTTP 请求下载它们(还没有 SDK 方法):

py
import os
import requests
import tarfile

env_id = interaction.environment_id
api_key = os.environ["GEMINI_API_KEY"]

response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key},
    allow_redirects=True,
)

with open("snapshot.tar", "wb") as f:
    f.write(response.content)

with tarfile.open("snapshot.tar") as tar:
    tar.extractall(path="extracted_snapshot")

保存托管智能体 #

在前面的步骤中,我们使用了默认的 Antigravity 智能体并对其进行了内联自定义。迭代配置(指令、技能、模型选择和环境)后,您可以将其保存为可重复使用的托管智能体。这允许您通过 ID 调用它,而无需重复配置。

当您保存智能体时,请注意内联交互的架构对称性:您指定 base_agent: "antigravity-preview-09-2026" 并且可以通过 agent_config 与你所选择的 model 就像你会做的那样 interactions.create。您还定义了一个 base_environment (来自来源或通过分叉现有环境)。 智能体将为每个新交互使用此环境和模型配置。

来源: 定义内联源或来自其他源(例如 GitHub 或 Cloud Storage)的源。

py
agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-09-2026",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-hydrogen",
    },
    system_instruction="You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports.",
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ],
    },
)

print(f"Saved agent: {agent.id}")

调用托管智能体 #

保存托管智能体后,您可以通过 ID 调用它。每次调用都会分叉基本环境,因此每次运行都是干净的:

py
result = client.interactions.create(
    agent="fibonacci-analyst",
    input="Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment="remote",
)

print(result.output_text)

后续步骤 #

搜索标题、API 名称或正文内容