如果你正在构建AI代理应用，可能已经体会过传统方案的复杂性：选择框架、定义工具、编写编排代码、打包容器、部署到云服务……整个过程在代理真正执行任务前就需要大量工程投入。但现在，Google为Gemini API的托管代理带来了四项关键功能扩展，彻底改变了这一局面。

这些新功能的核心价值在于： 将代理开发从基础设施管理转变为纯业务逻辑配置 。过去需要数十行代码和复杂部署流程的任务，现在只需几个Markdown配置文件和一次API调用就能完成。更重要的是，这些扩展不是简单的功能叠加，而是构建了一个完整的代理开发生态系统。

本文将深入解析这四项新功能的具体实现方式、适用场景以及与传统方案的对比。无论你是正在评估代理技术选型，还是已经在使用现有框架，这些扩展都将显著降低你的开发门槛和运维成本。

1. 托管代理新功能的核心价值

1.1 从基础设施到业务逻辑的转变

传统代理开发面临的最大挑战不是算法复杂度，而是工程复杂度。以构建一个简单的新闻摘要代理为例，传统方案需要：

# 传统方案：ADK + Cloud Run
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution
from google.adk.runners import FastApiRunner

# 定义代理和工具
agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,
    tools=[google_search, built_in_code_execution],
)

# 部署为HTTP服务
runner = FastApiRunner(agent=agent)
app = runner.app

# 还需要Dockerfile、部署脚本、监控配置等

而新的托管代理方案只需：

# 新方案：纯API调用
from google import genai

client = genai.Client()
stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Fetch tech news and generate digest PDF",
    stream=True,
    environment={
        "type": "remote",
        "sources": [config_files]  # 你的业务逻辑配置
    },
)

这种转变的核心在于 责任边界的重新划分 ：Google负责所有基础设施（沙盒环境、工具执行、状态管理、扩缩容），开发者只需关注业务逻辑（指令、技能、工作流）。

1.2 四项扩展功能概述

新扩展的四个核心功能构成了完整的代理开发闭环：

1. 配置驱动的代理定制 ：通过Markdown文件定义代理行为和技能，无需代码变更
2. 持久化环境状态管理 ：沙盒环境可保持7天活跃状态，支持多轮对话和文件持久化
3. 技能库与自动发现 ：技能作为可复用组件，支持跨项目共享和自动加载
4. 命名代理与配置烘焙 ：一次配置，永久生效，后续调用只需代理ID

这四项功能共同解决了代理开发中的四个关键痛点：定制复杂度、状态丢失、代码重复和部署繁琐。

2. 配置驱动的代理定制

2.1 配置文件结构与作用

新功能的核心是配置文件驱动模式。代理的所有行为都通过三个层级的配置文件定义：

.agents/
├── AGENTS.md              # 全局指令和角色设定
└── skills/
    └── digest-pdf/
        ├── SKILL.md       # 具体技能的工作流程
        └── scripts/
            └── generate_pdf.py  # 技能执行的具体代码

AGENTS.md 定义代理的"人格"和工作原则：

# Tech Digest Agent

## Role
You are a tech news curator that identifies important developments.

## Workflow
1. Scan Hacker News front page
2. Extract top 5 stories with scores and comments
3. Write concise summaries focusing on technical impact
4. Generate formatted PDF report

## Constraints
- Prioritize open source and developer tools
- Avoid marketing fluff and hype
- Keep summaries under 150 words each

SKILL.md 定义具体技能的执行步骤：

# digest-pdf Skill

## Description
Generates a formatted PDF from news summaries

## Steps
1. Read summaries.json from workspace
2. Format content with headers and bullet points
3. Apply consistent styling
4. Save as digest.pdf

2.2 配置加载机制

配置文件通过environment参数的sources字段注入：

environment={
    "type": "remote",
    "sources": [
        {
            "type": "inline",
            "target": ".agents/AGENTS.md",
            "content": AGENTS_MD,
        },
        {
            "type": "inline", 
            "target": ".agents/skills/digest-pdf/SKILL.md",
            "content": SKILL_MD,
        }
    ]
}

