跳转到内容

HTTP API 基于 REST 资源接口 + SSE 事件流。接口定义以 openapi.yaml 为准。

  • 对外 API:/api/v1
  • 内部模型运行时:/internal/v1/models/*(仅 loopback,无需 Authorization)
  • 宿主应用可注入 caller context resolver 接管认证;未注入时使用最小 caller context
  • 异步入口(发消息、触发 action)返回 202
  • 流式输出走 SSE
  • 最终执行状态以 run 资源为准
  • session 发消息默认不会打断当前活跃 run;只有显式传 runningRunBehavior: "interrupt" 才会先取消当前 run
  • session 后续消息队列是服务端资源;可通过 GET /sessions/{id}/queue 读取,并通过 POST /runs/{id}/guide 将已排队消息提升为打断模式

关键边界:session = 上下文边界,run = 执行边界,同 session 内 run 串行。

文件与命令接口刻意保持 E2B 风格的 sandbox 语义: 路由位于 /sandboxes,sandbox 内根目录暴露为 /workspace。这是稳定接口约定,不是临时兼容层。/workspaces API 仍然保留,用于 workspace metadata、catalog 与 lifecycle。

方法路径说明
GET/workspaces列出 workspace
POST/workspaces创建 workspace
POST/workspaces/import导入 workspace
POST/local/workspaces/register注册本机 workspace 路径
POST/local/workspaces/{id}/repair修复本机 workspace 路径绑定
GET/workspaces/{id}获取详情
DELETE/workspaces/{id}删除
GET/workspaces/{id}/catalog获取能力目录
GET/workspaces/{id}/memory/status获取 workspace memory 状态
GET/workspaces/{id}/memory列出 workspace memory index
GET/workspaces/{id}/memory/search搜索 workspace memory
GET/workspaces/{id}/memory/read读取 workspace memory 文件片段
GET/workspaces/{id}/memory/proposals列出 memory proposals
POST/workspaces/{id}/memory/proposals/apply应用 memory proposal
POST/workspaces/{id}/memory/proposals/reject拒绝 memory proposal
方法路径说明
GET/assets/runtimes列出 runtime 资产
POST/assets/runtimes/upload上传 runtime zip
PUT/assets/runtimes/{name}覆盖更新 runtime
DELETE/assets/runtimes/{name}删除 runtime
GET/assets/models列出平台 model 资产
POST/assets/models/upload上传平台 model YAML
PUT/assets/models/{name}覆盖更新平台 model
DELETE/assets/models/{name}删除平台 model
GET/assets/tools列出平台 tool 资产
POST/assets/tools/upload上传平台 tool 定义
PUT/assets/tools/{name}覆盖更新平台 tool
DELETE/assets/tools/{name}删除平台 tool
GET/assets/skills列出平台 skill 资产
POST/assets/skills/upload上传平台 skill
PUT/assets/skills/{name}覆盖更新平台 skill
DELETE/assets/skills/{name}删除平台 skill
方法路径说明
POST/sandboxes创建或解析 sandbox
GET/sandboxes/{id}获取 sandbox 元数据
GET/sandboxes/{id}/files/entries列出目录条目
GET/sandboxes/{id}/files/stat读取文件/目录元数据
DELETE/sandboxes/{id}/files/entry删除条目
PATCH/sandboxes/{id}/files/move移动/重命名
GET/sandboxes/{id}/files/content读取文件
PUT/sandboxes/{id}/files/content写入文件
PUT/sandboxes/{id}/files/upload上传二进制
GET/sandboxes/{id}/files/download下载文件
POST/sandboxes/{id}/directories创建目录
方法路径说明
POST/sandboxes/{id}/commands/foreground前台执行 shell command
POST/sandboxes/{id}/commands/process结构化执行 process
POST/sandboxes/{id}/commands/background启动后台命令
方法路径说明
GET/workspaces/{id}/sessions列出 session
POST/workspaces/{id}/sessions创建 session
GET/sessions/{id}获取详情
GET/sessions/{id}/snapshot获取控制台初始化快照
PATCH/sessions/{id}更新会话设置
DELETE/sessions/{id}删除会话
GET/sessions/{id}/children列出直接子 session / subagent session
GET/sessions/{id}/messages列出消息
POST/sessions/{id}/messages发送消息(202)
GET/sessions/{id}/messages/{messageId}获取单条消息
GET/sessions/{id}/messages/{messageId}/context获取锚点消息上下文
GET/sessions/{id}/queue读取服务端后续消息队列
GET/sessions/{id}/runs列出当前 session 的 runs
GET/sessions/{id}/terminals/{terminalId}读取 session terminal 输出
POST/sessions/{id}/terminals/{terminalId}/input写入 session terminal 输入
POST/sessions/{id}/compact手动 compact
GET/sessions/{id}/eventsSSE 事件流
方法路径说明
GET/runs/{id}获取详情
GET/runs/{id}/steps列出步骤
POST/runs/{id}/cancel取消(202)
POST/runs/{id}/guide将已排队消息提升为引导(202)
POST/runs/{id}/requeue手动重新入队 recovery run
POST/runs/requeue批量重新入队 recovery runs
方法路径说明
POST/workspaces/{id}/actions/{name}/runs触发 action(202)
方法路径说明
GET/model-providers列出 provider
GET/platform-models列出平台模型
POST/platform-models/refresh刷新平台模型
POST/platform-models/refresh/distributed分布式刷新平台模型
GET/platform-models/events平台模型 SSE 更新
POST/internal/v1/models/generate同步生成
POST/internal/v1/models/stream流式生成
方法路径说明
GET/storage/overview存储总览
GET/storage/postgres/tables/{table}检查 PostgreSQL 表
GET/storage/redis/keys扫描 Redis keys
GET/storage/redis/key读取 Redis key
DELETE/storage/redis/key删除 Redis key
POST/storage/redis/keys/delete批量删除 Redis keys
GET/storage/redis/worker-affinity检查 worker affinity
GET/storage/redis/workspace-placements列出 workspace placements
POST/storage/redis/session-queue/clear清理 session queue
POST/storage/redis/session-lock/release释放 session lock
文档内容
openapi.yamlOpenAPI 3.1 规范
workspaces.mdworkspace、catalog、模型可见性
assets.md平台 runtime、model、tool、skill 资产管理
sessions.mdsession 与 message
runs.mdrun 查询与取消
actions.mdaction 手动触发
files.mdsandbox 文件与命令接口
storage.md存储检查与维护接口
models.md模型运行时
streaming.mdSSE 事件流
components.md通用 schema 与错误模型

接口定义以 openapi.yaml 为准。发消息 + 消费流式结果建议配合看 sessions、runs、streaming。