知识库

知识库为 Agent 提供私有背景知识：把产品文档、FAQ、内部资料接入后，Agent 回答问题时先检索、再依据检索到的内容作答，而不是只靠模型的通用知识。

在云开发中，知识库以 MCP 工具的形式接入 Agent：检索服务对外暴露一个 MCP server，Agent 在 agent.yaml 中声明这个 server，对话时即可调用检索。

本文按实际操作顺序展开：拉代码 → 部署检索服务 → 写配置 → 部署 → 验证。

前置条件

• 已在 CloudBase 控制台创建 Agent，选择官方 cloudbase-agent 模板（即 OpenAgentKernel 项目）
• 本地已安装 CloudBase CLI 并完成 tcb login
• Node.js ≥ 20

第一步：拉取 Agent 代码

在控制台 Agent 详情页的「本地开发」页按指引拉取代码：

也可以直接用 CLI 拉取，<函数名> 即 Agent 对应的云函数名：

tcb fn code download <函数名> ./agent-code -e <环境 ID>

工程结构：

agent-code/
├── agent.yaml           # Agent 配置，见第三步
├── package.json
├── scf_bootstrap        # 云函数启动脚本
├── dist/                # 编译产物
├── node_modules/
└── src/
    ├── index.ts         # HTTP 入口，默认监听 9000 端口
    ├── config.ts        # 配置加载
    ├── managed/
    └── oak-runtime/

第二步：部署知识库 MCP server

知识库 MCP server 是一个独立部署的 HTTP 服务，部署在云托管、云函数或任意可访问的地址均可。下面是基于 @modelcontextprotocol/sdk 的最小实现（无状态模式）：

import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

function buildServer() {
  const server = new McpServer({ name: "kb", version: "1.0.0" });
  server.tool(
    "search",
    "Search the knowledge base. Use when the user asks product-specific questions.",
    { query: z.string().describe("检索关键词") },
    async (args) => {
      const hits = await searchKnowledge(args.query); // 替换为你的检索实现，见下文「检索怎么实现」
      if (hits.length === 0) return { content: [{ type: "text", text: "No relevant documents found." }] };
      return { content: [{ type: "text", text: hits.map((d) => `[${d.id}] ${d.title}\n${d.content}`).join("\n---\n") }] };
    },
  );
  return server;
}

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  // 无状态模式：每个请求新建 server + transport；handleRequest 必须传第三个参数 req.body
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => { transport.close(); server.close(); });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(Number(process.env.PORT ?? 8080));

部署后先自测工具是否注册成功。Streamable HTTP 协议要求请求头带 Accept: application/json, text/event-stream，缺少其中任一个值会返回 406：

curl -X POST https://your-kb-service.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

返回中应包含 search 工具。

检索怎么实现

searchKnowledge 的实现由你决定，常见选择：

• 云开发数据库：把文档切分后连同向量一起存入云开发数据库（PostgreSQL），检索时按向量相似度召回
• 已有的 Elasticsearch 或其他检索服务：在 searchKnowledge 里转发查询
• 小规模知识（几十条以内）：直接用数组做关键词匹配

第三步：在 agent.yaml 中声明知识库

agent.yaml 位于工程根目录，是 Agent 的配置文件，随代码包一起部署。在其中声明 MCP server 并挂载给 Agent：

name: my-agent
model: deepseek-v4-pro
system: 你是一个智能助手，回答用户问题前先检索知识库。

mcp_servers:
  - type: url
    name: kb
    url: https://your-kb-service.example.com/mcp

tools:
  - type: mcp_toolset
    mcp_server_name: kb
    default_config:
      enabled: true
      permission_policy:
        type: always_allow

mcp_servers 声明有哪些 MCP server，tools 声明把其中哪些挂给 Agent 使用。两者要配对出现——只写 mcp_servers 而不在 tools 里挂载，Agent 不会调用它。

如果工程根目录还没有 agent.yaml，新建一个即可，name / model / system 三个字段需要写全。

字段说明

字段	必填	说明
name	是	Agent 名称
model	是	模型 ID，需已在控制台开通
system	是	人设 / 系统提示词
mcp_servers[].type	是	目前仅支持 url，即远程 HTTP MCP server；其他取值会被忽略且不报错
mcp_servers[].name	是	server 别名，供 tools 引用
mcp_servers[].url	是	MCP server 的 HTTP 地址
tools[].mcp_server_name	是	对应 mcp_servers[].name
tools[].default_config.enabled	否	是否启用，默认启用
tools[].default_config.permission_policy.type	否	always_allow 自动调用，always_ask 每次询问

