---

name: hosted-agents description: 在沙箱环境中构建后台代理。适用于托管编码代理、沙箱虚拟机、Modal 沙箱和远程编码环境。 risk: unknown source: community

托管代理基础设施

托管代理在远程沙箱环境中运行，而非本地机器。设计良好时，它们可提供无限并发、一致的执行环境和多人协作。关键洞察是：会话速度应仅受模型提供商首次令牌生成时间限制，所有基础设施设置应在用户开始会话前完成。

何时使用

在以下情况下激活此技能：

• 构建独立于用户设备运行的后台编码代理
• 设计用于代理工作负载的沙箱执行环境
• 实现具有共享状态的多人代理会话
• 创建多客户端代理接口（Slack、Web、Chrome 扩展）
• 将代理基础设施扩展到超出本地机器限制
• 构建代理生成子代理进行并行工作的系统

核心概念

托管代理解决了本地代理执行的根本限制：资源争用、环境不一致和单用户约束。通过将代理执行移至远程沙箱环境，团队获得无限并发、可复现环境和协作工作流。

架构由三层组成：用于隔离执行的沙箱基础设施、用于状态管理和客户端协调的 API 层，以及用于跨平台用户交互的客户端接口。每层都有特定的设计要求以支持系统扩展。

详细主题

沙箱基础设施

核心挑战 快速启动完整开发环境是主要技术挑战。用户期望近乎即时的会话启动，但开发环境需要克隆仓库、安装依赖和运行构建步骤。

镜像注册表模式 按固定节奏（每 30 分钟效果良好）预构建环境镜像。每个镜像包含：

• 在已知提交处克隆的仓库
• 所有运行时依赖已安装
• 初始设置和构建命令已完成
• 运行应用和测试套件一次后的缓存文件

启动会话时，从最新镜像启动沙箱。仓库最多落后 30 分钟，使与最新代码的同步更快。

快照与恢复 在关键点获取文件系统快照：

• 初始镜像构建后（基础快照）
• 代理完成更改时（会话快照）
• 沙箱退出前用于潜在后续操作

这使后续提示可以即时恢复，无需重新运行设置。

后台代理的 Git 配置 由于镜像构建期间 git 操作不绑定特定用户：

• 在克隆期间生成 GitHub 应用安装令牌用于仓库访问
• 更新 git config 的 user.name 和 user.email 为代理标识
• 使用安装令牌作为 HTTPS 凭据而非 SSH 密钥

API 层设计

会话管理 API 层协调沙箱生命周期和客户端通信：

interface Session {
  id: string;
  sandboxId: string;
  userId: string;
  status: 'provisioning' | 'active' | 'paused' | 'completed';
  createdAt: Date;
  lastActivityAt: Date;
}

关键端点：

• POST /sessions - 创建新会话，触发沙箱配置
• POST /sessions/:id/prompt - 向活动会话发送提示
• GET /sessions/:id/events - SSE 流用于实时更新
• POST /sessions/:id/pause - 快照并暂停沙箱
• POST /sessions/:id/resume - 从快照恢复

多客户端架构 设计 API 以支持多种客户端类型：

• Web 仪表板用于完整会话管理
• Slack 机器人用于对话式交互
• Chrome 扩展用于上下文感知触发
• CI/CD 集成用于自动化工作流

每个客户端通过相同的 API 连接，但可能有不同的认证流程和权限级别。

并发与扩展

代理池 维护预热沙箱池以实现即时会话启动：

• 监控池大小并在低于阈值时补充
• 按仓库/环境类型分隔池
• 实现优雅降级当池耗尽时

子代理生成 对于复杂任务，代理可以生成子代理：

• 父代理将工作分解为并行子任务
• 每个子代理获得自己的沙箱
• 结果通过 API 层聚合回父代理
• 实现超时和失败处理以防止级联故障

安全考虑

沙箱隔离

• 每个沙箱运行在独立的虚拟机或容器中
• 网络访问受限于必要的外部服务
• 文件系统更改限定在会话范围内
• 资源限制防止单个会话影响其他会话

凭据管理

• 使用短期令牌而非长期凭据
• 通过安全注入而非环境变量传递密钥
• 会话结束时自动撤销令牌
• 审计所有凭据访问

实现清单

1. 设置镜像构建管道（30 分钟节奏）
2. 实现沙箱配置和生命周期管理
3. 构建快照/恢复机制
4. 设计并实现会话 API
5. 添加 SSE 事件流
6. 实现代理池管理
7. 添加子代理生成支持
8. 配置安全隔离和凭据管理
9. 构建监控和可观测性
10. 实现客户端 SDK 用于各平台集成