Google Gemini托管代理实战：从零构建自主AI技术摘要系统

weixin_30781433

395人浏览 · 2026-07-10 09:18:12

weixin_30781433 · 2026-07-10 09:18:12 发布

那天早上，我像往常一样打开技术新闻聚合器，准备花半小时快速浏览当天的头条。但这次不同——我看到的不是人工编辑的摘要，而是一份格式精美、内容详实的PDF报告，标题是“今日技术摘要”，包含Hacker News、TechCrunch等五个来源的精选报道，每篇都附有核心要点和重要性分析。

这份报告并非来自某个大型媒体团队，而是由一个完全自主运行的AI代理在真实Linux沙盒中生成的。它自动抓取网页、分析内容、撰写摘要，最后调用Python脚本渲染成PDF——整个过程无需我介入，也无需部署任何容器或编写复杂的编排代码。

这就是Google Gemini API托管代理带来的变化：它把构建自主AI代理的门槛，从“需要全栈工程能力”降到了“写两个Markdown配置文件加一次API调用”。

1. 托管代理真正解决的是什么问题？

在深入代码之前，我们需要理解托管代理与传统方案的差异。AI系统可以按基础设施管理责任分为三个级别：

1.1 标准大语言模型：只有大脑，没有手脚

你提供提示，它返回文本。模型无法执行任何操作——没有网络访问、没有代码执行、没有文件系统。就像一个有百科全书般知识但被关在密室里的专家，能回答问题但不能实际行动。

1.2 自托管代理：全栈工程挑战

这是过去两年主流方案：使用ADK、LangChain或AutoGen框架，结合Docker容器、自定义工具函数和会话管理，部署到Cloud Run或类似平台。你需要处理：

# 这只是冰山一角——实际还需要部署、扩缩、监控等
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,
    tools=[google_search, built_in_code_execution],
)

更重要的是基础设施负担：容器镜像、Cloud Run部署、流式传输架构、会话状态管理。在代理真正运行一次之前，你已经投入了大量工程资源。

1.3 托管代理：Google管理基础设施，你定义目标

托管代理的核心价值转移：你只关心“做什么”，Google处理“怎么做”的基础设施。一次API调用预配完整的Ubuntu沙盒（Python 3.12、Node.js 22、4CPU/16GB RAM），代理在其中自主运行。

关键区别在于责任边界：

能力	自托管代理（ADK + Cloud Run）	Gemini API托管代理
沙盒环境	自己构建Docker容器	一次API调用自动预配
工具执行	编写Python工具函数	内置：代码执行、网页浏览、文件系统
软件包安装	Dockerfile中预安装	代理在沙盒内实时安装
会话延续	自己管理数据库和上下文注入	传递environment_id和interaction_id
要管理的基础设施	容器、部署、扩缩、监控	无

托管代理不是“另一个框架”，而是服务模式的根本转变：从“给你工具自己搭建”到“告诉我要做什么，我帮你完成”。

2. 从零构建技术摘要代理的实战路径

让我们通过构建每日技术摘要代理，具体理解托管代理的工作方式。这个代理每天自动抓取多个新闻源，生成结构化摘要并输出PDF。

2.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",  # 触发沙盒预配
)

这里有几个容易被忽略但至关重要的细节：

stream=True不是可选功能 ：没有流式传输，调用会阻塞30-90秒后一次性返回结果。这期间你完全不知道代理是在工作、卡住还是失败。流式传输让你实时看到代理的推理过程：

[agent started]
  [tool] run_code  # 代理选择编写Python脚本抓取
  [tool] url_context  # 或者直接读取网页内容
  ...文本块逐步输出...

环境隔离是自动的 ：每个 interactions.create() 调用都启动一个全新的沙盒，彼此完全隔离。代理可以安装软件包、读写文件、访问网络，但无法影响你的本地环境或其他沙盒。

第一次运行成功后，你会获得两个关键ID： environment_id （沙盒实例标识）和 interaction_id （本次对话标识）。它们为后续的会话延续奠定基础。

2.2 第二步：注入个性——用配置文件定义代理行为

基础代理能工作，但没有“个性”。接下来通过配置文件定义代理的编辑风格和工作流程：

<!-- .agents/AGENTS.md -->
# 技术摘要代理

## 角色
你是资深技术编辑，负责生成每日技术新闻摘要。

