1. 先搞清楚托管代理到底解决了什么问题

如果你之前用过 LangChain、AutoGen 这类框架，应该知道搭建一个能自动执行任务的 AI 代理有多麻烦：要选框架、写工具函数、处理状态管理、打包容器、部署服务，最后才能跑起来测试。Google 的 Gemini API 托管代理直接把这一套流程简化到了极致——你只需要写两个 Markdown 配置文件和一个 Python 脚本，调用一次 API，就能启动一个完整的 Ubuntu 沙盒环境，让代理在里面自主浏览网页、运行代码、生成 PDF。

这个方案最核心的价值是 把基础设施复杂度全部转移到了云端 。你不用关心容器怎么打、服务怎么扩缩容、工具怎么注册，甚至连 Python 包都是代理在沙盒里自己安装。对于需要快速验证一个自动化工作流是否可行的场景，这种“一次调用，全托管执行”的模式能省下大量前期准备时间。

适合看这篇文章的人：

• 已经用过 Gemini API 基础文本生成，想探索更复杂的自动化任务
• 之前搭过本地代理框架，但被环境配置和部署流程劝退
• 需要做一个能联网、能执行代码、能处理文件输出的智能助手原型

2. 运行托管代理需要准备什么条件

虽然托管代理省去了部署环节，但运行前还是要确认几个硬性条件：

API 密钥和计费 ：

• 需要一个已启用结算功能的 Gemini API 密钥（从 aistudio.google.com/api-keys 获取）
• 每次完整运行的费用大约在 0.30-1.30 美元之间，建议先充入 1-2 美元作为测试预算
• 预览期间环境计算资源（CPU、内存）免费，但 API 调用按 token 收费

本地环境 ：

• Python 3.10 或更高版本
• 网络能正常访问 Google API 服务
• 不需要安装 Docker 或其他复杂依赖

沙盒规格 （每次调用自动分配）：

• 隔离的 Ubuntu Linux 环境
• 预装 Python 3.12、Node.js 22、Bash、git、pip、curl
• 4 CPU 核心 + 16 GB RAM
• 出站网络通过代理访问，支持正常的网页抓取

我建议先用 Cloud Shell 测试（Google 提供的在线终端），因为依赖项都已经预装好。如果要在本地跑，需要自己配 Python 环境和网络权限。

3. 从零开始搭建一个技术摘要代理

我们以构建“每日技术新闻摘要”代理为例，拆解整个流程。这个代理会自动抓取 Hacker News 首页，总结 top 5 故事，并生成格式化的 PDF 报告。

3.1 第一次调用：先验证沙盒能正常启动

初始代码非常简单，主要是测试环境是否能正常拉起：

from google import genai

client = genai.Client()  # 自动读取环境变量中的 GEMINI_API_KEY

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",  # 使用预置的基础代理
    input="Fetch the Hacker News front page and list the top 5 stories.",
    stream=True,  # 关键参数：实时看到代理在做什么
    environment="remote",  # 申请一个云端沙盒
)

for event in stream:
    if hasattr(event, 'tool_call'):
        print(f"  [tool] {event.tool_call.tool_name}")
    elif hasattr(event, 'text_delta'):
        print(event.text_delta, end="")

# 运行完成后会返回环境ID和交互ID
environment_id = stream.environment_id
interaction_id = stream.interaction_id

这个最简单的调用能帮你验证几件事：

• API 密钥是否正确
• 网络是否能连通 Google 服务
• 沙盒环境是否能正常分配
• 代理是否能执行基本任务

如果这里就报错，先检查密钥权限和网络设置，不要急着往下走。

3.2 关键配置：用 Markdown 文件定义代理行为

托管代理的核心配置方式是通过 Markdown 文件。你需要创建三个文件：

.agents/AGENTS.md - 定义代理的"人设"和工作流程：

# Tech Digest Agent

你是一个技术新闻摘要专家，每天早上自动抓取最新技术新闻，生成简洁的摘要报告。

## 工作流程
1. 访问 Hacker News 首页获取 top 5 故事
2. 提取每个故事的标题、链接、得分和评论数  
3. 为每个故事撰写 2-3 句摘要
4. 调用 digest-pdf 技能生成格式化 PDF

## 可用技能
- digest-pdf: 生成技术摘要 PDF 报告

.agents/skills/digest-pdf/SKILL.md - 定义 PDF 生成技能：

# digest-pdf

生成技术新闻摘要的 PDF 报告。

