跳到主要内容

OpenAgentKernel（官方 SDK）

@cloudbase/open-agent-kernel（OAK）是 CloudBase 官方的服务端 Agent SDK，Apache-2.0 开源。它内置了 Agent 开发中重复度最高的基础设施——会话持久化、多轮上下文、MCP 工具接入、人工审批（HITL）、用户长期记忆、沙箱执行——让你只写业务逻辑。

快速开始​

前置条件：Node.js 22+、一个云开发环境的 envId、环境的服务端 API Key（获取地址）。

npm install @cloudbase/open-agent-kernel@beta
import { createAgent } from "@cloudbase/open-agent-kernel";

process.env.TCB_API_KEY = "your-cloudbase-api-key";

const agent = createAgent({
  envId: "your-env-id",
  model: "deepseek-v4-pro",
  systemPrompt: "你是一个智能助手，请帮我回答用户的问题",
});

const session = await agent.startSession({ userId: "user-1" });

for await (const event of session.send("一句话解释：什么是 Serverless？")) {
  if (event.type === "message_delta") process.stdout.write(event.text);
  if (event.type === "session_idle") break; // 本轮结束
}

模型字符串写法默认走 CloudBase AI 网关，用 TCB_API_KEY 鉴权；也可以传 { id, apiKey, apiBaseUrl } 接入自带 endpoint 的模型。

在控制台创建​

打开 CloudBase 控制台的 Agent 板块，新建 Agent 时选择官方 cloudbase-agent 模板，得到的就是一个 OpenAgentKernel 项目：会话持久化、MCP 工具、人工审批开箱即用，创建完成即可在「接入 & 调试」页直接对话。

需要深度定制时，在「本地开发」页按指引操作：

tcb fn code download   # 把代码拉到本地
# 修改代码……
tcb fn deploy          # 部署回云端

控制台负责托管、日志和调试入口，OpenAgentKernel 负责运行时。

核心配置​

createAgent(config) 的常用字段：

字段必填说明
envId是云开发环境 ID，模型网关、数据库、存储、沙箱都以它为锚点
model是模型 ID（走 CloudBase AI 网关）或 { id, apiKey, apiBaseUrl } 完整配置
systemPrompt否系统提示词（Agent 的人设与行为约束）
mcpServers否MCP server 配置，支持进程内 / 本地 stdio / 远程 HTTP 三种
permissions否工具审批（HITL）：requireApproval 支持 '*'、工具名数组或函数
session否会话持久化，默认落云开发数据库（表前缀 oak_）
storage否多模态附件存储，默认落云开发云存储
sandbox否远程沙箱（当前内测中，如有需求请联系我们）
userMemory否用户长期记忆，同步到云开发云存储、跨会话生效
credentials视场景腾讯云 SecretId/SecretKey；仅有 TCB_API_KEY 时会话/审批/记忆也能持久化，多模态附件上传等需要它

完整字段与默认值见 GitHub README 的「完整参数说明」。

配置 MCP 工具​

const agent = createAgent({
  envId,
  model: "glm-5.2",
  systemPrompt: "你是一个智能助手",
  mcpServers: {
    // 远程 HTTP MCP
    remote: {
      type: "http",
      url: "https://example.com/mcp/v1",
      headers: { Authorization: "Bearer xxx" },
    },
    // 本地 stdio MCP
    stdio: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
    },
  },
});

工具名规则为 mcp__{serverName}__{toolName}。进程内自定义工具的写法见 README「MCP 工具扩展」。

工具审批（HITL）​

const agent = createAgent({
  envId,
  model: "glm-5.2",
  permissions: {
    requireApproval: ["database_delete", "reset_password"],
  },
});

命中的工具调用会暂停并发出 tool_approval_required 事件，业务层展示确认交互后调用 session.respondApproval() 继续执行。

会话持久化与跨进程恢复​

会话记录默认持久化到云开发数据库，不依赖进程内存。第二次函数调用时用 conversationId 恢复上下文：

const session = await agent.startSession({ userId: "user-1" });
const conversationId = session.id;

// 另一个进程 / 下一次函数调用
const resumed = await agent.resumeSession(conversationId);

事件流​

session.send() 返回 AsyncIterable<SessionEvent>：

事件含义
message_delta模型输出增量文本，流式渲染用
message_complete本条输出的完整文本
tool_call / tool_result工具调用与结果
tool_approval_required等待人工审批
session_idle本轮结束（reason: completed / requires_action / aborted / error）
error运行错误

OAK 的事件流是协议中立的：接入 SSE、AG-UI 或自定义协议时，由业务层做事件映射。

部署与接入​

写好的 Agent 部署到云开发：

客户端与渠道接入沿用现有指南：Web / Node.js / 小程序 / cURL / 微信渠道。

从可视化界面配置迁移​

此前在控制台可视化界面上配置的项，在代码里都有对应位置：

可视化界面配置项现在的做法
人设 / 角色设定createAgent 的 systemPrompt
模型选择model 字段
工具 / MCPmcpServers 配置
敏感操作确认permissions.requireApproval
欢迎语 / 开场问题见下方「动态配置」——存数据库，改配置不改代码

动态配置欢迎语与开场问题​

欢迎语和开场问题是界面展示层的数据，不建议写死在代码里。推荐把它们存到云开发数据库的一张配置表，运行时读取——修改配置立即生效，不需要重新部署：

// 云函数入口：每次请求时读取配置表
const db = app.database();
const { data } = await db.collection("agent_config").doc("my-agent").get();

const agent = createAgent({
  envId,
  model: data.model,
  systemPrompt: data.systemPrompt,
});

前端（含 Agent UI 组件）同样从这张配置表读取 welcomeMessage 和 openingQuestions 渲染开场界面。这个模式下，人设、欢迎语、开场问题都成为数据而不是代码，改动它们和改一条数据库记录一样。

常见问题​

TCB_API_KEY 是什么？ 云开发环境的服务端 API Key，用于默认的模型网关调用。它与腾讯云平台凭证（SecretId/SecretKey）不是一回事，后者用于让 SDK 直接操作云开发资源。

哪些能力需要 credentials？ 会话持久化、审批状态、用户记忆在仅有 TCB_API_KEY 时即可工作；多模态附件上传、沙箱内 CloudBase 工具的租户隔离等需要传 credentials。

沙箱现在能用吗？ Sandbox 能力当前内测中，如有需求请联系我们。