如何用Nakama打造第一个AI Agent:Profile配置、Soul文件与工具权限设置实战

原创2026-11-01 14:20:20450 阅读

如何用Nakama打造第一个AI Agent:Profile配置、Soul文件与工具权限设置实战

Nakama 是一个面向团队的 AI Agent 工作区(AI workspace),你可以在它的 Web 面板里像用 ChatGPT 一样和 Agent 聊天,而每个 Agent(Profile)都拥有独立的提示词文件、工具权限、技能(Skills)和记忆。本文将带你从零开始,完成 Nakama AI Agent 搭建 的完整流程:创建 Profile、编写 Soul 文件、配置工具权限,最终让你的第一个 AI Agent 跑起来 🚀

Nakama Agent 管理页面:包含 System prompt 与 SOUL.md、STYLE.md、INSTRUCTIONS.md、MEMORY.md 等 Soul 文件卡片

1️⃣ 先认识 Nakama 的三个核心概念

在动手之前,先记住三个词,它们构成了 Nakama AI Agent 平台的全部骨架:

概念 一句话解释
Profile 一个 Agent 的定义:角色、模型、系统提示词、工具、技能、记忆都挂在它下面
Soul 文件 决定 Agent "是谁"的一组 Markdown 文件(身份、语气、行为规则、记忆)
Tools Agent 被允许执行的动作,权限按 Profile 隔离,是最主要的风险控制手段

官方文档对这三块有完整说明,建议对照阅读:

💡 心智模型很简单:同一个大模型,配上不同的 Profile 和工具,就会变成完全不同的 Agent。写作型机器人可能一个工具都不需要,研究型机器人需要 web_search + web_fetch,运维型机器人则需要文件工具和邮件。

2️⃣ 创建你的第一个 Profile

Nakama 首次安装后会自动为每个组织(Organization)创建两个 Profile:

  1. Default Bot:组织默认 Agent(isDefault: true),当你没有指定 Profile 时由它应答;
  2. Super Nakama:超级 Agent(isSuper: true),可以在聊天里帮你创建新 Profile、审批后执行更高级的操作。

创建新 Agent 有两条路径:

  • 面板创建:打开左侧 Agent 页面,点击创建,填写 Agent id、名称并勾选初始工具集,点击 Create agent;
  • 让 Super Nakama 代劳:在聊天中直接提出需求,它会在聊天里起草 Soul 文件和工具方案,等你明确说 OK 之后才调用 create_profile 真正落库——这是 Nakama 的"确认优先"(confirm-first)设计,避免误操作。

Nakama 创建 Agent 对话框:可选择 Agent id、底层 Agent、名称,并为新 Profile 勾选 write_file、read_file、search_files 等初始工具

每个 Profile 包含这些关键字段(详见 profiles.mdx):

字段 含义
name 面板里显示的人类可读名称
model 该 Profile 专属的模型(不填则用工作区默认模型)
systemPrompt 存在数据库里的基础指令
tools / mcpServers / skills 允许使用的工具、MCP 服务器、可复用技能
soulActive Soul 文件是否存在并生效

📌 一个好习惯:一个 Profile 对应一个明确用途。当你需要不同的语气、工具或知识时,就创建新的 Profile,而不是往一个 Agent 里塞所有东西。

3️⃣ 用 Soul 文件给 Agent 注入"灵魂"

Soul 文件是 Nakama 最有特色的设计:它们不是代码,而是一组放在磁盘上的 Markdown 文件,决定了 Agent 的人格与长期行为。新组织的 Default Bot 自带预填写好的 Soul 文件,你可以直接在面板 Agent → Prompt 标签页中编辑,也可以在聊天里请 Super Nakama 帮你改(改完仍需你确认)。

四个 Soul 文件各司其职:

文件 作用 类比
SOUL.md 身份与世界观:"我是谁、我相信什么" 简历 + 价值观
STYLE.md 写作语气与格式 沟通风格指南
INSTRUCTIONS.md 行为规则:不确定时怎么查、工具怎么用 员工手册
MEMORY.md 跨会话的记忆连续性 工作日志

默认模板的内容可以直接参考源码 packages/core/src/soul/templates.ts,例如默认 Bot 在 SOUL.md 里写道:"诚实优于讨好——我宁可有用了再回应,而不是盲目附和",并明确声明"不会假装记得没有写进 MEMORY.md 的过去会话"。Soul 文件在每轮对话开始时由 compose.ts 拼进主系统提示词。

