Agent Skills
返回列表
🤖

Upstash Box Python SDK

AI Agent 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/upstash-skills-upstash-box-py。

技能介绍

要解决什么问题

在本地或自有服务器上跑「带 Shell、Git、定时任务和可选浏览器的隔离环境」,又要让 AI Agent 在容器里按 harness 执行,往往意味着自己拼编排、配额和网络策略。Upstash Box 提供云端沙箱容器;本技能对应的 Python SDK 用来用代码创建与管理 Box,发起 agent run、命令执行、文件与 Git 操作,而不是只做 REST 手工调用。

技能如何工作

通过 UPSTASH_BOX_API_KEY 或构造参数里的 api_key 鉴权后,可用同步 Box 或异步 AsyncBox 操作同一套能力。创建 Box 时可注入账号级环境变量、安装 Context7 格式的 Skills、挂载 MCP 服务器,并为出站流量配置 network_policy。

核心流程大致是:Box 生命周期(创建、快照、from_snapshot 恢复为新实例)→ 在容器内用 box.cd() 维护客户端工作目录(默认 /workspace/home)→ Agent Runs 需指定 harness 与模型(如 ClaudeCode、OpenRouterModel 或带 provider 前缀的字符串),也可跑自定义 harness 进程 → Shell / 文件 / Git(克隆发生在箱内,私有仓需 git.token)→ Schedules 以 UTC Cron 跑命令或 agent 提示 → 可选 browser=True 后在 box.browser 上做页面操作(extract / observe / act 等按量计费)。

EphemeralBox 适合最多 3 天的轻量任务:支持 exec、文件、schedule、快照与网络策略,但不含 agent、git、skills、labels、browser 与公网 URL。需要完整能力时用全功能 Box。

适用边界与注意点

  • Agent 配置的入口是 harness(必填),不要再用已废弃的 provider/runner 字段。
  • run.exit_code 仅对 exec 有意义;agent run 为 None。成功时 run.result 多为 stdout,失败时为 stderr。
  • box.cd() 只做客户端路径校验与跟踪,不会改变远端 shell 的 cwd;各 SDK 方法会按该目录相对执行。
  • 删除用 box.delete() 不可恢复;需要状态时先快照。流式 run 提前中断时应 stream.close() / await stream.aclose(),避免 run 悬挂。
  • 超时单位与 JS SDK 一致,均为 毫秒(默认 600000)。

使用场景

  • 需要在隔离容器里 clone 不可信仓库并先收紧 network_policy,再只跑 build/test 命令,避免代码落到本机
  • 要用异步客户端 asyncio.gather 并行创建多个 AsyncBox 并同时发起 agent.run,做批量代码审查或生成任务
  • 在云沙箱里挂 Context7 Skills 与自建 MCP,让 harness 在固定工具集下处理 PR 或内部脚本
  • 开启 browser=True 后对页面做 extract/observe/act,把无头浏览器流程和同一 Box 里的 shell、文件操作串在一起

适合人员

  • 维护 CI/自动化流水线、需要把 agent 与 cron 调度都放进远端沙箱而非自建 VM 的平台工程师
  • 写 Python 集成 Upstash Box、要在 SDK 里区分 Box 与 EphemeralBox 能力边界的后端开发者
  • 给 coding agent 接 MCP 与 Skills,且必须用 network_policy 限制出站访问的安全或 DevOps 工程师
  • 需要 SSH 进 Box 排障或从快照恢复为新实例做实验复现的 SRE / 支持工程师