## 步骤
1. 读取 /workspace/summaries.json 中的摘要数据
2. 使用 generate_pdf.py 脚本渲染 PDF
3. 保存到 /workspace/digest.pdf

.agents/skills/digest-pdf/scripts/generate_pdf.py - 具体的 PDF 生成脚本（标准 ReportLab 代码，这里省略具体实现）

配置好这些文件后，调用时通过 environment.sources 参数加载：

environment={
    "type": "remote",
    "sources": [
        {
            "type": "inline", 
            "target": ".agents/AGENTS.md",
            "content": AGENTS_MD,  # 从文件读取的内容
        },
        # 同样加载 SKILL.md 和 generate_pdf.py
    ],
}

这种配置方式的好处是 版本可控 ——所有代理行为定义都放在代码库中，与项目一起管理。

3.3 实时监控代理执行过程

设置 stream=True 后，你能实时看到代理在沙盒里的每一步操作：

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)  # 读取技能定义
  [tool] run_code  # 执行 Python 脚本抓取网页
  [tool] write_file (/workspace/summaries.json)  # 保存摘要数据
  [tool] run_code  # 调用 PDF 生成脚本
I have successfully generated today's tech news digest.

这种透明度很重要，因为：

• 你能确认代理确实在执行预期任务，而不是卡住或跑偏
• 出现问题时能快速定位到具体哪一步失败
• 了解代理的"思考过程"，便于后续优化指令

如果某个工具调用耗时过长（比如超过 2 分钟），可能意味着代理遇到了问题，需要中断重试。

4. 处理输出结果和文件下载

代理在沙盒中生成的 PDF 文件位于 /workspace/digest.pdf ，你需要通过 Gemini Files API 下载：

import requests
import tarfile
import os

# 从环境变量读取配置
api_key = os.getenv("GEMINI_API_KEY")
environment_id = os.getenv("ENVIRONMENT_ID")

# 下载沙盒文件系统快照
url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download"
response = requests.get(
    url,
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key}
)

# 从 tar 包中提取 PDF
with tarfile.open(fileobj=response.content) as tar:
    # 查找 PDF 文件（路径可能变化，按后缀匹配）
    pdf_member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
    tar.extract(pdf_member, path=".")

这个下载过程是 独立于代理执行 的，意味着：

• 你可以在代理完成后任意时间下载文件
• 同一个沙盒环境可以生成多个文件，一次性下载
• 如果下载失败，可以重新调用 API，不会重复计费

我建议在代理完成后立即下载文件，因为沙盒在 7 天不活动后会自动清理。

5. 多轮对话：优化输出而不重新执行

托管代理的一个重要特性是 保持会话状态 。假设你对生成的摘要不满意，想要添加"重要性评分"，不需要重新抓取网页：

# 使用之前的环境和交互 ID
stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="为每个故事添加重要性评分（1-5星），然后更新PDF",
    stream=True,
    environment=environment_id,  # 复用同一个沙盒
    previous_interaction_id=interaction_id,  # 继承对话历史
)

这种多轮对话的能力基于两个独立的 ID：

• environment_id ：标识沙盒环境，保持文件系统和已安装包不变
• previous_interaction_id ：标识对话历史，让代理记住之前做过什么

你可以灵活组合使用：

• 只传 environment_id ：在新对话中复用文件和环境，适合同一工作区的不同任务
• 只传 previous_interaction_id ：在新沙盒中继续对话，适合需要干净环境的优化任务
• 两个都传：完全连续的对话，适合当前场景

这种设计避免了传统代理框架中复杂的会话管理代码，所有状态都由平台托管。

6. 生产化配置：创建命名代理

如果测试满意，可以把配置"烘焙"成命名代理，避免每次调用都传递文件内容：

# 一次性创建命名代理
agent = client.agents.create(
    id="my-tech-digest",  # 自定义标识符
    base_agent="antigravity-preview-05-2026",
    description="每日技术摘要代理，带编辑风格和PDF生成",
    base_environment={
        "type": "remote",
        "sources": [/* 同样的配置源 */],
    },
)

# 后续调用简化成这样
stream = client.interactions.create(
    agent="my-tech-digest",  # 直接使用保存的配置
    input="",
    stream=True,
    environment="remote",
)

命名代理的优势：

• 调用代码更简洁，不携带文件内容
• 配置集中管理，更新时只需重新创建代理
• 适合团队协作，共享代理配置

创建后可以通过 client.agents.list() 查看所有已保存的代理，用 client.agents.delete() 清理不再使用的配置。

