角色、主题和提示词

智能体带有合理的默认值，但您可能需要调整声音和外观。 角色设定塑造它如何回答；主题塑造它的外观； 开场白提示塑造访客首先问什么。

角色设定和语气

角色设定 JSON 对象很小但很重要：

{
    "name": "Aria",
    "tone": "friendly and concise"
}

name 是助手的第一人称称呼（模型使用"我是 Aria…"）。 tone 直接附加到系统提示词中，因此像"温暖但专业"或 "俏皮，从不企业化"这样的短语会完整保留。

系统提示词

内置提示词已经涵盖安全性、RAG 基础、引用格式化和提示词注入防御。 您的 system_prompt 字段附加在内置之后——用于以下内容：

• 品牌词汇（"称我们的产品为'互客鱼'"）。
• 转化行为（"当访客询问价格时，提供预订电话"）。
• 领域提示（"如果询问退货，始终提及 30 天窗口"）。

护栏

guardrails blob 目前支持：

开场白提示

最多六个 chips 在访客首次打开小部件时出现在输入框上方。它们在 第一轮后消失。将它们保持在 80 个字符以下，并面向转化 （"Pro 多少钱？"、"您提供免费试用吗？"、"我可以和人工对话吗？"）。

主题

主题 blob 控制小部件的外观：

{
    "primary": "#111827",
    "accent": "#10b981",
    "radius": 12,
    "position": "bottom-right",
    "launcher_label": "Need help?"
}

• primary ——启动器按钮背景和 outgoing 消息气泡。
• accent ——链接颜色、焦点环、引用 chips。
• radius ——启动器和面板的圆角半径（像素）。
• position ——小部件固定自己的位置。 bottom-center（默认——omnibar pill）， bottom-right（Intercom / Drift / Tawk 风格的 角落浮动气泡），或 bottom-left （镜像，当页面右边缘有其他小部件时有用）。 从自定义页面上的单选组中选择；保存到 theme.position，小部件在 init 时读取它。
• launcher_label ——关闭的启动器 pill 上的文本。空字符串 = 仅圆形启动器。

自定义 页面（/app/agents/{id}/customize） 有实时预览，因此您可以在发布前查看更改。

聊天前潜在客户捕获

自定义页面上的 聊天前潜在客户捕获 开关（列 require_lead_before_chat）将聊天界面置于姓名 + 邮箱表单之后。 访客看到表单而不是 omnibar；提交后，聊天面板在同一挂载上解锁，无需重新加载。

• 为什么使用它。更高的捕获率。访客在获得答案之前仍有动力 识别自己——与 Intercom 和 Drift 使用了十年的模式相同。
• 为什么关闭它。摩擦。对于文档网站或公共营销页面， 目标是快速回答，电子邮件门比帮助捕获更损害参与度。
• 持久化。一旦访客捕获，刷新时门不会返回。 /widget/init 检查对话上是否存在现有 Lead 并相应地种子 state.leadCaptured。
• 捕获端点。不变——POST /v1/widget/leads 与内联对话中表单使用的相同。门只是更早调用它。

自定义潜在客户表单字段

默认情况下，潜在客户表单要求姓名 + 邮箱。自定义页面上的 潜在客户表单字段 卡片（列 lead_form_fields） 允许您用任何您想要的字段列表替换它——当不同智能体需要不同的资格问题时很有用。

v1 中支持的字段类型：

• text、email、tel、textarea ——单行/多行文本输入。
• select ——带有 options 列表的下拉菜单。
• checkbox ——通常是"同意"切换。

每个字段都有一个稳定的 key（小写/下划线）、面向访客的 label、可选的 required 标志、可选的 placeholder，以及文本类型字段的可选 maxlength。

保留键。 email、name 和 phone 是保留的——当小部件提交表单时，这些值直接落在匹配的 Lead 列上，因此 email / name / phone 上的现有分析查询继续工作。其他所有内容都落在 Lead 的 fields JSON 列上。

向后兼容性。如果 lead_form_fields 为 null （现有智能体的默认值），小部件回退到传统的姓名 + 邮箱形状—— 无需迁移现有数据，不会中断进行中的对话。

相同的模式在两个挂载点渲染。小部件的对话中潜在客户表单 （当 LLM 提出 lead_prompt 时）和聊天前门（当 require_lead_before_chat 开启时）都使用相同的字段列表， 因此构建 5 字段表单的买家无论表单如何打开都会看到完全相同的形状。

预设。构建器附带四个起点：经典（姓名 + 邮箱）、 B2B SaaS（姓名 + 工作邮箱 + 公司 + 团队规模）、 支持（邮箱 + 订单 ID + 问题类别）、 GDPR 友好（邮箱 + 同意复选框）。 "重置为默认"删除自定义并回到 null / 姓名 + 邮箱。

限制：每个智能体最多 12 个字段，每个字段的标签最多 120 个字符， 每个 select 最多 24 个选项，每个 text/textarea 最多 4000 个字符。

语言

language_default 固定智能体的回复语言。它接受从 lang/*.json 自动发现的任何区域设置——互客鱼开箱即用 132 种 （en/es/fr/tr 完全翻译，其余有 UI 界面翻译，未涵盖的内容回退到英语）。 当此字段为空时，智能体跟随访客的浏览器 Accept-Language 头， 当没有候选匹配时回退到英语。

系统提示词指示模型根据需要翻译检索到的来源，但保持数字、价格、 产品名称和专有名词不变。RTL 区域设置（阿拉伯语、希伯来语、波斯语、 乌尔都语、普什图语、信德语、迪维希语、意第绪语、维吾尔语）在 LocaleCatalog 中标记，小部件自动镜像其布局。

置信度阈值

一个 0–1 的数字，控制"我不知道"行为。详见 智能体获取调整建议——但简短版本是： Cloudflare bge-base 降低，OpenAI 嵌入提高，并在每次更改后观察分析缺口报告。