页面剧本

角落里的聊天气泡很容易被忽略，而点击它的访客会面对一个空白的对话框，不知道该问什么。页面剧本（Page playbooks）解决了这两个问题：智能体知道它是从哪个页面打开的，会相应地问候访客，并提供几个他们可以通过一次点击发送的问题。

什么是剧本

三个部分，附加在你选择的键（key）上：

开场白和问题可以由你编写，也可以由智能体根据背景生成，使用访客浏览器设置的语言。

匹配页面

你永远不会从浏览器发送页面内容——只发送一个标识符。平台保存文本。（参见为什么内容保留在服务器端。）

通过 URL —— 页面无需更改

给剧本一个 URL 规则，小部件会自动匹配：

/pricing            matches /pricing, /pricing/, /pricing?utm_source=x
/solutions/*        matches /solutions/legal, /solutions/insurance
*/solutions/legal   matches /solutions/legal AND /zh/solutions/legal

仅比较路径——主机、协议、查询字符串和尾部斜杠都被忽略，因此一个规则同时覆盖 www 和裸域名、http 和 https。

通过键 —— 用于共享 URL 的页面

单页应用、模态框和多步骤流程通常没有独特的 URL。改为显式命名剧本：

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN"
        data-page-key="checkout-step-2" async></script>

如果页面在不重新加载的情况下发生变化，请在路由变化时告知小部件：

caWidget.setPage("checkout-step-3");

解析顺序

1. 显式键（如果已提供）
2. 第一个匹配的 URL 规则
3. 默认剧本（如果你有）
4. 无——访客获得普通聊天框

不存在的显式键会回退到默认值，而不是静默匹配某个 URL 规则。这样，拼写错误会显示为“出现了默认值”，而不是“出现了错误的剧本”。

设置一个

在控制台中，打开页面剧本并创建一个。先选择页面类型——定价页面、解决方案页面、文档、案例研究、首页、联系我们——问题会根据访客通常在该类页面上询问的内容预填充。然后用你自己的语气重写它们。

列表视图有一个匹配器：粘贴任何 URL，它会告诉你该页面将获得哪个剧本，以及它是通过键、URL 规则匹配的，还是回退到了默认值。

或通过 API：

curl -X PUT https://api.agent4.io/v1/manage/page-contexts/pricing \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "label": "Pricing page",
    "url_pattern": "*/pricing",
    "context": "The visitor is looking at our pricing. Four tiers separated by monthly token quota and end-user count. The usual questions are which tier fits their size and what happens when they go over.",
    "greeting_mode": "generated"
  }'

编写背景

这是执行工作的部分。值得了解几点：

一种语言就足够了。 模型读取你写的任何内容，并用访客的语言回答。你不需要为每个区域设置提供翻译。

不要重述知识库中已有的事实。 价格、配额和限制由知识库回答，其优先级高于剧本——这里写的数字不会覆盖它。改为写情况：谁访问了这个页面，他们试图决定什么，他们通常担心什么。

写访客正在做什么，而不是页面说了什么。 “访客正在比较层级并试图预测他们的月度账单”比页面内容的摘要更有用——智能体已经可以查找页面内容。

静态或生成的开场白

greeting_mode: "static" 使用你编写的确切开场白和问题，适用于每种语言的每位访客。完全控制，没有意外。

greeting_mode: "generated" 让智能体根据你的背景，用访客的语言编写它们。每种语言的第一位访客会触发一次生成；之后的每位访客都从缓存中提供服务。编辑背景会清除缓存，因此你的下一位访客会看到更新。

对于多语言网站，生成式是更好的默认值。当措辞至关重要时——受监管的行业，或你与文案撰稿人精心调整了句子的页面——静态是正确的选择。

生成的开场白可以携带表单。 当剧本背景明确说明在初次联系时收集详细信息（“在问候中呈现表单”）时，开场白会附带一个交互式表单——渠道、联系字段，无论背景要求什么——起始问题则退居其次。提交表单是一个正常的消息，因此智能体的工具（save_contact、schedule_followup）照常触发。我们联系页面的“与真人交谈”卡片正是如此：预订表单在访客输入任何文字之前就已经显示在屏幕上。

