Gemini 中文指南
获取 API 密钥 ↗

Antigravity 智能体

↓ 下载 MarkdownInteractions API

Antigravity 智能体是 Gemini API 上的通用托管智能体。一次 API 调用即可为您提供一个智能体,它可以在您自己的安全 Linux 沙箱(由 Google 托管)内推理、执行代码、管理文件并浏览网页。

它由 Gemini 4 Hydrogen 构建,并使用与 Antigravity IDE 相同的线束。您可以使用以下命令配置底层 Gemini 模型 agent_config。可以通过 Interactions API 和 Google AI Studio.

py
from google import genai

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

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

print(interaction.output_text)

功能 #

每个调用都可以配置一个 Linux 沙箱并启动一个工具使用循环。 智能体计划、行动、观察结果并重复直到任务完成。

  • 代码执行: 运行 Bash、Python 和 Node.js 命令。安装软件包、运行测试、构建应用程序。
  • 文件管理: 读取、写入、编辑、搜索和列出沙箱中的文件。文件在交互过程中持续存在。
  • 网络访问: Google 搜索和 URL 获取数据。
  • 上下文压缩: 自动上下文压缩(在 ~135k token 时触发)支持长时间运行、多轮会话,而不会丢失上下文或达到 token 限制。

请参阅 快速入门 用于多轮使用和流式传输。

支持的工具 #

默认情况下,智能体可以访问 code_execution, google_search, 和 url_context。当您指定时,文件系统工具会自动启用 environment 参数。您还可以定义 自定义功能 将智能体连接到您自己的 API 和工具。您只需要指定 tools 自定义或限制默认设置或添加自定义功能时的参数。

工具类型值说明
代码执行code_execution使用 stdout/stderr 捕获运行 shell 命令(bash、Python、Node)。
Google 搜索google_search搜索公共网络。
URL上下文url_context获取并阅读网页。
文件系统(通过启用 environment)读取、写入、编辑、搜索和列出沙箱中的文件。当您设置时,系统会自动启用这些工具 environment.
自定义功能function定义智能体可以请求执行的自定义函数。参见 函数调用.
远程 MCP 服务器mcp_server将外部 Model Context Protocol (MCP) 服务器注册为工具。参见 MCP 服务器.

您可以拦截并验证 code_execution 和 filesystem 使用同步在远程沙箱内直接执行工具 钩子.

要将智能体限制为特定工具,请仅传递您需要的工具:

py
from google import genai

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

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Search for the latest AI research papers on reasoning and summarize them.",
    environment="remote",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"},
    ],
)

print(interaction.output_text)

多模态输入 #

Antigravity 智能体支持多模态输入。目前,仅 text 和 image 支持输入。图像必须作为内联 Base64 编码字符串提供(data).

py
import base64
from google import genai

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

with open("path/to/chart.png", "rb") as f:
    image_bytes = f.read()

interaction_inline = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input=[
        {"type": "text", "text": "Analyze this chart and summarize the trends."},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode("utf-8"),
            "mime_type": "image/png",
        },
    ],
    environment="remote",
)

函数调用 #

函数调用允许您通过定义智能体可以调用的自定义工具将 Antigravity 智能体连接到外部 API 和数据库。有关一般概念,请参见 Gemini API 函数调用.

以下示例演示了 2 转弯交互。 智能体首先请求自定义 get_weather 函数调用,客户端第二轮执行并返回结果。

python
from google import genai

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

# 1. Define the custom function
get_weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets the current weather for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, e.g. San Francisco, USA",
            }
        },
        "required": ["location"],
    },
}

# 2. Call the agent with the custom tool (Turn 1)
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[
        {"type": "code_execution"},  # Enable default code execution
        get_weather_tool,            # Add custom function
    ],
)

# Check if the agent requested a function call
if interaction.status == "requires_action":
    # Find function calls that do not have a matching function result.
    # Filesystem tools (like write_to_file) are also represented as function calls
    # but are executed automatically by the environment.
    executed_calls = {step.call_id for step in interaction.steps if step.type == "function_result"}
    pending_calls = [step for step in interaction.steps if step.type == "function_call" and step.id not in executed_calls]

    if pending_calls:
        fc_step = pending_calls[0]
        print(f"Function to call: {fc_step.name} (ID: {fc_step.id})")
        print(f"Arguments: {fc_step.arguments}")

        # 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
        function_result = {
            "temperature": 23,
            "unit": "celsius"
        }

        final_interaction = client.interactions.create(
            agent="antigravity-preview-09-2026",
            previous_interaction_id=interaction.id,  # Reference the interaction ID
            environment=interaction.environment_id,
            input=[
                {
                    "type": "function_result",
                    "name": fc_step.name,
                    "call_id": fc_step.id,
                    "result": function_result,
                }
            ],
        )

        print(final_interaction.output_text)
        # Output: The current weather in Tokyo, Japan is 23°C (Celsius).
    else:
        print("No pending function calls.")
