创建自定义智能体

自定义智能体是你自己编写的帮手：它的指令、什么时候运行、允许改动什么，都由你决定。没有哪个可下载智能体能满足需求时，就自己做一个。如果某个已安装的智能体已经很接近，在 Agents(智能体) 面板里把鼠标移到它的卡片上，点击 Copy agent(复制智能体)，就能得到一份可编辑的副本。

开始之前：先读智能体：聊天里的 AI 帮手。做好一个智能体并不会让它运行，之后还要把它加进聊天。自定义智能体在所有聊天模式下都能用。

新建一个自定义智能体

  1. 打开 Agents 面板。
  2. 点击顶部附近的 New(新建)（加号图标）。整页的智能体编辑器会打开。
  3. 在标题输入框里填写名称，例如 Weather Reporter。
  4. 填好 Description(描述) 和 Author(作者)。
  5. 选择一个 Pipeline Phase(流程阶段)（见 Pipeline Phase）。
  6. 在 Custom Agent Abilities(自定义智能体能力) 下开启它需要的能力。
  7. 挑一个与智能体产出相符的 Result Type(结果类型)。拿不准的话，选 Context Injection(上下文注入)。它不需要任何能力，也没有严格的输出格式。
  8. 在 Prompt Template(提示词模板) 下写它的指令。
  9. 点击顶栏的 Save(保存)。会出现一个绿色的 Saved 角标。

智能体现在会出现在 Agents 面板的 Custom Agents(自定义智能体) 区域。要使用它，打开一个聊天，进入 Chat Settings(聊天设置)，开启 Enable Agents(启用智能体)，再从 Custom Agents 里添加这个智能体。

Pipeline Phase

Pipeline Phase 决定智能体在什么时候运行。

有些结果类型会强制指定阶段。Text Rewrite(文本改写) 会切到 Post-Processing。Prompt Patch(提示词补丁) 和 Character Activity(角色活动) 会切到 Pre-Generation。

Post-Processing 智能体还会多出一个 Turn Data Access(回合数据访问) 区域，里面有两个开关：Pre-generation injections(生成前注入) 和 Parallel agent results(并行智能体结果)。打开它们，智能体就能读到同一回合内其他智能体的产出。

Custom Agent Abilities

能力需要你主动开启。每项能力在你打开它的开关之前都用不了。

如果开启了 Edit lorebooks，会出现 Lorebook Writer(世界书写入) 区域。打开 Allow lorebook entry writes(允许写入世界书条目)，再在 Target lorebook(目标世界书) 里选一本世界书。智能体只能写入这一本。

Result Type

Result Type 告诉 Marinara 该怎么读取智能体的回答。多数类型要求 JSON，这是一种用花括号和引号书写的文本格式。在你开启某个类型所需的能力之前，它会一直显示为灰色。

不需要能力的类型：

需要 Edit messages 的类型：

需要 Edit trackers 的类型：

其他类型各自需要一项对应的能力：

图像智能体在聊天中的控制项

拥有 Image generation 能力的智能体会在 Chat Settings → Agents → Custom Agents(聊天设置 → 智能体 → 自定义智能体) 里多出两个控制项。

Activation Keywords

默认情况下，智能体按它正常的节奏（也就是多久运行一次）运行。Activation Keywords(激活关键词) 会在场景不相关时跳过智能体，省下 Token。

  1. 在 Activation Keywords 里每行填一个关键词或短语，例如 tavern 或 secret door。
  2. 把 Scan Depth(扫描深度) 设为要搜索的最近消息条数。默认是 5，最大是 200。

之后只有当这些消息里出现某个关键词时，智能体才会运行。框留空就关闭这个筛选。频率和激活问题仍然适用。

挂载工具

智能体可以调用工具：工具是 AI 能执行的函数，用来获取或改动某样东西，再把结果读回来。这也叫函数调用。

  1. 在智能体编辑器里打开 Tools / Function Calling(工具/函数调用)，逐个开启想用的工具。列表里既有内置工具，也有你自己的工具。要自己做一个，见自定义工具。
  2. 在 Chat Settings 里打开 Function Calling(函数调用)，开启 Enable Tool Use(启用工具调用)。少了这一项，智能体的工具一直不生效。

导入的智能体永远不会获得工具权限。先检查导入的智能体，再自己为它选好工具。

智能体每次运行最多进行 16 轮工具调用（服务器的 MAX_TOOL_ROUNDS 更低时则更少），之后就用手头已有的结果作答。一次只调用一个工具的模型，每次调用都要用掉一轮，所以要保存很多条目的智能体，应该在一次回复里发起多个调用。世界书回填每次运行最多可用 64 轮。

命名提示词选项

一个智能体可以带好几套提示词变体，这样每个聊天都能挑一套，而不必改动智能体。

  1. 在 Prompt Template 下找到 Named prompt options(命名提示词选项)。
  2. 点击 Add option(添加选项)。
  3. 给它起个名字，写一句简短说明，再写完整的提示词。

