Agent、Environment、Session 与 Event
| 概念 | 说明 | 类比 |
|---|---|---|
| Agent | 由已安装 Agent 程序驱动的云端 Agent。 | 云端同事 |
| Environment | Session 使用的 Agent 程序、沙箱、模型连接、网络访问和生命周期设置。 | 办公桌和工具箱 |
| Session | Agent 的一次有状态运行，包含消息、Event 和当前状态。 | 一项具体工作 |
| Event | Session 产生的实时输出和状态变化。 | 工作进度实时播报 |
从部署到运行 Agent
部署 AstraBox
在 Docker 主机、Kubernetes 或已有基础设施中运行 AstraBox 服务和 OpenSandbox。
配置 Environment
选择 Agent 程序、沙箱镜像、模型连接、网络访问和生命周期。
创建 Agent
选择 Environment 和模型；只有 Agent 需要时，才添加系统提示词、MCP 服务器、Plugin、Skill 或代码仓库。
启动 Session 并接收 Event
发送消息、查看实时输出、回答问题或审批；浏览器关闭后，稍后仍可回来继续。
让云端 Agent 进入产品和日常工作
断开连接后继续工作
运行编程、研究、运维和其他任务，不依赖开发者电脑或浏览器一直在线。
在自己的产品中使用 Agent
从应用中启动并跟踪 Agent 任务，不需要另外开发和维护 Agent 运行平台。
并行运行互不影响的任务
使用多个 Session 处理批量请求，并分别保存每个 Session 的状态和输出。
按计划或事件启动任务
把 Agent 接入定时任务、Webhook、外部系统或消息平台，并为每次执行保存 Run 记录。
在终端里管理 AstraBox，也可以交给编程助手
AstraBox CLI 无需打开网页控制台，就能配置和使用本地或远程部署。命令结果可以输出为 JSON，Claude Code、Codex 等编程助手也能替你运行这些命令。
astrabox init --from-deployment
astrabox diff -f astrabox.yaml
astrabox apply -f astrabox.yaml
astrabox run researcher "总结本周的仓库变更"
astrabox get sessions --output json
astrabox mcp serve
配置即代码
把部署中的 Environment 和 Agent 导出为
astrabox.yaml，用diff预览修改，再用apply应用。应用只会创建和更新资源，从不删除。在命令行派发任务
run会启动一个 Session、发送任务并流式输出回复。加上--session可以继续已有的 Session。便于程序读取的输出
加上
--output json后，命令无论成功还是失败都只输出一个 JSON 对象，每类失败还有各自的退出码。同样的操作也能作为 MCP 工具
astrabox mcp serve通过 stdio 把 schema、get、export、diff、apply、status 和 run 提供为 MCP 工具，供调用工具而不是运行 Shell 命令的客户端使用。
AstraBox 让 Agent 持续在线，OpenSandbox 负责沙箱
客户端连接 AstraBox。AstraBox 对调用方进行身份验证、保存 Session 状态、通过 OpenSandbox 创建或恢复沙箱，再把任务交给所选 Agent 程序。Event 实时返回，Session 记录保存在沙箱之外。
- 01网页控制台 / API请求 · 实时输出
- 02Session 服务流式输出 · 审批 · Session 存储
- 03OpenSandbox沙箱生命周期
- 04Agent 程序沙箱内的 AstraBox 服务 · 工作区
- 05模型服务由部署者配置
实线表示正在传递的请求和 Event，虚线表示 AstraBox 单独保存的 Session 记录。在支持快照的部署中，暂停会保留沙箱文件；恢复时会基于这些文件重新启动进程。
用 Python 插件接入你自己的基础设施
Python 包可以为下面每个扩展接口提供自己的实现。实现注册在卡片所示的插件组中，AstraBox 按名称选用。名称不存在时会直接报错，不会退回默认实现。
Agent 程序
astrabox.providers.engine内置：随 AstraBox 提供的全部 Agent 程序
沙箱后端
astrabox.providers.sandbox内置：运行在 Docker 或 Kubernetes 上的 OpenSandbox
模型服务
astrabox.providers.model内置：LiteLLM 网关
消息平台
astrabox.providers.channel内置：消息平台网关、通用 JSON Webhook
身份提供方
astrabox.web.identity内置：本地模式、OIDC、已验证 JWT、可信身份请求头
Secret Store
astrabox.providers.secrets内置：本地加密、AWS KMS
数据存储
astrabox.providers.repository内置：PostgreSQL、MongoDB、SQLite
工作区存储
astrabox.providers.storage内置：挂载卷、Amazon EFS
远程 MCP 服务来源
astrabox.providers.extensions内置：管理员在 AstraBox 中保存的配置、LiteLLM MCP 网关
astrabox.testing 提供可复用的一致性测试套件，可以在你自己的测试中检查沙箱后端、工作区存储、消息平台、Agent 程序和数据存储的实现。