else:
    print(f"Interaction completed with status: {interaction.status}")

MCP 服务器 #

您可以通过注册远程Model Context Protocol(MCP)服务器将Antigravity 智能体连接到外部工具。 智能体通过可流式 HTTP 支持远程 MCP 服务器。

注册MCP服务器时,必须在 tools 数组:

领域类型必填说明
type字符串是的必须是 "mcp_server".
name字符串是的服务器的唯一标识符。必须严格为小写字母和字母数字(匹配 ^[a-z0-9_-]+$).
url字符串是的远程 MCP 服务器的端点 URL。
headers对象否与请求一起发送的自定义标头(例如身份验证)。
allowed_tools数组否允许执行的工具名称列表。如果省略,则允许使用所有工具。
py
from google import genai

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

# Register a remote HTTP MCP server
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "weather", # Must be lowercase
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
    }]
)

print(interaction.output_text)

选型 #

对于 antigravity-preview-09-2026,默认模型是 Gemini 4 Hydrogen (gemini-4-hydrogen)。如果你省略 agent_config,智能体默认为 gemini-4-hydrogen.

您可以使用以下命令配置底层 Gemini 模型 agent_config 优化速度、成本或推理能力。例如,设置 model 到 Gemini 4 Carbon (gemini-4-carbon)对于复杂的软件工程和推理任务:

python
from google import genai

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

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Summarize the key differences between functional and object-oriented programming.",
    environment="remote",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-carbon",
    },
)

print(interaction.output_text)

支持的值 agent_config.model 是:

模型价值在 agent_config.model说明
Gemini 4 Hydrogen (默认)gemini-4-hydrogen默认 Gemini 4 模型为日常编码和智能体工作流程带来了尖端智能、速度和效率。
Gemini 4 Carbongemini-4-carbon适用于复杂软件工程、深度问题解决和长期智能体任务的最强大的前沿推理模型。
Gemini 4 Argongemini-4-argon我们高效的 Gemini 4 前沿推理模型,与相比,可提供更快的响应和更低的 token 每回合支出 Gemini 4 Carbon 跨越软件工程和智能体任务。
Gemini 3.8 Flashgemini-3.8-flash用于推理、编码和工具使用的平衡 Gemini 3.8 Flash 模型。
Gemini 3.6 Flashgemini-3.6-flash适用于一般智能体工作流程的平衡 Flash 模型。
Gemini 3.5 Flash-Litegemini-3.5-flash-lite针对低延迟和成本敏感任务进行了优化的轻量级模型。

创建托管智能体时 agents.create,您可以通过传递以完全相同的方式配置模型 base_agent 和 agent_config。请注意,对于使用以下命令创建的托管智能体,您无法在交互时覆盖模型 agents.create。该模型被锁定为创建智能体时设置的内容。这确保了可预测的工具调用行为、一致的调试以及遵守安全边界。

定制智能体 #

您可以通过自定义其指令、工具和环境来扩展 Antigravity 智能体。 智能体支持文件系统本机的自定义方法:您可以挂载文件,例如 AGENTS.md 有关说明和技能,请参见 .agents/skills/ 直接进入沙箱,或在交互时内联传递配置。您可以内联迭代您的配置,然后在准备好后将其保存为托管智能体。

有关如何构建自定义智能体的完整详细信息,请参阅 建筑托管智能体.

后台执行 #

涉及多步骤推理、代码执行或文件操作的智能体任务可能需要几分钟才能完成。使用 background=True 异步运行交互。 API 立即返回一个交互 ID,您可以轮询该 ID,直到状态变为 completed 或 failed.

python
import time
from google import genai

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

# 1. Start the interaction in the background
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run a complex analysis on the repository.",
    environment="remote",
    background=True,
)

print(f"Interaction started in background: {interaction.id}")

# 2. Poll for completion
while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

if interaction.status == "completed":
    print(interaction.output_text)
else:
    print(f"Finished with status: {interaction.status}")

