配置智能体
智能体创建完成后，可在详情页的 编辑 标签页中进行全面配置。配置界面采用左右分栏布局：左侧为配置编辑区，右侧为对话预览区，支持实时调试。
本文详细介绍每一项配置选项的含义和使用方法。
配置界面概览
进入智能体详情页后，顶部标签栏提供主要视图：
| 标签 | 功能 |
|---|---|
| 编辑 | 配置智能体的全部参数，左右分栏实时预览 |
| 分析 | 查看活跃用户、对话量、消息趋势等统计数据 |
配置修改后，点击右上角 发布 按钮保存。保存成功后会显示绿色勾号标识。
基本信息
基本信息卡片包含智能体的身份标识配置。
| 配置项 | 说明 |
|---|---|
| 头像 | 点击头像区域可打开资源选择器，从资源库选择或上传图片。未设置头像时，显示名称首字母的渐变色圆形头像。 |
| 名称 | 智能体的显示名称。将展示在列表卡片、对话界面标题等位置。 |
| 描述 | 对智能体功能的概括性描述。展示在列表卡片和对话欢迎区域。 |
执行应用
执行应用用于指定智能体的实际推理引擎运行在哪个 Agent Client 实例上。
在 Snail AI 的 Server-Agent 分布式架构 中，Server 端负责请求编排和路由，Agent Client 负责实际的模型调用和工具执行。通过选择不同的执行应用，可以实现：
- 资源隔离：将不同业务线的智能体路由到不同的 Client 实例
- 灵活部署：本地工具（如数据库查询、文件处理）在 Client 所在网络内执行，数据不出域
- 负载分配：将高流量智能体路由到专用的高性能 Client
配置方式：
从下拉列表中选择已注册的应用（格式：应用名称 (AppID)）。如不选择，系统将使用默认路由策略。
对话模型
在配置信息的 CHAT 模型 折叠项中，选择该智能体使用的大语言模型。
下拉列表展示所有已配置的 CHAT 类型模型，格式为 提供商 / 模型名称。
TIP
对话模型的配置和管理请参考 模型管理 文档。当前源码已落地的模型调用规格以 OpenAI-compatible Chat、OpenAI-compatible Embedding 和 Qwen/HTTP Rerank 为主；其他服务如提供兼容接口，可按兼容端点验证接入。
需要在对话预览中上传图片时，请选择已在模型配置中开启“支持图片输入”的 CHAT 模型。该开关对应 configJson.capabilities 中的 vision 能力，未开启时图片消息会被服务端拒绝。
绑定 RAG 知识库
开启知识库开关后，智能体将具备基于文档的检索增强生成（RAG）能力。
配置步骤
- 在"知识库"行，将开关切换为开启状态
- 在出现的下拉列表中选择目标知识库（格式：
知识库名称 (#ID)） - 每个智能体当前支持绑定 一个 知识库
工作原理
当用户提问时，系统会：
- 将用户问题进行向量化
- 在绑定的知识库中执行混合检索（向量 + BM25 + 融合 + 重排）
- 将检索到的相关文档片段注入上下文
- 由大模型基于上下文生成回答
前置条件
使用 RAG 功能前，需要先在 RAG 知识库 模块中创建知识库并完成文档上传和索引构建。
绑定 MCP 服务
MCP（Model Context Protocol）服务为智能体提供外部工具调用能力。一个智能体可以绑定 多个 MCP 服务器。
配置步骤
- 在"MCP 工具"折叠项中，点击右上角 添加 按钮
- 在弹出的选择弹窗中，勾选需要绑定的 MCP 服务器
- 每个服务器条目展示：名称、连接状态（已连接/未连接）、连接地址和描述
- 点击 确认 完成选择
已绑定服务管理
绑定完成后，所选服务以列表形式展示在折叠项中，每个条目包含：
- 服务名称和连接状态标签
- 连接地址（自动拼接 baseUri 和 endpoint）
- 移除按钮（点击可取消绑定）
工作原理
当大模型判断需要调用外部工具时，会通过 MCP 协议向绑定的服务器发送工具调用请求。Snail AI 支持三种 MCP 传输协议：
- SSE（Server-Sent Events）
- Streamable HTTP
- Stdio（标准输入输出）
TIP
MCP 服务器的配置和管理请参考 MCP 工具 文档。
绑定 Skill 技能
Skill 技能是预定义的结构化处理能力，与 MCP 工具类似但更轻量。一个智能体可以绑定 多个 技能。
配置步骤
- 在"SKILL"折叠项中，点击右上角 添加 按钮
- 在弹出的选择弹窗中，勾选需要绑定的技能
- 每个技能条目展示：名称、描述和关联的文件名
- 点击 确认 完成选择
已绑定技能管理
与 MCP 服务类似，已绑定的技能以列表形式展示，支持单独移除。
TIP
当选中的技能列表为空时，Skill 功能将自动禁用；绑定至少一个技能后自动启用。
配置记忆
记忆功能使智能体具备对话上下文的延续能力。Snail AI 提供两种记忆机制：
短期记忆（滑动窗口）
短期记忆通过保留最近 N 条对话消息来维持上下文连贯性。
| 配置项 | 默认值 | 范围 | 说明 |
|---|---|---|---|
| 滑动窗口大小 | 20 条 | 1 ~ 100 | 保留最近多少条消息作为上下文发送给模型 |
TIP
窗口大小影响 Token 消耗。对于大多数场景，20 条已足够。如果智能体需要频繁引用较早的对话内容，可适当增大；如果追求响应速度和成本控制，可适当减小。
长期记忆（向量召回）
开启记忆开关后，可从下拉列表选择一个记忆配置。长期记忆会将对话中的关键信息向量化存储，在后续对话中通过语义检索召回相关记忆。
配置步骤：
- 将"记忆"行的开关切换为开启
- 在出现的下拉列表中选择记忆配置（格式：
配置名称 (#ID)） - 设置短期记忆滑动窗口大小
前置条件
使用长期记忆功能前，需要先在 记忆管理 模块中创建记忆配置。
联网搜索
在"知识库"折叠区域中，联网搜索 开关控制智能体是否可以实时检索互联网信息。
- 开启（默认）：智能体可在必要时搜索网络获取最新信息
- 关闭：智能体仅基于已有知识和绑定的知识库回答
TIP
对于内部知识问答、保密场景，建议关闭联网搜索，确保回答完全基于私域知识库。
系统提示词
系统提示词（System Prompt / Instruction）是智能体行为定义的核心。它告诉大模型"你是谁、能做什么、应该怎么回答"。
编辑方式：
在"系统提示词"卡片中，使用多行文本框编辑。支持 Markdown 格式，建议使用结构化的提示词模板：
## 角色
[定义角色身份]
## 能力
[列出核心能力]
## 限制
[说明行为边界]
## 输出格式
[指定回答格式要求]文本框支持自动高度调整（12 ~ 24 行），适应不同长度的提示词。
问候语
问候语（Greeting）是用户进入对话界面时看到的第一条消息。一段好的问候语应该：
- 简要说明智能体的功能
- 引导用户如何开始对话
- 语气友好、专业
示例：
你好！我是企业财报解读专家。你可以向我提供任意上市公司的财报数据，我将帮你分析关键财务指标、识别风险和增长点。请问你想分析哪家公司的财报？
预设问题
预设问题（Preset Questions）展示在对话界面的欢迎区域，帮助用户快速理解智能体能做什么，并一键开始对话。
管理方式：
- 添加：在输入框中输入问题文本，点击 添加 按钮
- 编辑：直接修改已有问题的文本内容
- 删除：点击问题右侧的删除按钮
- 建议设置 3 ~ 5 个有代表性的问题
示例：
- "分析腾讯 2024 年 Q3 财报的营收变化趋势"
- "对比阿里巴巴和京东的毛利率走势"
- "帮我解读最新发布的年报中的风险提示"
精选推荐
在配置信息底部的"精选推荐"折叠项中，可以将智能体标记为企业精选。
标记为精选的智能体将在列表页的"企业精选"区域优先展示，适合推荐给全组织使用的优质智能体。
配置保存
所有配置修改后，点击页面右上角的 发布 按钮保存。保存 API 会将以下全部字段一次性提交到后端：
- 基本信息（名称、描述、头像）
- 系统提示词、问候语、预设问题
- 对话模型
- MCP 服务绑定列表
- Skill 技能绑定列表
- RAG 知识库绑定
- 记忆配置
- 联网搜索开关
- 执行应用
- 精选推荐标记
保存成功后，右上角显示绿色勾号和"已保存"状态提示。