定义 Agent
Agent 会在 AstraBox 中运行已安装的 Agent 程序，并使用所选模型、系统提示词、扩展和运行配置。一个 Agent 可被多个 Session 复用。保存 Agent 不会打断正在执行的任务；AstraBox 在首次准备或重建 Session 运行实例时，会读取最新保存的 Agent 和运行配置。
核心要素
可以把 Agent 理解为一份”岗位说明书”：
| 要素 | 含义 |
|---|---|
| 模型 | Agent 的智力水平 |
| 系统提示词 | Agent 的行为准则 |
| MCP 服务器 | Agent 可以调用的外部服务 |
| Skill 和 Plugin | Agent 可以使用的流程和扩展 |
Agent 在 Session 中执行任务。AstraBox 让 Agent 随时可用，创建或复用它的沙箱，实时返回进度，并把 Session 保存在沙箱之外。
字段参考
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_id | string | — | 系统生成的 Agent ID |
name | string | 是 | Agent 名称 |
description | string | 否 | Agent 的说明 |
use_cases | array | 否 | 这个 Agent 适合处理的任务示例 |
display_meta | object | 否 | display_name、icon 和 tags。标签可被搜索，并显示在主页的 Agent 卡片上，点击即按该标签筛选：最多 5 个，存储时转为小写、去掉开头的 #、空格换成 - |
categories | array | 否 | Agent 在主页上所属分类的 ID，取自管理员定义的分类（GET /api/v1/agent-categories）；不存在的 ID 会被拒绝 |
model | string | 是 | 模型标识，详见下文 |
system | string | 否 | 系统提示词 |
engine_options | object | 否 | 运行配置所选 Agent 程序定义的高级配置 |
skills | array | 否 | 加载到 Session 沙箱中的 Skill 来源 |
mcp_servers | object | 否 | MCP 服务器配置，以服务器名称为键 |
artifacts_enabled | boolean | 否 | Agent 的对话是否提供内置 artifacts 工具。创建时省略则为 true；参见 Artifacts |
default_repo | object | 否 | 每个新 Session 默认克隆的代码仓库 |
packages | array | 否 | 要安装的引擎原生扩展包及经过审核的版本；每项用 kind 写明环境所用引擎声明的类型，例如 Claude Code 插件仓库是 claude-plugin |
runtime_profile_name | string | 是 | 提供 Agent 程序、沙箱、网络策略和模型连接的运行配置 |
exposure_mode | string | 否 | Agent 的使用入口：chat_only、mcp_only 或 both |
idle_hibernate_seconds | integer | 否 | Session 运行实例空闲多久后执行运行配置设置的暂停或回收方式 |
prepared_capacity | integer | 否 | 同一时刻能在已准备好的运行时上开始的新对话数量，范围 0 到 1000，0 表示关闭预热。创建时省略则由部署决定：能够预热的部署为 1，否则为 0；参见预热 |
enabled | boolean | 否 | Agent 是否可以启动新 Session |
visibility | string | — | Agent 鉴权模式：public、private 或 allowlist，通过 Agent access 接口管理 |
admins | array | — | 可以管理 Agent 的账户，通过 Agent access 接口管理 |
allowed_user_ids | array | — | allowlist 鉴权允许的账户，通过 Agent access 接口管理 |
version | integer | — | 用于乐观并发控制的序号，从 1 开始；用于准备 Agent 运行实例的设置发生变化时递增 |
state | string | — | Agent 生命周期状态 |
created_at | string | — | 创建时间，ISO 8601 格式 |
updated_at | string | — | Agent 的设置、访问权限或凭证绑定最后一次变更的时间。平台记在 Agent 上的运行时状态不会改变它，保存未改动的设置也不会。 |
model
model 为字符串类型，指定 Agent 使用的模型。AstraBox 会把这个标识传给所选运行配置配置的模型服务：
| 值 | 说明 |
|---|---|
ANTHROPIC_MODEL 配置的值 | 内置 Anthropic 兼容路由提供的模型 |
| 所选模型服务提供的任意模型 ID | 外部 LiteLLM 网关、OpenAI 兼容服务或本地模型服务提供的模型 |
自托管部署不受固定厂商目录限制。模型服务地址和凭证配置参见连接模型服务。
原生运行配置 JSON
先选择运行配置：对应的 Agent 程序会声明可覆盖的 JSON 配置块。每个编辑器都会说明 原生目标及合并规则。平台校验块名称、JSON 对象格式和平台管理的字段；块内厂商配置的 含义及未知字段的处理方式，由已安装的 Agent 程序决定。适配器将配置传给程序自身的 文件或 API。凭证通过受管理的模型连接和 Credential Vault 分配，不作为运行配置 JSON 中的覆盖值。
| Agent 程序 | engine_options 配置块 | 原生目标 |
|---|---|---|
| Claude Code | sdk_options | ClaudeAgentOptions；嵌套的 settings 序列化后传给 CLI 的 --settings。 |
| Codex | config | thread/start 和 thread/resume 的配置覆盖值。 |
| Codex | turn_start | 每次 turn/start 的参数对象。 |
| Codex | model_catalog | 完整的原生 models.json 对象。 |
| Pi | settings | 当前对话的 ~/.pi/agent/settings.json 根对象。 |
| DeepSeek Harness | session_create | 原生 session/create 请求参数，包括 agentPreset。 |
输入 {} 表示传入空对象，清空编辑器则移除对应配置块。运行配置 JSON 与模型网关配置
各有用途，可以同时使用。部署配置了 LiteLLM 管理地址时，模型字段会提供相应入口。
Session 身份、通信设置和已分配的模型凭证由平台管理。
MCP 服务器、Skill 和 Plugin
读写文件、编辑代码和执行命令等原生工具由所选 Agent 程序提供，AstraBox 不会重新定义这些工具。Agent 使用相应程序支持的原生格式配置 MCP 服务器、Skill 和 Plugin。在「管理台 > Agent」中打开一个 Agent，即可选择管理员配置的远程 MCP 服务和 Skill，也可以直接添加 Plugin 仓库。
更多配置参见 MCP 服务器、Skill 和 Plugin。
Connector
Agent 管理页面上的 Connectors 卡片向 Agent 的调用者提供 Gmail、Notion 等办公应用。每个与 Agent 发起对话的人都使用自己的登录授权，在 连接 页面中连接；没有连接这个应用的人会收到 connector 发出的登录请求。由消息渠道、定时计划或 webhook 发起的对话没有这样的人，因此不提供任何 connector。connector 是一个以应用命名的 MCP 服务器，所以不能与 Agent 自己的 MCP 服务器同名。connector 的工作方式和管理员的配置步骤参见 连接办公应用。
管理 Agent
网页控制台支持下面这些常用操作。通过程序管理 Agent 时，请参见 HTTP API。
创建
打开「管理台 > Agent」，点击「创建 Agent」，填写名称、运行配置和模型。系统提示词和所有扩展都可以不配置；根据这个 Agent 要完成的任务选择即可。完成后点击「创建」。
预热
预热会在下一个 Session 使用前准备运行实例。Agent 配置、所选 Skill 与 Plugin，以及 Agent 程序启动会在可领取前完成，新对话领取的是已经运行的沙箱，而不是从头启动一个。 Agent 页面中的预热状态会显示是否已有就绪资源，或准备是否失败。
「预备容量」（prepared_capacity）是同一时刻无需等待就能开始的新对话数量，范围 0 到
1000。Agent 的沙箱服务能运行预备沙箱池时，新建 Agent 默认为 1；对内置的 OpenSandbox
服务而言，这意味着设置了 ASTRABOX_AGENT_PREWARM_REDIS_URL，所有随附的 Compose 部署
都会设置它。其他情况下新建 Agent 默认为 0，保存时大于 0 的预备容量会被拒绝，因为无法
为它准备任何资源。这个值在创建 Agent 时写入 Agent，创建表单也从这个值开始显示；之后
修改部署不会改变已有 Agent 的值。
每一份容量是一个等待对话的已准备运行时：每个对话独立使用沙箱时是一个空闲沙箱，Agent 的 对话共用沙箱时是沙箱里的一个席位（一个已经启动、相互隔离的 Agent 程序）。共用的沙箱在准备 时放入内存所能容纳的全部席位，AstraBox 保留足够多的空闲沙箱，使席位总数达到预备容量； 第一个取走这种沙箱的对话会把其余席位留给后面的对话。对话取走一个空闲沙箱后，AstraBox 在 几秒内补上一个。全部取完后，后续对话要先启动运行时，需要数秒，直到补齐；Agent 页面的 「预备容量」卡片会显示最近一次发生这种情况的时间。请按预计同时开始的对话数设置。修改数值 立即生效，不会丢弃已经准备好的单位。
预备容量大于 0 且 Agent 及其运行配置处于启用状态时，会一直占用资源。各种部署下每份容量
的占用见为已准备沙箱规划容量。
要为某个 Agent 关闭预热，把「预备容量」设为 0（创建时在高级设置中，创建后在 Agent
页面的「运行设置」中），或在创建、更新时传入 "prepared_capacity": 0。
查看
打开「管理台 > Agent」可以查看当前账号有权访问的 Agent。选择一个 Agent，即可查看它的模型、运行配置和能力；拥有管理权限时，还可以修改配置和鉴权设置。
更新
打开 Agent，修改需要调整的部分，然后点击该部分的「保存」。控制台会自动携带当前 version；如果其他人同时修改了这个 Agent，保存会返回冲突，不会静默覆盖对方的修改。保存不会重新配置正在执行的任务；AstraBox 在首次准备或重建 Session 运行实例时使用最新设置。
需要按已保存的配置重新拉取 Skill 和 Plugin 时，在预热状态中选择重新预热。 操作前先保存或撤销待提交修改。重新预热只替换尚未被 Session 领取的准备资源，现有 Session 使用的沙箱保持运行。固定到 commit 的仓库会使用该 commit，直到配置中的 版本被修改。
删除
当前通过 DELETE /api/v1/agents/{agent_id} 删除 Agent。删除会使 Agent 不再可用，并开始释放它拥有的运行资源。现有 Session 记录和对话内容仍会保留，但它引用的 Agent 被删除后，Session 无法再启动或重建运行实例。
版本管理
Agent 采用乐观并发控制（OCC）机制：
- 创建时
version从1开始 - 成功修改运行字段后，
version自动加 1 - 更新请求可以携带当前
version；如果与服务端版本不一致，AstraBox 返回 409AGENT_VERSION_CONFLICT - 更新请求也可以不带
version，但应用更新时检测到并发写入仍会返回 409
这避免了多人 / 多系统并发修改时互相覆盖。
处理 409 冲突
当持有的版本已过期时：
{
"code": "AGENT_VERSION_CONFLICT",
"message": "agent version mismatch: supplied 1, stored 2",
"data": null
}
恢复步骤：
GET最新 Agent 拿到当前version- 合并自己的变更
- 用新
version重新PUT
最佳实践
- 命名规范 — 用
团队-用途格式，如backend-code-review、frontend-test-gen - 提示词精炼 —
system字段写清角色、输出格式、限制条件 - 最小权限原则 — 只添加任务需要的 MCP 服务器、Skill、Plugin、代码仓库、凭证和网络地址
- 帮用户找到 Agent — 写清楚说明，选好它所属的分类，并用标签写下用户会搜索的词
- 自动更新时检查版本 — 服务修改 Agent 时携带版本，让并发修改产生冲突，而不是互相覆盖
已安装的 Agent 程序需要把工作拆分为 child run 时，参阅 Multiagent 编排。
常见问题
Q：Agent 的网络策略如何与扩展和凭证配合？
A：
需要开放全部互联网访问时使用 networking.type: unrestricted。limited 只允许
列出的地址，以及 AstraBox 能确定的模型地址、平台回调地址和 Plugin 仓库地址；只有
allow_mcp_servers 为 true 时才允许 Agent 声明的远程 MCP。Agent 自己的 Skill、Plugin
和 MCP 服务所在的主机，只有是公网地址或已被列出时才会放行，参见
Agent 自身扩展可以访问的范围。Credential
Vault 分配保持 RuntimeProfile 记录原样，并把 binding 地址加入沙箱的有效策略。
Q：更新 Agent 后，正在运行的 Session 会受影响吗？
A：保存不会打断正在执行的任务。Session 会继续使用当前运行实例；需要首次准备或重建运行实例时，AstraBox 会读取最新保存的 Agent 和运行配置。
Q：MCP 服务器、Skill 和 Plugin 列表可以为空吗？
A：可以。Agent 程序仍然保留自己的原生能力。只有在需要外部服务、可复用流程或扩展命令时才需要添加。
Q：name 字段有长度限制吗？
A：AstraBox 没有设置固定长度限制。名称应当简洁，让用户可以在控制台和集成中辨认。
Q：如何恢复先前的 Agent 配置？
A：AstraBox 不保存可选择的历史配置。建议在更新前自行保存 Agent 配置；需要恢复时，使用最新 version 通过 PUT 写回先前保存的配置。
下一步
- 运行配置 — 配置 Agent 的运行位置
- 启动 Session — 使用 Agent 创建 Session
- MCP 服务器、Skill 和 Plugin — 配置扩展和凭证
- Multiagent 编排 — 查看和控制委派的 child run