@sema-agent/core

技能简介

@sema-agent/core 是一款纯 TypeScript/Node.js 实现的无状态、任务化 AI Agent 引擎——以库的形态交付，模型由你自行选择和注入。它不是一个聊天产品或托管服务，而是一个完整的 Agent 运行时引擎，负责模型轮次循环、工具调用、MCP 服务器集成、会话记忆、自动上下文压缩和多 Agent 委派，最终返回机器可执行的结果。

核心能力

• 无状态任务化设计：每个任务自带完整配置（模型、提示词、工具、MCP、Skill、限额），跑完返回 TaskResult，状态语义明确（completed | blocked | failed | timeout | suspended | needs_review）
• Claude Code 级工具面：内置工具集与 Claude Code 工具契约对齐，覆盖文件读写、Shell 执行（含后台）、grep/glob 搜索、子 Agent 委派、todo/plan 等
• 模型无关：通过注入流式补全函数工作，内置 OpenAI 兼容端点（vLLM、Ollama、OpenRouter、DeepSeek、OpenAI）和 Anthropic Messages API 两种 Brain 适配器
• 持久化检查点：任务可在审批闸、预算上限或显式检查点处挂起并恢复，背后是 File 或 Postgres 的 CheckpointStore
• 记忆引擎：带作用域的长期记忆，MemoryBackend 可插拔（文件或 Postgres），配合自动上下文压缩，长任务不会撑爆上下文窗口
• 多 Agent 体系：子 Agent 委派、team 讨论、runWorkflow 确定性编排、可选 observer agent
• 流式优先：每个任务发出带类型的 TaskEvent 流（推理增量、文本增量、工具生命周期、进度、诊断），经 createTaskServer 可直接暴露为 SSE
• 内建安全模型：工具策略 allow/ask/deny、按 principal 授权、Shell 闸门、可持久化的审批挂起
• 极简依赖：运行时仅依赖 typebox 和 @modelcontextprotocol/sdk，5400+ 确定性 vitest 测试完全离线可跑

工作原理

@sema-agent/core 的核心是 Runner 类。集成方通过以下三步完成接入：

第一步：定义 Brain（模型适配器）

import { createOpenAIBrain } from "@sema-agent/core";

const brain = createOpenAIBrain({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.openai.com/v1",
});

也支持 Anthropic Messages API 和自定义兼容网关。

第二步：创建 Runner 实例

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

const model: Model = {
  id: "gpt-4o-mini",
  name: "GPT-4o Mini",
  api: "openai-completions",
  provider: "openai",
  baseUrl: "https://api.openai.com/v1",
  cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 128000,
  maxTokens: 4096,
};

const runner = new Runner({
  brain,
  models: { main: model },
});

第三步：运行任务

const res = await runner.runTask({
  objective: "用三个要点总结 SSE 与 WebSocket 的取舍",
  model: "main",
  sessionId: "chat-42",
});

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

Runner.runTask 返回机器可读的 TaskResult，status 字段表明任务最终状态，result 为最终回复文本。任务可中断、可恢复、可在多 Agent 场景中相互委派。

安装配置

环境要求

• Node.js 20 及以上
• 一个 OpenAI 兼容网关（流式 + function calling）或 Anthropic Messages API

安装命令

npm install @sema-agent/core
# 或
yarn add @sema-agent/core
# 或
pnpm add @sema-agent/core

60 秒上手

1. 安装 SDK：npm install @sema-agent/core
2. 定义 Brain（OpenAI 兼容网关或 Anthropic）：const brain = createOpenAIBrain({ apiKey })
3. 创建 Runner 并注入 Brain：const runner = new Runner({ brain, models: { main: model } })
4. 调用 runTask：const res = await runner.runTask({ objective: "你的任务", model: "main" })
5. 检查结果：console.log(res.status, res.result)

使用步骤

基础任务执行

const res = await runner.runTask({
  objective: "读取当前目录的 package.json，用三个要点总结项目",
  model: "main",
  sessionId: "proj-001",
});

挂载自定义工具

import { defineTool } from "@sema-agent/core";
import Type from "typebox";

const getWeather = defineTool({
  name: "GetWeather",
  description: "查询城市天气",
  parameters: Type.Object({ city: Type.String() }),
  async execute({ city }) {
    return { weather: `${city}：晴，25°C` };
  },
});

const res = await runner.runTask({
  objective: "北京今天天气如何？",
  model: "main",
  tools: [getWeather],
});

集成 MCP 服务器

const res = await runner.runTask({
  objective: "查询我的 GitHub 仓库列表",
  model: "main",
  mcpServers: [
    { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
  ],
});

多 Agent 委派

const res = await runner.runTask({
  objective: "分析前端代码库并生成测试报告",
  model: "main",
  subAgents: [
    { name: "analyzer", objective: "分析代码库结构", model: "main" },
    { name: "tester", objective: "基于分析结果编写单元测试", model: "main" },
  ],
});

持久化会话与恢复

import { FileCheckpointStore } from "@sema-agent/core/checkpoints";

const runner = new Runner({
  brain,
  models: { main: model },
  checkpointStore: new FileCheckpointStore("/tmp/checkpoints"),
});

// 任务挂起后，可通过同一 sessionId 恢复
const resumed = await runner.resumeTask({ sessionId: "chat-42" });

适用场景

• AI 应用集成：在自有产品中嵌入完整的 Agent 能力，无需自行实现 Agent 循环
• 多模型评测：通过 Runner 配置多个模型，快速对比不同模型的执行效果
• 任务编排：在复杂工作流中，通过检查点和子 Agent 委派实现可控的多步骤执行
• 私有化部署：引擎纯本地运行，不依赖外部服务，数据完全自主可控
• 教育与研究：无状态设计使实验可重复，适合 Agent 系统研究和教学
• 工具开发与调试：内置对齐 Claude Code 的工具集，可用于开发新的 Agent 工具

适用人群

• AI 应用开发者：需要在产品中集成 Agent 能力的工程师
• Agent 框架研究者：需要可组合、可观测、可中断的实验环境
• DevOps/平台工程师：需要用编程方式控制 AI 任务执行流程
• AI 智能体产品经理：需要理解 Agent 引擎架构以便规划产品能力边界

官方链接

• npm：https://www.npmjs.com/package/@sema-agent/core
• 文档：https://github.com/sema-ai/sema-agent（docs/ 目录）
• SDK 指南：https://github.com/sema-ai/sema-agent/tree/main/docs/sdk