## 工作流程
1. 抓取Hacker News、TechCrunch、The Verge技术版块
2. 每篇报道提取标题、要点、技术影响
3. 按重要性排序，限制在10篇以内
4. 调用digest-pdf技能生成格式化报告

## 执行规则
- 优先使用官方API而非网页抓取
- 避免过度技术术语，面向广大技术受众
- 每篇摘要不超过150字

同时定义具体技能：

<!-- .agents/skills/digest-pdf/SKILL.md -->
# digest-pdf技能

## 描述
生成格式化的PDF技术摘要报告。

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

关键理解： 技能是代理的程序性记忆 。代理不仅知道“生成PDF”这个概念，还知道具体如何通过预定义的步骤完成。这种“按需加载”的设计保持上下文简洁——技能详情只在需要时载入。

通过environment参数注入配置：

environment={
    "type": "remote",
    "sources": [
        {
            "type": "inline", 
            "target": ".agents/AGENTS.md",
            "content": AGENTS_MD,
        },
        # ... 其他配置文件
    ],
}

这时再运行代理，你会看到明显的行为变化：它先读取配置文件，然后按照预定流程执行，最后生成PDF输出。配置文件让代理从“通用工具”变成“专属助手”。

2.3 第三步：处理输出——从沙盒中提取成果

代理在沙盒内生成PDF后，你需要将其提取到本地。这里使用Gemini Files API：

import requests

def download_pdf(environment_id, api_key):
    # 下载整个沙盒文件系统的tar快照
    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
    )
    r.raise_for_status()
    
    # 从tar中提取PDF文件
    with tarfile.open(fileobj=BytesIO(r.content)) as tar:
        member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
        with open("digest.pdf", "wb") as f:
            f.write(tar.extractfile(member).read())

这种方法的好处是 完整性 ：你获得的是沙盒在任务完成后的完整快照，不仅包括目标PDF，还有中间文件、日志等调试信息。在实际项目中，你可以直接集成到同一流程中，无需单独下载步骤。

3. 托管代理的进阶用法：状态管理和配置持久化

基础功能跑通后，接下来解决两个生产环境关键问题：如何延续会话？如何避免每次传递配置？

3.1 会话延续：利用environment_id和interaction_id

沙盒在互动完成后不会立即销毁，而是保留7天。这让你可以进行多轮对话优化：

# 第一轮：生成初始摘要
stream1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="",  # 依赖AGENTS.md中的工作流程
    environment=environment_config,  # 包含配置文件的字典
    stream=True,
)
env_id, inter_id = extract_ids(stream1)

# 第二轮：基于已有成果进行优化
stream2 = client.interactions.create(
    agent="antigravity-preview-05-2026", 
    input="为每篇报道添加重要性评分（1-5星）",
    environment=env_id,  # 重用同一沙盒（文件、安装的包都在）
    previous_interaction_id=inter_id,  # 继承对话历史
    stream=True,
)

这两个ID分别管理不同维度的状态：

environment_id ：保持文件和系统状态。代理可以访问前一次运行创建的所有文件，继续使用已安装的软件包。
previous_interaction_id ：保持对话上下文。代理记得之前讨论过什么，避免重复提取或分析。

这种设计特别适合迭代优化场景：生成初稿→基于反馈修改→最终定稿，全程无需重新抓取或处理数据。

3.2 配置持久化：从内联到命名代理

每次调用都内联传递配置可行，但不优雅。更好的方案是创建命名代理：

# 一次性注册配置
agent = client.agents.create(
    id="my-digest-agent",  # 自定义标识符
    base_agent="antigravity-preview-05-2026",
    description="每日技术摘要代理，包含编辑规范和PDF生成",
    base_environment={  # 注意是base_environment不是environment
        "type": "remote",
        "sources": [/* 同样的配置内容 */],
    },
)

# 后续调用简化很多
stream = client.interactions.create(
    agent="my-digest-agent",  # 使用注册的ID
    input="",  # 可覆盖或扩展配置中的指令
    environment="remote",  # 无需再传递sources
    stream=True,
)

命名代理的好处不仅仅是代码简洁： 配置在Google端集中管理 ，版本一致，更新方便。团队不同成员可以调用同一代理保证行为一致，而不需要每人维护一套配置文件。