有人把这个智能体加进聊天时，会看到一个 Prompt Mode(提示词模式) 下拉菜单，列出你的选项。一个选项都没有时，只显示默认提示词。

其他设置

{{user}}、{{char}} 这类宏在 Prompt Template 里同样有效。见宏。

完整实例

这个智能体会把每条回复改写成英式英语。

  1. 命名为 British English Editor。
  2. 在 Custom Agent Abilities 下开启 Edit messages。
  3. 在 Result Type 下选 Text Rewrite。阶段会切换到 Post-Processing。
  4. 把下面这段粘贴进 Prompt Template：
   You are a copy editor. Rewrite the latest reply into British English.
   Change spelling and vocabulary only. Do not change the meaning, tone, or events.
   Return JSON with an "editedText" field holding the full rewritten reply,
   and a "changes" array of short notes describing what you changed.
  1. 点击 Save。
  2. 打开一个 Roleplay 聊天，在 Chat Settings 里开启 Enable Agents，再从 Custom Agents 添加这个智能体。

每条回复之后，智能体会返回这样的 JSON：

{"editedText":"The colour of the harbour caught her eye.","changes":[{"description":"color to colour, harbor to harbour"}]}

Marinara 把 editedText 换进回复里。changes 里的说明会显示为一小段摘要。

导入和导出智能体

要导出一个智能体，点击编辑器顶栏的 Export agent(导出智能体)（上传图标）。文件里包含智能体的提示词和设置，但永远不包含自定义工具的定义。要导出多个，在 Agents 面板里用 Select agents(选择智能体)，选好后导出。

外部导入默认是锁住的。

  1. 打开 Settings → Advanced → Danger Zone(设置 → 高级 → 危险区域)，开启 Allow custom Agent imports(允许导入自定义智能体)。不需要改 .env。
  2. 在 Agents 面板里点击 Import agents(导入智能体)，选择智能体文件或文件夹。
  3. 检查 Marinara 列出的权限清单。只批准这个智能体确实需要的权限。没勾选的能力保持禁用。

这个锁只影响来自文件、文件夹或自定义仓库的智能体。你自己创建的智能体，以及从 Agent Organizer(智能体管理器) 安装的官方智能体，照常可用。每个导入的文件都会得到一个新的自定义身份，所以它无法顶替官方智能体。

出于安全考虑，Marinara 会忽略附带的函数，清空工具选择，清理临时 CSS，并在导入的智能体改动消息、追踪器、世界书、背景、立绘、媒体、触觉设备、About Me 数据、提示词或图像之前，先核对已批准的能力。可信的函数要单独导入，检查之后再自己挂载到智能体上。把 Danger Zone 开关关掉，导入的智能体就会停止运行。

激活问题

激活问题会询问最近的场景是否需要你的智能体。它能识别关键词漏掉的改述。它需要一个 Decision model(判定模型)，也就是回答是非问题的小模型。在 Connections(连接) 面板里选一个，见 Decision 模型。Decision model 设为默认的 None(无) 时，问题字段保持禁用，带问题的智能体会像没有问题一样运行。

  1. 打开这个自定义智能体。
  2. 输入最多 500 个字符的 Question(问题)。其中可以使用 {{user}} 和 {{char}} 宏。
  3. 把 Run when probability is at least(运行所需的最低概率) 设为这个智能体的阈值。“是”的概率达到这个值时智能体才运行，所以值越高，跳过的次数越多。编辑器会为你的模型给出推荐值：本地聊天模型和 Decision 账号为 0.5，内置 Open-Jev 模型为 0.1。切换模型之后，用自己的聊天核对一下。见阈值。
  4. 可选：设置 Bypass the question after this many messages without a successful run(连续指定消息数未成功运行后跳过问题)。经过这么多条消息后，问题就会被跳过，这样一个一直回答“否”的模型就无法让智能体永远沉默。关键词和频率仍然适用。

把问题写成关于最新消息的陈述，例如 The latest message moves the scene to a new place.，小模型回答它比回答 Did the scene change? 更可靠。见编写陈述。

运行方式：

激活问题只适用于自定义智能体。

智能体提示词中的判定陈述

激活问题决定智能体是否运行。Prompt Template 里的判定陈述决定运行中的智能体会收到什么指示。语法见条件提示词：

{{#if decision:"In the latest message, the characters move to a different location"}}
Update the location field.
{{else}}
Leave the location as it is.
{{/if}}

用它们可以在平静的回合发送更小的提示词。追踪器可以只在地点改变时更新地点。图像智能体可以只在场景改变时描述新图片。音乐智能体可以只在氛围转变时换曲。要从几组指示里挑一组，使用 {{#if decision_choice:"The kind of scene in the latest message" == "combat"}}，然后是 {{else if decision_choice:"The kind of scene in the latest message" == "dialogue"}}，依此类推。见条件提示词。

从 Marinara-Agents 安装的智能体也以同样的方式渲染提示词。

相关指南