@sema-agent/server

Sema 技术栈的服务端/API 层 —— 装配引擎,服务舰队。

快速开始 · 配置 · HTTP API · 生态导航 · 许可协议

English

它是什么

@sema-agent/server 是 Sema 的服务端/API 实现层:把 @sema-agent/core 引擎、registry 配置、 模型网关与云端 agent 执行能力,装配到一套 HTTP/SSE 契约后面。

它是:

• 一个 HTTP/SSE 服务端 + 装配层。 请求体只带内容(objective、sessionId、scenario 等); 服务端按任务装配其余一切 —— 工具、子智能体角色册、提示词、skill、策略 —— 身份/会话/安全策略由服务端注入,不信 body。凭据只活在服务端闭包里, 不进请求体、不进模型、不进沙箱。
• 无状态设计。 副本是 cattle:docker run 即起一个,挂在负载均衡后想开多少开多少。 持久化状态 —— 会话、run、可重放事件日志、检查点、审批 —— 全在外部 SQL 存储 (任何 MySQL 协议数据库:MySQL/TiDB/MariaDB,或 PostgreSQL;单机场景另有文件持久化的 local 模式)。任意副本都能服务任意 run 的事件流;任务可以在一个副本上挂起、在另一个副本上恢复。
• 完整的服务端能力面(可在 GET /v1/capabilities 发现): 异步 run + 可重放 SSE、持久化检查点 + 人工审批(HITL)、会话与长期记忆、 一份镜像服务多场景、任务级子智能体、确定性 workflow 编排,以及可插拔的沙箱执行通道 (host / local-docker / e2b / k8s / ssh / adb)。

它不是:

• 不是引擎本体。 agent 循环、工具 harness、记忆与检查点机制在 sema-core;本仓以 npm 依赖的方式消费它, 自己出装配、后端与服务契约。
• 不是 CLI。 终端智能体是 sema;它(以及网页端) 都是本服务的客户端。
• 不是部署工具。 一键自托管部署(Docker 单机或 Kubernetes)在 sema-deploy。
• 不是持久化中心。 真相在外部数据库里;服务进程随时可弃。

架构

  HTTP / SSE API 面           装配层                       执行通道
  ────────────────            ──────                       ────────
  /v1/tasks   (同步) ──┐   ┌─ 任务级 spec 装配     ─┐   ┌─ host          (本机直跑)
  /v1/runs    (异步) ──┤   │  场景 · skill          │   ├─ local-docker  (任务级容器)
  /v1/sessions       ──┼──▶│  策略 · 审批门         │──▶├─ e2b           (Firecracker VM)
  /v1/approvals      ──┤   │  registry 配置         │   ├─ k8s           (Kata pod 沙箱)
  /v1/workflows      ──┘   │  模型网关              │   └─ ssh / adb     (真机 / 真设备)
                           └─ @sema-agent/core     ─┘
                                     │
                    持久化存储(MySQL/TiDB · PostgreSQL · 本地文件)
                    会话 · run · 事件日志 · 检查点 · 审批

快速开始

环境要求:Node ≥ 20(npm 路径)+ 一个 OpenAI 兼容模型网关。

# A) npm
npm install @sema-agent/server
MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-chat \
  MODEL_API_KEY=<你的-key> SERVICE_AUTH_TOKEN=<自定> \
  node node_modules/@sema-agent/server/dist/main.js        # → :8090

# B) 容器(零依赖,匿名可拉)
docker run -p 8090:8090 \
  -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-chat \
  -e MODEL_API_KEY=<你的-key> -e SERVICE_AUTH_TOKEN=<自定> \
  ghcr.io/sema-agent/sema-server:latest              # 或 docker.io/claybobby/sema-server:latest

# 提交一个任务
curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>" \
  -H 'content-type: application/json' -d '{"objective":"用一句话回答:1+1 等于几?"}'
# 带指定模型:body 加 "model":"<catalog id>";可用能力见 GET /v1/capabilities

• 分发坐标:npm = @sema-agent/server (npmjs 公开)· 镜像 = ghcr.io/sema-agent/sema-server + docker.io/claybobby/sema-server (均 public,:latest 滚动 / :<sha> 钉版)。
• 随包二进制:包内带两个 bin —— run-local(单机本地 runner)与 sema-up(部署引导脚本)。
• 一键全栈部署(DB + 对象存储 + registry 网站 + 沙箱池,docker/k8s 双路径): sema-agent/sema-deploy。
• 沙箱装包源:缺省 = 官方源(pypi/npmjs/crates.io/…)。中国大陆部署配 SANDBOX_PKG_SOURCE=cn 切国内镜像源(tuna/npmmirror/rsproxy/aliyun),自定义源用 SANDBOX_PKG_SOURCE=custom + SEMA_*_MIRROR/INDEX/REGISTRY 显式 URL。

配置

服务完全由环境变量配置。最核心的一批:

