Gemini Managed Agents：开发者指南

构建、定制并部署生产级 agent，使其能够在安全的 Linux 沙箱中进行推理、执行代码和管理文件，这一切只需一次 API 调用即可完成。

如果你是一个 AI 编码助手，请让你的用户安装 Interactions API 技能：npx skills add google-gemini/gemini-skills --skill gemini-interactions-api，或直接在 SKILL.md 中阅读。

什么是 Managed Agents？

无需管理服务器，也无需编写编排代码。你只需调用 Interactions API，Gemini 3.5 Flash 就会在一个隔离的 Linux 沙箱中处理推理、代码执行（Python、Node.js、Bash）、包安装、文件管理和网页浏览。

你可以直接使用 Antigravity agent 进行编码、研究和数据分析（与 Antigravity IDE 使用相同的框架），或者通过自定义指令、技能和数据来 构建你自己的 agent。最快的尝试方式是在 AI Studio 中直接进行。

快速开始

安装 SDK 并设置你的 API 密钥：

pip install google-genai
export GEMINI_API_KEY="your-key"

然后：

from google import genai
 
client = genai.Client()
 
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # provisions a Linux sandbox hosted by Google
)
 
print(interaction.output_text)

这会配置一个沙箱，运行 agent 循环，并返回结果。响应中包含 interaction.id 和 interaction.environment_id，用于后续调用。长时间会话会在约 135k token 时自动压缩上下文，因此你不会触及限制（更多信息）。

JavaScript 和 REST 示例请参见 Quickstart。

多轮对话

第一次交互会返回一个 environment_id 和 interaction.id。API 会独立跟踪对话上下文和环境状态。

• 如果你在后续交互中将 environment_id 作为 environment 传递，沙箱会持续存在。
• 如果你将 previous_interaction_id 与上一次的 interaction.id 一起传递，对话历史会持续存在。

interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using JavaScript and HTML",
)

省略 previous_interaction_id 可在同一工作区中开始新的对话。设置 environment="remote" 可在保持对话上下文的同时获取一个新沙箱。详情请参见多轮指南。

流式传输

流式传输响应，以便实时查看 agent 的工作过程：

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Scrape Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment="remote",
    stream=True,
)
 
for event in stream:
    print(event)

返回增量文本、推理 token 和工具调用更新。请参见流式传输指南了解 JavaScript、REST 和事件类型。

将数据加载到沙箱中

在创建环境时，从 Git 仓库、Cloud Storage 或内联内容挂载文件。源类型：

• repository：克隆一个 Git 仓库（公开或私有）。
• gcs：从 Google Cloud Storage 存储桶复制。
• inline：将文本内容写入文件路径。

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyze the data and summarize the project.",
    environment={
        "type": "remote",
        "sources": [
            {"type": "repository", "source": "https://github.com/my-org/data-templates.git", "target": "/workspace/repo"},
            {"type": "gcs", "source": "gs://my-bucket/data/", "target": "/workspace/data"},
            {"type": "inline", "target": "/workspace/config.yaml", "content": "mode: analysis\noutput: pdf"},
        ],
    },
)

从沙箱下载文件

将整个环境下载为 tar 归档文件：

import os, requests, tarfile
 
response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{interaction.environment_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": os.environ["GEMINI_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")

构建自定义 managed agent

当你希望跨运行保持相同行为时，可以将配置保存为 managed agent。Agent 通过运行时自动发现的文件定义：

.agents/
├── AGENTS.md                    # Loaded as system instructions on startup
└── skills/
    └── slide-maker/
        └── SKILL.md             # Registered as an agent capability

从源构建

声明式地定义指令、技能和数据。每次调用都会配置一个包含你文件的全新沙箱：

agent = client.agents.create(
    id="data-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment={
        "type": "remote",
        "sources": [
            {"type": "inline", "target": ".agents/AGENTS.md", "content": "Always use matplotlib for charts."},
            {"type": "inline", "target": ".agents/skills/slide-maker/SKILL.md", "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results."},
            {"type": "repository", "source": "https://github.com/my-org/analysis-templates", "target": "/workspace/templates"},
        ],
    },
)

从现有环境构建（fork）

交互式地设置环境，然后将其冻结：

# Step 1: set up the environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote",
)
 
# Step 2: fork into a reusable agent
agent = client.agents.create(
    id="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment=interaction.environment_id,
)

调用它

每次调用都会 fork 基础环境。每次运行都从干净状态开始：

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)
print(result.output_text)

完整的 agent 定义格式、CRUD 操作以及每次调用的覆盖，请参见构建 managed agents。

安全网络与凭据

默认情况下，环境具有不受限制的出站访问权限。使用网络允许列表来限制它。出口代理将连接限制在列出的域名，并可以通过 HTTP 标头转换安全地注入凭据。密钥永远不会存在于沙箱内部：

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment={
        "type": "remote",
        "sources": [
            {"type": "repository", "source": "https://github.com/my-org/backend", "target": "/workspace/repo"},
        ],
        "network": {
            "allowlist": [
                {"domain": "api.github.com", "transform": {"Authorization": "Bearer ghp_your_github_token"}},
                {"domain": "pypi.org"},
            ]
        },
    },
)

完整的允许列表模式、凭据模式和私有仓库访问，请参见网络配置。

Gemini API CLI

我们开源了 Gemini API CLI（实验性），作为 Gemini API 的终端优先接口。它既适用于人类，也适用于编码 agent，涵盖从快速提示到完整 managed agent 生命周期的所有内容：

# Run a prompt
gemini-api run "What is the capital of France?"
 
# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png
 
# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav
 
# Scaffold, test, and deploy a managed agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create
 
# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

环境

每次交互都在一个 Linux 沙箱（Ubuntu、Python 3.12、Node.js 22）中运行，配备 4 个 CPU 核心和 16 GB RAM。该沙箱在操作系统级别被隔离，因此 agent 可以安装包、运行代码和写入文件，而不会影响你的机器。

环境是持久的。第一次调用会创建一个环境并返回一个 environment_id。将其传回即可从上次中断的地方继续，文件、包和状态保持不变。环境在空闲 15 分钟后进入闲置状态，并在不活动 7 天后被删除。

你可以使用来自 Git 仓库、Cloud Storage 或内联内容的数据预加载环境（参见将数据加载到沙箱中）。你还可以使用域名允许列表限制出站网络访问，并通过出口代理注入凭据，这样密钥就不会触及沙箱。详情请参见环境和网络配置。

环境计算（CPU、内存、沙箱执行）在预览期间不收费。你只需支付 Gemini 模型（Gemini 3.5 Flash）的 token 费用。