7. 实际使用中的注意事项和排查经验

经过多次测试，我总结出几个关键经验点：

启动失败常见原因 ：

1. API 密钥未启用结算功能——去 AI Studio 确认账单设置
2. 网络连接问题——尝试用 Cloud Shell 排除本地网络因素
3. 沙盒资源暂时不足——等待几分钟后重试

执行过程卡住的排查顺序 ：

1. 先看流式输出最后显示的工具调用——确认卡在哪个环节
2. 检查输入指令是否明确——模糊的指令可能导致代理"思考"过久
3. 确认网页资源可访问——有些网站可能屏蔽自动化访问
4. 等待合理时间——复杂任务可能需要 3-5 分钟

输出质量优化技巧 ：

• 在 AGENTS.md 中提供具体示例，让代理理解你想要的格式和风格
• 分阶段测试：先验证网页抓取，再验证摘要生成，最后验证 PDF 输出
• 使用多轮对话逐步优化，而不是一次性要求完美输出

成本控制建议 ：

• 初始测试时设置明确的超时时间，避免长时间运行
• 使用流式传输实时监控，发现问题及时中断
• 定期清理不再使用的命名代理和沙盒环境

8. 托管代理与传统方案的对比

如果你在犹豫是否要采用这个方案，可以对比一下传统自建代理的复杂度：

能力	ADK + Cloud Run（自建）	Gemini 托管代理
沙盒环境	需要自己构建 Docker 镜像并部署	一次 API 调用自动分配
工具定义	需要编写 Python 工具函数并注册	使用内置工具（代码执行、网页浏览等）
包管理	在 Dockerfile 中预先安装	代理在沙盒内按需安装
会话管理	需要自己实现数据库存储和上下文注入	通过 environment_id 和 interaction_id 管理
基础设施	需要管理容器、部署、扩缩容	完全托管，无基础设施负担

对于原型验证和中小型自动化任务，托管代理的快速启动优势很明显。但对于需要深度定制工具或有严格数据驻留要求的场景，可能还是需要自建方案。

最重要的是，托管代理大幅降低了尝试门槛——你可以在几小时内验证一个想法是否可行，而不需要先花几天时间搭建基础设施。

9. 适合的使用场景和边界条件

基于我的测试经验，这个方案特别适合：

技术内容自动化 ：

• 每日技术新闻摘要（如示例所示）
• 监控 GitHub 趋势项目并生成报告
• 跟踪特定技术话题的最新讨论

数据收集和处理 ：

• 定期抓取公开数据源并生成统计报告
• 监控网站变化并发送差异通知
• 处理结构化数据并生成可视化图表

个人效率工具 ：

• 自动整理阅读清单和笔记
• 处理邮件或消息中的任务请求
• 生成周报或项目进度摘要

需要谨慎评估的场景 ：

• 处理敏感或私有数据（沙盒在 Google 云端运行）
• 需要极低延迟的实时任务（沙盒启动需要几十秒）
• 需要自定义系统级工具或特殊依赖的任务
• 大规模批量处理（成本可能较高）

我建议先从简单的、非关键的任务开始，熟悉整个工作流程后再应用到更重要的场景中。

10. 从测试到生产的过渡建议

如果你测试后觉得这个方案适合实际项目，可以考虑以下过渡步骤：

1. 错误处理和重试机制 ：

import time
from google.api_core import exceptions

def run_agent_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            stream = client.interactions.create(...)
            return process_stream(stream)
        except exceptions.ResourceExhausted:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 指数退避
                continue
            raise

2. 输出验证和质检 ：

• 检查生成的 PDF 文件大小是否合理（不应为 0 字节）
• 验证摘要内容是否包含关键信息点
• 设置基本的质量阈值，不达标时自动重运行

3. 监控和日志 ：

• 记录每次运行的 environment_id 和 interaction_id
• 跟踪执行时间和 token 使用量
• 设置异常报警机制

4. 成本优化 ：

• 根据实际需要调整任务频率
• 使用更简洁的提示词减少 token 消耗
• 定期审查和清理不再使用的资源

托管代理最大的价值在于快速验证想法，当你的工作流稳定后，可以根据实际需求决定是继续使用托管方案，还是迁移到更可控的自建架构。

我个人更建议先把单任务跑稳定，确认输出质量和成本都在可接受范围内，再考虑批量化和生产化。很多自动化项目失败不是因为技术不行，而是因为低估了异常处理和边界情况的复杂度。