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、curl4 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( agentantigravity-preview-05-2026, # 使用预置的基础代理 inputFetch the Hacker News front page and list the top 5 stories., streamTrue, # 关键参数实时看到代理在做什么 environmentremote, # 申请一个云端沙盒 ) 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 实时监控代理执行过程设置streamTrue后你能实时看到代理在沙盒里的每一步操作[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 todays 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 fhttps://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(fileobjresponse.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( agentantigravity-preview-05-2026, input为每个故事添加重要性评分1-5星然后更新PDF, streamTrue, environmentenvironment_id, # 复用同一个沙盒 previous_interaction_idinteraction_id, # 继承对话历史 )这种多轮对话的能力基于两个独立的 IDenvironment_id标识沙盒环境保持文件系统和已安装包不变previous_interaction_id标识对话历史让代理记住之前做过什么你可以灵活组合使用只传environment_id在新对话中复用文件和环境适合同一工作区的不同任务只传previous_interaction_id在新沙盒中继续对话适合需要干净环境的优化任务两个都传完全连续的对话适合当前场景这种设计避免了传统代理框架中复杂的会话管理代码所有状态都由平台托管。6. 生产化配置创建命名代理如果测试满意可以把配置烘焙成命名代理避免每次调用都传递文件内容# 一次性创建命名代理 agent client.agents.create( idmy-tech-digest, # 自定义标识符 base_agentantigravity-preview-05-2026, description每日技术摘要代理带编辑风格和PDF生成, base_environment{ type: remote, sources: [/* 同样的配置源 */], }, ) # 后续调用简化成这样 stream client.interactions.create( agentmy-tech-digest, # 直接使用保存的配置 input, streamTrue, environmentremote, )命名代理的优势调用代码更简洁不携带文件内容配置集中管理更新时只需重新创建代理适合团队协作共享代理配置创建后可以通过client.agents.list()查看所有已保存的代理用client.agents.delete()清理不再使用的配置。7. 实际使用中的注意事项和排查经验经过多次测试我总结出几个关键经验点启动失败常见原因API 密钥未启用结算功能——去 AI Studio 确认账单设置网络连接问题——尝试用 Cloud Shell 排除本地网络因素沙盒资源暂时不足——等待几分钟后重试执行过程卡住的排查顺序先看流式输出最后显示的工具调用——确认卡在哪个环节检查输入指令是否明确——模糊的指令可能导致代理思考过久确认网页资源可访问——有些网站可能屏蔽自动化访问等待合理时间——复杂任务可能需要 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_retries3): 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 raise2. 输出验证和质检检查生成的 PDF 文件大小是否合理不应为 0 字节验证摘要内容是否包含关键信息点设置基本的质量阈值不达标时自动重运行3. 监控和日志记录每次运行的 environment_id 和 interaction_id跟踪执行时间和 token 使用量设置异常报警机制4. 成本优化根据实际需要调整任务频率使用更简洁的提示词减少 token 消耗定期审查和清理不再使用的资源托管代理最大的价值在于快速验证想法当你的工作流稳定后可以根据实际需求决定是继续使用托管方案还是迁移到更可控的自建架构。我个人更建议先把单任务跑稳定确认输出质量和成本都在可接受范围内再考虑批量化和生产化。很多自动化项目失败不是因为技术不行而是因为低估了异常处理和边界情况的复杂度。