后台执行需要 store=True,这是默认值。有关后台执行期间的实时进度更新,请参阅 流媒体后台交互.

您可以使用以下命令取消正在运行的后台交互 cancel 方法。

python
client.interactions.cancel(id="INTERACTION_ID")

多轮后台执行

当后台交互涉及有状态工具(例如沙箱中的代码执行)时,请使用 environment_id 从已完成的交互到在同一环境中继续。这可确保智能体从中断处继续,所有文件和状态完好无损。

python
import time
from google import genai

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

# First turn: run a task in the background
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Clone https://github.com/google/generative-ai-python and run its tests.",
    environment="remote",
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Second turn: continue in the same environment
followup = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Fix any failing tests and re-run them.",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    background=True,
)

while followup.status == "in_progress":
    time.sleep(5)
    followup = client.interactions.get(id=followup.id)

print(followup.output_text)

环境 #

每个调用都会创建或重用一个 Linux 沙箱。的 environment 参数采用三种形式:

形式说明
"remote"使用默认设置配置新的沙箱。
"env_abc123"按 ID 重用现有环境,保留所有文件和状态。
{...}满 EnvironmentConfig 具有自定义源和网络规则。

参见 环境 有关源(Git、GCS、内联)、网络、生命周期和资源限制的详细信息。

触发器 #

触发器允许您安排智能体按照 cron 计划自动运行。触发器将智能体、环境、提示和计划绑定到无需手动干预即可触发的持久资源中。每次执行都会重用相同的环境,因此一次运行中创建的文件会保留下来,并且对下一次运行可见。

创建触发器#

通过指定 cron 计划、时区和交互配置来创建触发器。触发器开始于 active 状态并将在下一个匹配的 cron 时间触发。保存返回的 id 管理后续调用中的触发器。

由于触发器按计划无人值守地运行,因此请引用存储的 凭证 而不是内联 token。出口代理会在每次运行时解析它,并且您无需触摸触发器即可轮换机密。内联 transform 规则在这里也起作用,它们只需要您在值发生变化时更新触发器。

python
from google import genai

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

trigger = client.triggers.create(
    schedule="0 9 * * *",
    time_zone="America/Argentina/Buenos_Aires",
    display_name="issue-solver",
    interaction={
        "agent": "antigravity-preview-09-2026",
        "input": "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/.",
        "environment": {
            "type": "remote",
            "network": {
                "allowlist": [
                    {
                        "domain": "api.github.com",
                        "credential": "github-production",
                    },
                    {"domain": "github.com"},
                ]
            },
        },
    },
)

print(f"Trigger created: {trigger.id}")
print(f"Next run: {trigger.next_run_time}")

该 CreateTrigger 请求接受以下字段:

领域类型必填说明
schedule字符串是的Cron 表达式(例如, 0 * * * * 每小时, 0 9 * * 1-5 工作日早上)。
time_zone字符串是的IANA 时区(例如, UTC, America/Argentina/Buenos_Aires).
display_name字符串否触发器的人类可读名称。
max_consecutive_failures整数否触发器自动暂停之前的最大失败次数。默认值:5.
execution_timeout_seconds整数否每次执行的超时时间(以秒为单位)。默认值:600.
interaction对象是的A CreateInteractionRequest 定义智能体、输入、工具和环境。

响应包括以下关键字段:

领域类型说明
id字符串触发器的唯一标识符。在所有后续操作中都使用它。
status字符串当前状态: active, paused, 或 disabled.
next_run_time字符串下一个计划执行的 ISO 8601 时间戳。
consecutive_failure_count整数自上次成功执行以来连续执行失败的次数。

列出触发器#

检索与您的项目关联的所有触发器。

python
triggers = client.triggers.list()
for trigger in triggers.triggers:
    print(f"{trigger.id}: {trigger.display_name} ({trigger.status})")

获取触发器#

获取单个触发器的完整配置和当前状态。

python
trigger = client.triggers.get(id="TRIGGER_ID")
print(f"Schedule: {trigger.schedule}")
print(f"Next run: {trigger.next_run_time}")

暂停和恢复#

您可以暂停触发器以停止计划的执行,然后恢复触发器以重新激活计划。暂停不影响手动执行。

python
# Pause
client.triggers.update(id="TRIGGER_ID", status="paused")

# Resume
client.triggers.update(id="TRIGGER_ID", status="active")

删除触发器#

永久移除触发器。过去的执行历史不会被删除。

python
client.triggers.delete(id="TRIGGER_ID")

立即运行触发器#