| 变量 | 默认 | 说明 | |------|------|------| | PORT | 8090 | HTTP 监听端口 | | MODEL_GATEWAY_BASEURL | http://127.0.0.1:8000/v1 | OpenAI 兼容网关地址(不带 /chat/completions) | | MODEL_ID | Qwen3.5-35B | 缺省模型 id | | MODEL_API_KEY | — | 网关 key(可选) | | SERVICE_AUTH_TOKEN | — | 调用方需带 Authorization: Bearer <token> | | DB_BACKEND | mysql | SQL 引擎:mysql(任何 MySQL 协议库:MySQL/TiDB/MariaDB;tidb 为兼容别名)/ pg(PostgreSQL)/ local(免 DB 文件持久化)。显式设置 mysql/pg 时 session 自动转 durable | | SESSION_BACKEND | memory* | memory / mysql(durable 会话中心;tidb 别名)/ auto。*显式 DB_BACKEND=mysql/pg 时默认转 durable | | REMOTE_EXEC | 未设 | 沙箱执行通道:host / local-docker / e2b / k8s / ssh / adb;未设 = 进程内 stub(CONFIG_PROVIDER=local 时缺省转 host) | | CONFIG_PROVIDER | 未设 | 配置来源:local(单机文件 config.d/)/ remote(registry 控制面) | | DEFAULT_SCENARIO | code | 请求体未指定场景时的缺省场景 | | SANDBOX_PKG_SOURCE | global | 沙箱内装包源:global(官方源)/ cn(国内镜像)/ custom / none | | SENSITIVE_WRITE_PATTERNS | core 推荐集 | 敏感路径写拒集;逗号分隔值为整体替换,off 关闭 | | MODEL_CONNECT_TIMEOUT_MS | 30000 | 网关连接超时 | | MODEL_FIRST_TOKEN_TIMEOUT_MS | 120000 | 首 token 超时 | | MODEL_IDLE_TIMEOUT_MS | 300000 | 流中 idle 超时(0 关) | | LOG_LEVEL | info | debug / info / warn / error(结构化 JSON 日志) |

完整配置面 —— 成本/配额上限、断路器与 failover、多模型角色、审批门、可观测 (Prometheus /metrics + 可选 OTLP)、registry 控制面、各沙箱通道细项 —— 见 USAGE.md。

HTTP API 概览

一行一个端点族(非全量):

| 端点族 | 服务什么 | |--------|----------| | GET /health · GET /metrics | 存活探针 + Prometheus 指标(/metrics/summary、/metrics/plan-cache) | | GET /v1/capabilities | 部署能力发现 —— 本部署真正能做什么,客户端免 501 探测 | | GET /v1/models | 模型目录(仅名字,不含网关 URL/key) | | POST /v1/tasks · /v1/tasks/stream | 同步任务执行;SSE 变体逐 token 流式输出类型化 TaskEvent | | POST /v1/runs · GET /v1/runs/:id | 异步 run:立即 202,后台续跑,轮询状态/结果 | | GET /v1/runs/:id/events | 可重放 SSE(Last-Event-ID 续订);任意副本可服务任意 run | | POST /v1/runs/:id/cancel / steer / compact · /v1/runs/:id/subagents/:target/steer / resume | run 控制动词:协作式取消、运行中转向、上下文压缩、子智能体转向/恢复 | | /v1/approvals(list · get · decide · stream) | 人工审批中心,底座是持久化检查点;任意副本都能批复 | | /v1/sessions(list · get · fork · init · settings · wake) | 会话列表/检索、审计回溯、fork、启动包 | | /v1/workflows(list · get · stream · agents/:label/steer) | 确定性 workflow 编排 run,带实时流与逐 agent 转向 | | GET /v1/usage · GET /v1/policy | 累计花费(配置配额时)与生效策略只读面 |

生态导航

| 仓库 | 是什么 | |------|--------| | sema-agent/sema | sema CLI 门户 —— 属于你自己的 Claude Code 级智能体:终端、网页、你的云 | | sema-agent/sema-core | 智能体引擎,以库的形式发布 —— @sema-agent/core | | sema-agent/sema-sdk | 本服务的官方 TypeScript SDK(@sema-agent/sdk) | | sema-agent/sema-deploy | 一键部署 —— docker compose 或 k8s(helm),单机到多机 HA | | sema-agent/sema-web | 自托管网页控制台 + registry/配置中心 + orchestrator |

版本策略

1.x = 快速迭代期:BREAKING 变更可能落在 minor(记录于 MIGRATION.md)。生产部署请锁精确版本 (如 @sema-agent/[email protected]);GA 后切 2.0 起严格 semver。

许可协议

BUSL-1.1(Business Source License):

• 个人、教育、研究及非商业生产使用 免费。
• 商业生产使用需要商业授权。
• 2030-07-13 起自动转为 Apache-2.0。

≤ 1.180.1 的已发布副本仍受其发布时的 MIT 约束。