这种机制的优势在于：

• 版本控制友好 ：配置文件可与代码库一起管理
• 热更新支持 ：修改配置无需重新部署代理
• 环境隔离 ：不同环境可使用不同配置版本

2.3 与传统配置方式的对比

方面	传统方式	新配置驱动方式
修改代理行为	需要代码变更+重新部署	修改Markdown文件+重新调用
版本管理	代码版本与配置混合	纯文本配置，diff清晰
环境差异	需要条件代码或多个部署	不同环境加载不同配置文件
学习曲线	需要理解框架API	只需编写Markdown说明

3. 持久化环境状态管理

3.1 环境生命周期模型

新功能引入了明确的环境生命周期管理：

# 首次调用创建新环境
stream1 = client.interactions.create(
    agent=BASE_AGENT,
    input="Initial task",
    environment="remote",  # 创建新沙盒
    stream=True
)

# 获取环境ID用于后续调用
environment_id = get_environment_id_from_stream(stream1)

# 后续调用复用同一环境
stream2 = client.interactions.create(
    agent=BASE_AGENT, 
    input="Follow-up task",
    environment=environment_id,  # 复用现有沙盒
    stream=True
)

环境的关键特性：

• 7天活跃期 ：最后一次交互后保持7天可用
• 完整文件系统 ：包含所有安装的包和生成的文件
• 计算资源隔离 ：4CPU/16GB RAM专用资源
• 自动清理 ：非活跃期后自动回收资源

3.2 多轮对话支持

对话状态的保持通过两个ID实现：

# 第一轮交互
stream1 = client.interactions.create(
    agent=BASE_AGENT,
    input="Fetch Hacker News headlines",
    environment=environment_id,
    stream=True
)
interaction_id1 = get_interaction_id_from_stream(stream1)

# 第二轮交互（保持对话上下文）
stream2 = client.interactions.create(
    agent=BASE_AGENT,
    input="Now summarize the most technical story", 
    environment=environment_id,
    previous_interaction_id=interaction_id1,  # 关键参数
    stream=True
)

这种设计解决了代理应用中的关键问题： 任务执行的连续性和上下文保持 。

3.3 实际应用场景

场景一：迭代优化输出

# 第一轮：生成初版摘要
input1 = "Generate tech news digest"
# 第二轮：基于初版进行优化  
input2 = "Make the summaries more concise and add technical depth ratings"
# 第三轮：格式调整
input3 = "Convert to PDF with better formatting"

场景二：复杂任务分解

# 任务1：数据收集
input1 = "Scrape latest AI research papers"
# 任务2：数据分析（复用任务1的结果）
input2 = "Analyze trends in the collected papers"
# 任务3：报告生成（基于前两步）
input3 = "Generate research trend report"

4. 技能库与自动发现机制

4.1 技能作为一等公民

技能（Skills）在新架构中不再是附属功能，而是核心组件。每个技能包含：

# 技能元数据（自动发现部分）
- Name: digest-pdf
- Description: Generates PDF reports from structured data
- Version: 1.0
- Input: summaries.json
- Output: digest.pdf

# 技能实现（按需加载部分）
## Steps
1. Validate input JSON structure
2. Apply report template
3. Generate PDF with reportlab
4. Save to workspace

4.2 自动发现与按需加载

技能系统采用"渐进式披露"设计：

# 代理启动时只加载技能元数据
# 当代理决定使用某个技能时，才加载完整实现

# 技能触发流程：
1. 代理分析任务需求
2. 匹配可用技能元数据
3. 按需加载完整SKILL.md
4. 执行技能中定义的步骤

这种设计显著减少了初始上下文长度，提高了代理的响应速度。

4.3 技能开发最佳实践

技能设计原则：

• 单一职责：每个技能只做一件事
• 明确接口：定义清晰的输入输出格式
• 错误处理：包含完整的验证和异常处理
• 文档完整：提供使用示例和限制说明

示例技能结构：

skills/
├── web-scraper/
│   ├── SKILL.md
│   └── scripts/
│       └── scrape.py
├── data-analyzer/
│   ├── SKILL.md
│   └── scripts/
│       └── analyze.py
└── report-generator/
    ├── SKILL.md
    └── scripts/
        └── generate_report.py

