概览
在自托管的云端沙箱中运行已安装的 Agent 程序。
AstraBox 是开源、自托管的 Agent 运行平台，可将已安装的 Agent 程序变成随时可用的云端 Agent。你无需自建 agent loop、管理工具执行沙箱或处理长连接——只需在管理台或通过 API 定义 Agent、启动 Session，即可在云端运行复杂任务并实时接收结果。
核心概念
| 概念 | 说明 | 类比 |
|---|---|---|
| Agent | 由已安装 Agent 程序驱动的云端 Agent | "云端同事" |
| RuntimeProfile | Session 的运行环境，包含 Agent 程序、沙箱、模型连接和网络配置 | "办公桌和工具箱" |
| Session | 一次对话，包含已接收输入、回复、工具、交互与保存的历史 | "一项具体工作" |
| Assistant | 同一用户的多次对话共用的个人工作区 | "个人工作区" |
| Deployment | 为 Agent 或 Assistant 启动工作的定时、Webhook 或消息渠道绑定 | "任务触发器" |
| Event | Session 中产生的实时事件流 | "工作进度实时播报" |
Agent 适合可复用任务与团队使用，Assistant 适合跨对话 持续进行的个人工作。使用指引按任务列出控制台、API、CLI 和 MCP 的入口。 程序原生状态和对话历史保存在平台数据库中；沙箱释放或丢失后仍需保留工作区文件时，需要 配置可选的持久工作区存储。
工作流程
- 配置 RuntimeProfile。 选择 Agent 程序、沙箱、模型连接和网络配置。
- 定义 Agent。 选择 RuntimeProfile、模型、系统提示词（system prompt）和扩展。
- 启动 Session。 使用 Agent 创建运行实例。
- 发消息 + 收事件。 向 Session 发送消息，然后通过 HTTP 实时接收 Agent 消息、执行进度和状态变更。
输入接口返回持久保存的接收回执，输出通过独立的事件流到达。Agent 程序决定何时取走消息、 一条回复回答哪些输入，以及何时需要审批。离开页面后仍可回到保存的对话；浏览器连接断开 并不代表 Agent 已停止。中断、恢复和历史的使用方式见 Session。
开箱即用的企业级基建
一次部署就带齐团队通常要自己拼装的几块：
- 模型网关。 默认内置 LiteLLM 网关。Agent 只选路由名；上游密钥、路由、预算和请求日志都留在服务端，后面可以接 Anthropic、OpenAI 兼容服务或本地模型。参见连接模型服务。
- 团队登录。 预集成 Casdoor 作为身份提供方，支持 OIDC、组织与角色；管理员在 Casdoor 中添加身份提供方后，可用 Google、Microsoft Entra ID、Okta、GitHub、SAML、LDAP 等方式登录，也支持钉钉、飞书、企业微信。安装脚本设置一项即可开启，参见设置团队登录。
- 隔离沙箱。 基于 OpenSandbox，单台 Docker 主机或 Kubernetes 集群都能运行，并通过预热容量让对话在数秒内启动和恢复。
- 凭证不进沙箱。 Vault 凭证在沙箱的出站边界注入，Agent 只看得到占位符。参见保护 Agent 使用的凭证。
- 触发器与消息通道。 定时任务、签名 Webhook 和消息平台可以在无人值守时启动 Agent。参见让 Agent 自动运行。
管理与扩展 AstraBox
- 命令行与 MCP。 AstraBox CLI 在
astrabox.yaml中声明 RuntimeProfile 和 Agent，应用修改，并给 Agent 发送任务。命令结果可以输出为 JSON，每类失败都有各自的退出码，因此脚本和编程助手可以用它管理部署；astrabox mcp serve还把同样的操作提供为 MCP 工具。 - Python 插件。 安装的 Python 包可以接入 Agent 程序、沙箱后端、模型服务、消息平台、身份提供方、Secret Store、工作区存储、调度器和远程 MCP 服务来源。详见扩展接口。
快速验证连通性
# 验证本地 API，列出所有 Agent
curl -s http://127.0.0.1:8088/api/v1/agents
成功响应格式：
{
"code": "OK",
"message": "success",
"data": []
}
适用场景
- 长时间异步任务 — 代码审查、大规模重构、自动化测试生成
- API 集成 — 在后端服务中嵌入 Agent 能力，无需另外维护运行时
- 批量处理 — 并行启动多个 Session 处理批量请求
- 定时任务 — 创建定时 Deployment，周期性运行 Agent 完成巡检或报告
认证方式
团队部署使用 OAuth 访问令牌时，API 请求需要携带以下 Header：
| Header | 值 | 说明 |
|---|---|---|
Authorization | Bearer <access token> | 由已配置身份提供商签发的访问令牌 |
本地模式不启用 API 认证，只适合通过回环地址使用。团队部署使用已配置的身份提供方，例如 OIDC、验证 JWT、可信网关请求头或已安装的身份提供方。详见团队认证。
分页机制
不同资源的列表接口采用各自的分页结构。分页列出了支持的游标和页码形式。
常见问题
Q: AstraBox Agent 和本地的 Agent 程序可以同时使用吗？
A: 可以。本地使用适合在一台电脑上交互开发；AstraBox Agent 则可以远程访问、执行长时间任务并接入其他系统，两者互补。
Q: 一个 Agent 可以同时运行多少个 Session？
A: 同一个 Agent 可以同时运行多个活跃 Session，实际数量取决于部署的计算资源和沙箱容量。
Q: 数据安全如何保障？
A: 默认情况下，每个 Session 运行在隔离沙箱中；RuntimeProfile 也可以使用平台支持的 Agent 共享沙箱。Session 记录保存在沙箱之外；工作区生命周期取决于 RuntimeProfile 的空闲处理方式和存储配置。
下一步
- 快速开始 — 运行第一个 Agent
- 定义 Agent — 深入了解 Agent 配置
- RuntimeProfile — 配置运行配置
- Session — 管理 Session 生命周期