如何用Nakama打造第一个AI Agent:Profile配置、Soul文件与工具权限设置实战
如何用Nakama打造第一个AI Agent:Profile配置、Soul文件与工具权限设置实战
Nakama 是一个面向团队的 AI Agent 工作区(AI workspace),你可以在它的 Web 面板里像用 ChatGPT 一样和 Agent 聊天,而每个 Agent(Profile)都拥有独立的提示词文件、工具权限、技能(Skills)和记忆。本文将带你从零开始,完成 Nakama AI Agent 搭建 的完整流程:创建 Profile、编写 Soul 文件、配置工具权限,最终让你的第一个 AI Agent 跑起来 🚀
1️⃣ 先认识 Nakama 的三个核心概念
在动手之前,先记住三个词,它们构成了 Nakama AI Agent 平台的全部骨架:
| 概念 | 一句话解释 |
|---|---|
| Profile | 一个 Agent 的定义:角色、模型、系统提示词、工具、技能、记忆都挂在它下面 |
| Soul 文件 | 决定 Agent "是谁"的一组 Markdown 文件(身份、语气、行为规则、记忆) |
| Tools | Agent 被允许执行的动作,权限按 Profile 隔离,是最主要的风险控制手段 |
官方文档对这三块有完整说明,建议对照阅读:
- Profiles 文档:Profile 结构与 Soul 文件
- Builtin Tools 文档:内置工具与权限模型
- Agent Prompt 文档:最终系统提示词如何拼装
💡 心智模型很简单:同一个大模型,配上不同的 Profile 和工具,就会变成完全不同的 Agent。写作型机器人可能一个工具都不需要,研究型机器人需要
web_search+web_fetch,运维型机器人则需要文件工具和邮件。
2️⃣ 创建你的第一个 Profile
Nakama 首次安装后会自动为每个组织(Organization)创建两个 Profile:
- Default Bot:组织默认 Agent(
isDefault: true),当你没有指定 Profile 时由它应答; - Super Nakama:超级 Agent(
isSuper: true),可以在聊天里帮你创建新 Profile、审批后执行更高级的操作。
创建新 Agent 有两条路径:
- 面板创建:打开左侧 Agent 页面,点击创建,填写 Agent id、名称并勾选初始工具集,点击 Create agent;
- 让 Super Nakama 代劳:在聊天中直接提出需求,它会在聊天里起草 Soul 文件和工具方案,等你明确说 OK 之后才调用
create_profile真正落库——这是 Nakama 的"确认优先"(confirm-first)设计,避免误操作。
每个 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:
官方文档给出了几个好用的权限组合模板(见 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 发送一条测试消息,几秒内应该收到回复:
如果聊天失败,按 首次设置指南 排查:重新打开 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 官方最推荐的使用节奏 🎯