5. 命名代理与配置烘焙

5.1 从临时配置到持久化代理

新功能最重要的改进之一是命名代理支持：

# 创建持久化命名代理
agent = client.agents.create(
    id="tech-digest-agent",  # 唯一标识符
    base_agent=BASE_AGENT,
    description="Daily tech news digest with PDF generation",
    base_environment={
        "type": "remote",
        "sources": [all_config_files]  # 烘焙所有配置
    }
)

# 后续调用只需代理ID
stream = client.interactions.create(
    agent="tech-digest-agent",  # 使用命名代理
    input="",
    environment="remote",
    stream=True
)

5.2 配置烘焙的优势

简化调用流程：

• 无需每次传递配置文件内容
• 调用代码更加简洁
• 减少网络传输数据量

版本控制与治理：

• 代理配置集中管理
• 变更控制和安全审计
• 环境间的一致性保证

5.3 代理生命周期管理

完整的代理管理API：

# 创建代理
agent = client.agents.create(...)

# 列出所有代理
agents = client.agents.list()

# 获取代理详情
agent_details = client.agents.get("tech-digest-agent")

# 更新代理配置
updated_agent = client.agents.update("tech-digest-agent", ...)

# 删除代理
client.agents.delete("tech-digest-agent")

6. 完整实战示例：技术摘要代理

6.1 环境准备与依赖安装

# 克隆示例项目
git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

# 安装依赖管理工具uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 配置API密钥
cp .env.example .env
# 编辑.env文件设置GEMINI_API_KEY

# 安装依赖
uv sync

6.2 核心代码实现

run_digest.py - 主执行逻辑：

from google import genai
import os
from dotenv import load_dotenv

load_dotenv()

def run_digest():
    client = genai.Client()
    
    # 加载配置文件
    AGENTS_MD = load_source(".agents/AGENTS.md")
    SKILL_MD = load_source(".agents/skills/digest-pdf/SKILL.md")
    GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")
    
    stream = client.interactions.create(
        agent="antigravity-preview-05-2026",
        input="",  # AGENTS.md中已定义完整工作流
        stream=True,
        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md", 
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },
    )
    
    # 处理流式响应
    environment_id, interaction_id = run_stream(stream)
    
    # 保存ID用于后续操作
    set_key(".env", "ENVIRONMENT_ID", environment_id)
    set_key(".env", "INTERACTION_ID", interaction_id)
    
    print(f"Digest completed. Environment: {environment_id}")

if __name__ == "__main__":
    run_digest()

6.3 结果下载与验证

download_pdf.py - PDF下载逻辑：

import requests
import tarfile
import tempfile
import os
from dotenv import load_dotenv

load_dotenv()

def download_pdf():
    environment_id = os.getenv("ENVIRONMENT_ID")
    api_key = os.getenv("GEMINI_API_KEY")
    
    # 下载环境快照
    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
        allow_redirects=True,
    )
    r.raise_for_status()
    
    # 提取PDF文件
    with tempfile.NamedTemporaryFile() as tmp:
        tmp.write(r.content)
        tmp.flush()
        
        with tarfile.open(tmp.name, "r") as tar:
            # 查找PDF文件
            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=".", filter="data")
    
    print("PDF downloaded successfully")

if __name__ == "__main__":
    download_pdf()

6.4 运行验证

# 运行摘要生成
uv run python run_digest.py

# 下载生成的PDF
uv run python download_pdf.py

# 查看结果
open digest.pdf

7. 与传统方案的详细对比

7.1 基础设施需求对比

能力	ADK + Cloud Run方案	托管代理新方案
沙盒配置	Dockerfile + 自定义镜像	自动提供Ubuntu沙盒
工具定义	Python代码注册	内置工具+技能配置
包管理	Dockerfile中pip install	沙盒内动态安装
流式传输	自定义SSE基础设施	stream=True参数
会话管理	数据库+上下文注入	environment_id + interaction_id
部署流程	CI/CD流水线	无需部署