按需触发触发器,无需等待下一个计划时间。即使触发器暂停,此操作也有效。

python
client.triggers.run(trigger_id="TRIGGER_ID")

列出执行次数#

查看触发器的执行历史记录。每个执行包括一个 status、时间戳、 interaction_id 您可以用来获取完整的交互输出,以及 environment_id 确认所有运行共享同一个沙箱。

python
executions = client.triggers.list_executions(trigger_id="TRIGGER_ID")
for ex in executions.trigger_executions:
    print(f"{ex.id}: {ex.status} ({ex.start_time} - {ex.end_time})")

# Fetch the full interaction for an execution
interaction = client.interactions.get(id=ex.interaction_id)
print(interaction.output_text)

供货情况和定价 #

Antigravity 智能体可通过以下方式预览 Interactions API 在 Google AI Studio 和 Gemini API 中,适用于免费层和付费层项目。

定价遵循 现收现付模式 基于底层 Gemini 模型 token 和智能体使用的工具。与产生单个输出的标准聊天请求不同,Antigravity 交互是一个智能体工作流程。单个请求会触发推理、工具执行、代码运行和文件管理的自主循环。免费套餐项目包括免费速率限制和使用配额。

Antigravity 交互运行多轮自主循环,并且可能消耗大量 token。套装 预算控制 根据您的要求限制 token 使用。您还可以通过以下方式实时监控进度 上交所流媒体,或取消正在运行的请求。

预算控制 #

除了 选型, 设置 max_total_tokens 里面 agent_config (与 "type": "antigravity")来限制一次交互可以消耗的token(输入+输出+思考)的总数。缓存的 token 不计入此限制。当智能体达到限制时,交互停止并返回 status: "incomplete"。该限制是尽力而为:实际使用量可能会稍微超出该限制,具体取决于智能体在步骤之间检查预算的时间。

设置交互请求的预算 agent_config 旁边 agent 和 input.

python
from google import genai

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

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the dataset in /workspace/data.csv and generate a summary report.",
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    },
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": "/workspace/data.csv",
                "content": "id,name,value\n1,alpha,100\n2,beta,200\n",
            }
        ],
    }
)
print(f"Status: {interaction.status}")  # "incomplete" if budget was hit
print(f"Tokens used: {interaction.usage.total_tokens}")

继续不完整的交互 #

当交互返回时 status: "incomplete",智能体的工作和上下文被保留。发送引用原始交互的新交互 id 和 environment_id 从中断的地方继续。新的互动有自己的特色 max_total_tokens 预算。

python
# Continue from where the agent stopped
continuation = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="continue",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    }
)
print(f"Status: {continuation.status}")

预计费用#

成本因任务复杂性而异。 智能体自主确定需要多少工具调用、代码执行和文件操作。以下估计基于运行。

任务类别输入 token输出 token典型成本
研究与信息综合100k–500k10k–40k$0.30–$1.00
文档和内容生成100k–500k15k–50k$0.30–$1.30
流程与系统设计100k–400k10k–30k$0.25–$0.80
数据处理与分析300k–3M30k–150k$0.70–$3.25

输入 token 的 50–70% 通常会被缓存。具有许多工具调用的复杂智能体工作流程可以在单次交互中累积 3–5 百万 token,成本高达 ~$5.

环境计算 (CPU、内存、沙箱执行)是 未计费 在预览期间。

限制 #

  • 预览状态: Antigravity、智能体和 Interactions API。功能和架构可能会发生变化。
  • 不支持的生成配置: 不支持以下参数并返回 400 错误: temperature, top_p, top_k, stop_sequences, max_output_tokens.
  • 结构化输出: Antigravity 智能体不支持结构化输出。
  • 不可用的工具: file_search, computer_use, 和 google_maps 尚不支持。
  • 远程 MCP 限制: 不支持服务器发送事件 (SSE) 传输(使用 Streamable HTTP)。另外,服务器 name 必须严格为小写字母和字母数字(使用大写字母会触发通用 400 Bad Request 错误)。
  • 文件系统工具: 目前没有文件系统工具。它是 environment.
  • 店铺要求: 智能体执行使用 background=True 需要 store=True.
  • 仅有状态函数调用: 函数调用仅在有状态模式下受支持。你必须使用 previous_interaction_id 继续转弯;不支持手动重建历史记录(无状态模式)。
  • 不支持的多模态类型。 目前不支持音频、视频和文档输入。仅允许文本和图像。

后续步骤 #

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