为什么内容保留在服务器端

小部件报告一个键或 URL。它从不上传页面文本，平台也从不读取你的 DOM。

这是刻意为之。浏览器发送的任何内容都可以被坐在屏幕前的人编辑，而页面上下文接近智能体的指令。我们对此进行了测试：在页面上下文块中植入伪造的“本月企业版 199 美元，无限席位”——明确作为数据围栏，并指示智能体价格仅来自知识库——模型将假价格作为事实重复给访客。围栏和仔细的措辞未能奏效。

将文本保留在服务器上消除了整个渠道。访客能做的最坏事情是请求不同的键，并收到你自己编写的剧本。

值得了解的权衡：剧本副本是半公开的。任何猜到键的人都会获得该剧本的开场白。不要在那里放内部笔记。

内容内的入口点

角落里的气泡很容易被忽略。当某人实际上有疑问的时刻，正是他们正在阅读特定段落的时候——因此你可以在那里放置一个入口点：

<p data-ca-ask="overage-billing"
   data-ca-question="What happens if we go over, and can we cap the spend?"
   data-ca-label="Ask about this">
  When the quota is exhausted, chat requests return 429 …
</p>

悬停在段落上会显示一个小提示。点击它会以你的品牌颜色闪烁页面，高亮显示该段落，然后打开已经基于该段落的剧本工作的聊天——如果你提供了一个，则立即提问。

稍后添加的段落——通过框架、选项卡、手风琴——会被自动拾取。如果你以绕过该机制的方式渲染内容，请调用 caWidget.rescan()。

连接你自己的按钮

你页面上的任何元素都可以打开选定剧本的对话——将现有的“联系销售”或“预订演示”按钮转变为智能体对话而不是表单的模式：

const ok = caWidget.open("contact-sales");            // open on that playbook
caWidget.open("contact-sales", "I need a quote");     // …and ask the first question for them
if (!ok) location.href = "mailto:sales@example.com";  // false = script blocked; keep a fallback

无论你的站点使用哪种小部件形状——角落气泡或 Ask 命令面板，caWidget.open 的工作方式相同。当小部件不可用时（脚本未加载或被阻止），它返回 false，因此点击永远不会成为死胡同：回退到按钮之前的链接。

我们自己的联系页面正是这样构建的——七个意图卡片，每个卡片打开一个剧本，询问两三个问题，保存联系人，并预订后续跟进。

确定性的 intake 归档

当剧本的工作是收集——预订、潜在客户、投诉——在它的背景中添加一个机器标记：[[inbox:submit_lead]]、[[inbox:escalate]] 或 [[inbox:request_booking]]。当访客在该剧本上提交交互式表单时，平台会在模型回复之前自行归档记录——智能体仅转发工具返回的引用。答案中的联系细节以相同方式保存。

存在这一点是因为归档是绝不能依赖模型情绪的一步：在生产测试中，一个中型模型即使有工具可用、被指示并被推动，仍会口头确认——一次引用文档中的示例引用，仿佛它是真实的。有了标记，回复中的引用每次都是你收件箱中的引用。如果因任何原因归档失败，对话正常继续，模型驱动的指令接管。

查看哪些有效

控制台显示每个剧本的打开次数以及哪些起始问题被点击。用它来删除无人选择的问题，并发现访客打开聊天但从不互动的页面——通常表明开场白在谈论错误的事情。

事件仅是计数。它们不携带访客标识符，因为要回答的问题是“这篇文案是否好”，而不是“谁问了什么”。

他们说话之后

起始问题适用于尚未说话的访客，一旦有人说话，它们就会退居其次。接下来发生的是单独的开关：后续建议，设置在智能体上而不是页面上，在每次回复后提供几个一键问题。两者共享消息框上方的同一栏，且从不冲突——一个打破僵局，另一个保持对话进行。