7.2 开发体验对比

传统方案开发流程：

1. 编写代理逻辑代码
2. 定义工具函数
3. 配置Dockerfile
4. 设置Cloud Run部署
5. 测试部署结果
6. 迭代优化

新方案开发流程：

1. 编写配置文件
2. 调用API测试
3. 迭代优化配置
4. （可选）保存为命名代理

7.3 成本对比分析

传统方案成本构成：

• Cloud Run实例费用
• 容器镜像存储费用
• 网络出口费用
• 开发维护时间成本

新方案成本构成：

• API调用token费用
• 环境计算资源（预览期免费）
• 显著降低的开发时间成本

8. 最佳实践与注意事项

8.1 配置管理最佳实践

文件组织规范：

.agents/
├── AGENTS.md                      # 主配置文件
├── skills/
│   ├── common/                    # 通用技能
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── project-specific/          # 项目特定技能
│       ├── SKILL.md
│       └── scripts/
└── templates/                     # 配置模板
    ├── basic-agent.md
    └── advanced-skills.md

配置版本控制策略：

• 配置文件与代码同步版本化
• 使用语义化版本命名代理
• 维护配置变更日志

8.2 性能优化建议

上下文长度优化：

• 保持AGENTS.md简洁明了
• 使用技能目录代替详细描述
• 按需加载技能详细内容

调用模式优化：

• 批量处理相关任务，减少环境创建
• 合理设置stream参数平衡实时性和性能
• 使用命名代理避免配置重复传输

8.3 安全注意事项

权限最小化原则：

• 代理只拥有执行任务所需的最小权限
• 敏感配置通过环境变量管理
• 定期审查代理行为和输出

数据安全保护：

• 避免在配置中硬编码敏感信息
• 使用沙盒隔离保护本地系统
• 实施输出内容审核机制

9. 常见问题与解决方案

9.1 环境管理问题

问题：环境ID丢失或失效

• 症状：无法恢复之前的环境状态
• 原因：环境超过7天非活跃期被清理
• 解决方案：实现环境ID的持久化存储和定期刷新

问题：环境状态不一致

• 症状：同一环境不同调用结果异常
• 原因：并发访问或状态污染
• 解决方案：确保环境单线程使用或实现状态隔离

9.2 配置相关问题

问题：技能未正确加载

• 症状：代理无法识别或执行特定技能
• 原因：文件路径错误或格式不正确
• 解决方案：验证技能元数据和文件路径配置

问题：代理行为不符合预期

• 症状：输出结果与配置指令不一致
• 原因：指令冲突或上下文过长
• 解决方案：简化指令结构，使用技能分解复杂任务

9.3 性能与成本问题

问题：API调用成本过高

• 症状：简单任务消耗大量token
• 原因：上下文过长或指令不精确
• 解决方案：优化配置结构，使用更精确的指令

问题：响应时间过长

• 症状：代理执行简单任务需要较长时间
• 原因：工具调用链过长或网络延迟
• 解决方案：优化任务分解，减少不必要的工具调用

10. 未来发展方向与应用场景

10.1 技术演进趋势

基于当前的功能扩展，可以预见以下发展方向：

生态系统完善：

• 官方技能市场或仓库
• 第三方技能开发和分发机制
• 企业级代理管理和监控工具

能力增强：

• 更丰富的内置工具集
• 多模态处理能力扩展
• 实时协作和共享环境支持

10.2 典型应用场景

技术内容聚合：

• 每日技术新闻摘要
• 开源项目更新跟踪
• 学术论文趋势分析

开发辅助工具：

• 代码审查助手
• 文档生成和维护
• 自动化测试报告

业务自动化：

• 数据分析和报告生成
• 客户支持自动化
• 内部流程优化

这四项新功能扩展标志着AI代理开发进入了一个新阶段：从技术探索转向规模化应用。对于开发者而言，现在正是深入学习和实践的最佳时机，这些能力将为你的项目带来显著的效率提升和成本优化。

建议从简单的用例开始实践，逐步掌握配置驱动开发和状态管理的核心模式，为构建更复杂的代理应用打下坚实基础。