它们在磁盘上的位置按组织与 Profile 隔离:

~/.nakama/orgs/{orgId}/profiles/{profileId}/

💡 Soul 文件 vs systemPrompt:systemPrompt 适合存放简短的数据库级基础指令;想要更丰富的人格、语气和长期规则,就用 Soul 文件。两者同时存在时,systemPrompt 会作为补充指令追加在 Soul 之后。

4️⃣ 设置工具权限:最小权限原则是核心

工具(Tools)是控制 Agent 风险的第一道闸门——Profile 只能使用被分配给它的工具,不同 Profile 可以有完全不同的权限。这正是团队可以放心共享 Agent 的原因。

新创建的自定义 Profile 默认获得一组"安全基线"工具:

工具 能力
read_file / search_files 读取与搜索 Profile 工作区文件
write_file / edit_file 写入与编辑文件
save_artifact 保存产出物(报告、文档等)到 artifacts/
knowledge_base_search 搜索已上传的知识库文档
web_fetch 抓取网页内容

而 bash(执行 shell 命令)、email(收发邮件)、delete_file、sub_agent(委托子 Agent)等高风险能力默认不分配,需要平台管理员按需开启。分配入口在 Control center → Agent tools → Tools:

Nakama Control center 控制台:Workspace 与 Agent tools 区域,可进入 AI Providers、Tools、Skills、MCP、Plugins 等设置

官方文档给出了几个好用的权限组合模板(见 builtin-tools.mdx):

  • 简单聊天机器人:不加任何额外工具
  • 研究型机器人:web_search + web_fetch + knowledge_base_search
  • 知识库机器人:knowledge_base_search + 文件工具
  • 运维机器人:文件工具 + email
  • 委派型机器人:sub_agent 并行处理多个子任务
  • 编码 Agent:bash + coding-agent 技能

⚠️ 建议遵循最小工具集原则:写作型 Bot 一个工具都不用给,能显著降低误操作风险。工具与 Profile 的绑定关系由 agent-service.ts 在服务端强制执行,内置工具清单定义在 builtin.ts。

5️⃣ 发第一条消息,验证你的 Agent

配置完成后,回到聊天界面,从左侧选择你的 Profile 发送一条测试消息,几秒内应该收到回复:

Nakama 聊天面板:左侧为 Agent 导航与历史会话,右侧选择 Profile 后即可开始对话

如果聊天失败,按 首次设置指南 排查:重新打开 Settings → Agent tools → AI Providers,确认 API Key 和该 Agent 的模型选择是否正确。

验证清单:

  • ✅ Agent 的称呼与语气符合 SOUL.md / STYLE.md 的设定
  • ✅ 分配了 web_search 的 Agent 能真实搜索并给出来源
  • ✅ 未分配 bash 的 Agent 拒绝执行 shell 命令
  • ✅ 对话中的偏好能被写入 MEMORY.md,跨会话记住

6️⃣ 进阶玩法速览

  • 模型选择:每个 Profile 可以在 model 字段单独指定模型,让不同角色用不同"脑子";
  • Skills 技能:可复用的操作手册,分配后 Agent 在相关话题下自动调用,详见 Skills 文档;
  • 知识库:上传 .md、.pdf、.docx 等文档后,knowledge_base_search 即可检索;
  • 渠道接入:把 Agent 接到 Telegram、WhatsApp、Discord、Slack,让全公司从熟悉的 App 里使用它;
  • 共享与克隆:组织间可通过 Profile pack 导出/导入单个 Agent,也可以 Clone agent 快速派生变体(克隆体记忆为空,不会继承源 Agent 的连续性)。

写在最后

用 Nakama 打造 AI Agent 的完整路径只有四步:建 Profile → 写 Soul 文件 → 配工具权限 → 对话验证。Soul 文件解决"它像谁",工具权限解决"它能做什么",而 Profile 把两者装进一个可分享、可克隆、可审计的团队资产里。建议从默认工具集起步,等 Agent 真正跑通业务后,再按需追加高风险能力——这是 Nakama 官方最推荐的使用节奏 🎯

登录后查看全文
nakama