配置来源与优先级

运行时按固定顺序取用配置，命中即生效：

1. AGENT_CONFIG / AGENT_CONFIG_B64 环境变量 —— 面向工具链的动态下发通道，正常开发不需要手工设置
2. agent.yaml —— 推荐方式，配置随代码走，可进版本库
3. AGENT_NAME / AGENT_MODEL / AGENT_SYSTEM 环境变量 —— 三个字段的兜底

其中 AGENT_NAME / AGENT_MODEL / AGENT_SYSTEM 这三个环境变量，只要存在就以它们为准，会覆盖前两层里的同名字段。启动日志只打印最终生效值。

建议把配置集中在 agent.yaml

如果函数上设置过 AGENT_MODEL，在 agent.yaml 里改 model 不会生效——name 和 system 改了却生效，容易误判。把这几个环境变量清掉、统一由 agent.yaml 管理，行为最容易预期。

查看和修改函数环境变量：控制台「云函数 / 托管 → 函数配置 → 环境变量」，或

tcb agent update <Agent ID> --env <KEY>=<VALUE>

第四步：部署回云端

agent.yaml 需要随代码包一起部署才会在云上生效——运行时读取的是代码包解压后的 /var/user/agent.yaml。只在本地创建而不部署，云端读不到。

cd ./agent-code
tcb fn code update <函数名> --dir . -e <环境 ID>

命令会提示确认，选择 Update with current config。部署期间函数处于 Updating 状态，此时 tcb fn code download 等操作会被拒绝。

第五步：验证

触发一次冷启动

配置在进程启动时读取。部署完成后，已有实例可能仍在服务旧配置，此时行为不会变化。在控制台「接入 & 调试」页发一两条对话，触发新实例拉起即可。

查看启动日志

tcb logs search --query "function_name:\"<函数名>\" AND (\"[Agent]\" OR \"[Config]\")" \
  --timeRange 30m -e <环境 ID>

挂载成功时的日志：

[Config] Loaded agent config from: /var/user/agent.yaml
[Agent] Name: my-agent
[Agent] Runtime: managed
[Agent] Model: deepseek-v4-pro
[Agent] Tools: 1 configured
[Agent] MCP Servers: 1 configured
[KernelAdapter] kernel Agent created (id=...)

对照排查：

现象	含义
日志里没有 Init Report ... Coldstart	本次请求由旧实例服务，配置尚未重新加载，再发一两条对话
[Config] Loaded agent config from: /var/user/agent.yaml	配置已从代码包中的 yaml 加载
[Config] No agent.yaml or AGENT_CONFIG found, using environment variables	没找到 yaml，正在使用默认值，检查文件是否随代码包部署
[Agent] MCP Servers: 0 configured	yaml 中缺少 mcp_servers，或 type 不是 url 被跳过
[Agent] Tools: 0 configured	声明了 mcp_servers 但没有在 tools 里挂载

发一条对话

在控制台「接入 & 调试」页提一个只有知识库里才有答案的问题。Agent 会先调用 mcp__kb__search 检索，再依据检索内容回答，事件流中能看到对应的 tool_call 记录。

小程序、Web 等客户端的调用方式不变，沿用现有接入指南即可。

常见问题

改了 agent.yaml，部署后没有变化

依次检查：

1. 日志里有没有 Init Report ... Coldstart。没有说明还是旧实例，再发一两条对话触发冷启动
2. [Config] 那行是不是 Loaded agent config from: /var/user/agent.yaml。如果是 No agent.yaml or AGENT_CONFIG found，说明文件没进代码包，确认它位于部署目录根部

人设生效了，但模型没换

函数上的 AGENT_MODEL 环境变量优先于 agent.yaml 中的 model，参见配置来源与优先级。

MCP server 还没部署好，会影响 Agent 启动吗

不会。MCP server 是按需连接的，启动阶段只登记配置、不做连通性检查。地址暂时不可达时 Agent 正常启动、普通对话不受影响，只有真正调用检索工具时才会失败。可以先完成配置再部署检索服务。

支持哪些类型的 MCP server

目前仅支持 type: url，即通过 HTTP 访问的远程 MCP server。其他类型的声明会被静默忽略、不报错，表现为 [Agent] MCP Servers 计数少于预期。

能不能不重新部署代码就改配置

agent.yaml 的改动需要重新部署代码包。运行时另有一条基于环境变量的动态下发通道（AGENT_CONFIG），面向配套工具链使用，不建议手工设置。