@sema-agent/core

Claude Code 级 agent 引擎,以库的形态交付——模型你自己带。

@sema-agent/core 是一个无状态、任务化的 TypeScript/Node AI agent 引擎。LLM 由你提供 (任意 OpenAI 兼容网关,或 Anthropic Messages API);引擎负责完整的 agent 循环——模型轮次、 原生工具调用、MCP 服务器、会话记忆、自动上下文压缩、多 agent 委派——并返回机器可读的结果。

const res = await runner.runTask({ objective: "...", model: "main" });

它是什么 / 不是什么

它是:

• 一个库(npm install @sema-agent/core),嵌进你自己的服务、CLI 或产品里。 一个 Runner 实例、普通函数调用、带类型的事件流。
• 模型无关。"大脑"是注入的流式补全函数。内置两类适配器:OpenAI 兼容的 /v1/chat/completions 端点(vLLM、Ollama、OpenRouter、DeepSeek、OpenAI)与 Anthropic Messages API。路由、故障转移、模型角色都是配置项。
• **设计上无状态。**一个任务自带全套配置(模型、提示词、工具、MCP、skill、限额), 跑完返回一个 TaskResult。持久化——会话、检查点、长期记忆、workflow 日志——全部 藏在存储接口后面,可用文件或 Postgres 落地。

它不是:

• 不是聊天应用、CLI 产品或托管服务。没有 UI,也没有必须部署的服务端 (可选提供一个可嵌入的 HTTP/SSE 服务器 createTaskServer)。
• 不绑定任何模型厂商。不带 API key、没有默认模型、不回传数据。
• 不是提示词模板或"链式"框架。它是完整的 agent 运行时:循环、工具挂载、 安全闸门、持久化层,一个不少。

核心亮点

• **Claude Code 对齐的工具面。**内置 agent 工具集(文件读/写/编辑、支持后台执行的 shell、 grep/glob 搜索、子 agent 委派、todo/plan 面……)对齐 Claude Code 的工具契约, 并持续用活体探针验证。
• **持久化检查点与人在环。**任务可以在审批闸、预算上限或显式检查点处挂起,稍后恢复—— 甚至在另一个进程或机器上——背后是可插拔的 CheckpointStore(内存/文件/Postgres)。 任务状态语义明确:completed | blocked | failed | timeout | suspended | needs_review。
• **记忆引擎。**带作用域的长期记忆,MemoryBackend 可插拔(文件或 Postgres); 配合自动压缩,长任务不会撑爆上下文窗口,也不会丢线索。
• **多 agent。**子 agent 委派、team 讨论、确定性的 runWorkflow 编排(带可恢复日志), 以及可选启用的 observer agent(旁观并引导正在运行的 agent)。
• **流式优先。**每个任务发出带类型的 TaskEvent 流(推理增量、文本增量、工具生命周期、 进度、诊断),经 createTaskServer 可直接接 SSE。
• **内建安全模型。**工具策略的 allow/ask/deny 语义、按 principal 的授权、shell 闸门、 可持久化的审批挂起——不是事后补丁。
• **小而诚实。**运行时依赖只有两个(typebox、@modelcontextprotocol/sdk)。 5400+ 条确定性 vitest 测试完全离线可跑(npm test),其中包括一个真实的 stdio MCP 服务器。
• **源码可得。**BUSL-1.1:个人/教育/研究/非商用生产免费;2030-07-13 自动转 Apache-2.0。 见许可。

60 秒上手

要求:Node ≥ 20,以及一个 OpenAI 兼容网关(流式 + function calling)。

npm install @sema-agent/core

import { Runner, createOpenAIBrain, type Model } from "@sema-agent/core";

// 1) 描述模型(指向你自己的网关)
const model: Model = {
  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
  api: "openai-completions", provider: "vllm",
  baseUrl: "http://localhost:8000/v1",          // 你的网关,结尾不带 /chat/completions
  reasoning: true, input: ["text", "image"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 262144, maxTokens: 4096,
};

// 2) 建 Runner(brain = 外部 LLM;models = 你的模型目录)
const runner = new Runner({
  brain: createOpenAIBrain(),
  models: { main: model },
});

// 3) 跑一个任务
const res = await runner.runTask({
  objective: "用三个要点总结 SSE 与 WebSocket 的取舍。",
  model: "main",
  sessionId: "chat-42",   // 传同一个 id 即继续对话;不传则开新会话
});

console.log(res.status);  // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
console.log(res.result);  // 最终回复文本

接下来:挂工具(defineTool、内置 SQL 工具、任务级 MCP)、逐 token 消费事件流、 或把 Runner 暴露成 HTTP + SSE 服务——SDK 指南按主题分章覆盖, 从 01 – Getting Started 读起。

文档导航

| 文档 | 内容 | |------|------| | SDK 指南(目录) | 完整 SDK 文档入口,按主题分 10 章 | | 01 – Getting Started | 安装、60 秒集成、核心概念、可运行示例 | | 02 – Runner and Tasks | Runner、RunnerDeps、TaskSpec、TaskResult、任务状态语义 | | 03 – Brains and Models | Brain 契约、OpenAI/Anthropic 适配器、故障转移、模型角色、推理强度 | | 04 – Tools and MCP | defineTool、SQL 工具、issue 工具、MCP 集成 | | 05 – Streaming and the HTTP Server | TaskEvent 协议、SSE、createTaskServer | | 06 – Sessions, Memory, and Compaction | 会话存储、自动压缩、长期记忆后端 | | 07 – Multi-Agent | 子 agent、team 讨论、teacher 模式 | | 08 – Workflows | 确定性 runWorkflow 编排与可观测性 | | 09 – Security and Policies | 工具策略、审批、shell 闸门、人在环监督 | | 10 – Extension Points | 自定义 brain、会话存储、执行环境、Postgres 适配器 | | docs/ARCHITECTURE.md | 引擎内部结构 | | docs/TESTING.md | 测试体系与运行方式 | | docs/REFERENCES.md | 设计脉络与外部参考 | | docs/ROADMAP.md | 项目方向 | | CONTRIBUTING.md | 如何参与贡献 | | SECURITY.md | 漏洞报告 |

本地开发

npm install
npx tsc --noEmit     # 类型检查(应为 0 错误)
npm test             # vitest:全量确定性套件,离线,无需网关
npm run smoke        # mock brain 端到端冒烟

需要真实网关的活体示例在 src/examples/。

许可

BUSL-1.1(Business Source License)。

• 个人、教育、研究及非商用生产环境免费。
• 商用生产环境需向许可方取得授权。
• 2030-07-13 自动转为 Apache-2.0。

准确条款以 LICENSE 文件为准。