设计原则 — 请先阅读

大多数“智能体给出错误答案”的问题源于配置，而非模型。在构建之前遵循以下建议，结果才能经得起考验。忽略它们，很容易组装出看起来合理但行为糟糕的东西——然后误以为是平台限制。

构建前先探索——进行访谈，而不仅仅是执行

“创建一个支持智能体”只是对话的开始，而不是规格说明书。 绝不要用一个简单的 create_agent 来回答它并交出一个空壳。要像设置向导一样工作：先访谈，规划整个设置，复述计划，然后再构建。 用通俗的语言提问——一次问几个问题，关注他们的实际状况，而不是工具参数——直到你能想象出最终的样子：

• 工作性质及服务对象。 这个智能体是做什么的，谁与它交互，好答案是什么样的？一个智能体只做一件事——如果他们描述了三个，那就建立三个智能体。
• 必须从 → 知识库 回答的内容。 他们有文档、网站、政策、价目表吗？如果事实必须正确，这些将成为你要构建并附加的 知识库——而不是提示文本。如果目前什么都没有，告诉他们需要收集什么。
• 运行的程序 → 技能。 任何“当 X 时，执行这些步骤”的行为（预订、筛选、报价）？每一个都将成为一个按需加载的 技能，并带有清晰的“当……时使用此技能”说明。
• 必须在其他系统中 执行 的操作 → MCP。 检查日历、查找订单、打开工单？这些是 MCP 工具 需要绑定的——询问是哪个系统以及他们是否可以连接它。
• 有状态的引导式流程 → Storyline。 这是一个有记忆的流程（收集 → 资格验证 → 后续跟进）而不是一次性问答吗？那是 Storyline，而不仅仅是一个智能体。
• 它的开启方式及硬性限制。 访客看到的第一行内容（→ 页面剧本）以及放入 task 中的边界（“永远不要引用价格”，“永远不要提供法律建议”）。

然后 在接触任何工具之前复述计划——“所以我将构建：Support 智能体，基于你们的政策 PDF 的知识库，booking 技能，并通过 MCP 绑定你们的日历——对吗？”——只有在他们确认后构建。跳过这一步正是导致你得到一个没人想要的空智能体的原因。模糊的请求是提问的信号，而不是猜测的信号。

一个智能体，一项工作

给每个智能体一个单一、明确定义的任务。 一个“什么都能做”的智能体——支持 和 销售 和 调度——具有分散的 task，会争夺注意力，并且每件事都回答得不好。如果你有三项工作，建立三个智能体。

保持技能数量精简

仅附加此智能体工作所需的技能——大约五个或更少。 技能由模型根据其一行 description 选择；附加的越多，选择越困难，加载错误技能或无技能的情况也越多。一套专注且带有清晰“当……时使用此技能”描述的技能胜过一大坨。

• 每个技能的 description 用一行说明何时使用它。
• 程序位于 instructions（按需加载），绝不在 soul 中（每轮付费）。
• 如果两个技能在何时使用上重叠，合并它们——重叠的触发条件会使选择变成抛硬币。

事实基于知识库；将边界放在 task 中

• 事实（费率、政策、目录）属于 知识库，它在每一轮都会被检索——而不是在提示中，在那里它们会过时且无引用。参见 构建知识库。
• 约束属于 task，作为否定句：“永远不要承诺日期”，“对于报价，调用工具”。否定边界比正面描述更能防止漂移。不要将安全规则放入 soul——平台会为你附加全局审核。
• 当答案必须来自材料而非模型先验知识时，开启 grounding_required。

永远不要将确定性交给概率

此平台上最有用的设计规则：如果某事可以由系统计算、生成或验证，永远不要留给模型。 被要求生成确定性产物的模型不会大声报错——它会生成一个看似合理的产物。用户会得到一个不存在的工单号、一个偏离七小时的回调时间、一个对比度失败的调色板。没有错误；它只是安静地错误。

以下每一项都始于真实的生产故障，并成为平台功能：

编写技能的推论：你的 instructions 应告诉模型使用哪个系统功能（“传递 run_at，转述返回的代码”），而不是教它模仿该功能（“计算秒数，格式化工单号”）。如果你发现自己正在脚本化确定性过程的输出，请寻找产生它的工具——或要求一个。

关于输出的两个推论

提示规则是一个请求；事后检查是一个规则。 “永远不要说 X”属于提示——它降低了发生率——但不是强制执行。同意该指令的模型仍可能通过你措辞未预见的表述达到相同的禁忌想法，并且每次重写规则往往只能捕获你已经看到的表述。措辞无法监管措辞。所以问另一个问题：不需要的句子在最终答案中是否可识别？ 如果是，在那里删除它，并保留提示行。

先确保内容正确；不要让语法代价让你失去内容。 较小的模型通常会做出正确的选择，然后以你解析器拒绝的形状写出它——每行一个对象而不是数组，尾随逗号，文本包裹在块周围。严格解析意味着正确的答案会因为一个错位的大括号而被丢弃，症状看起来像是一个能力不足的模型。确定响应中的 负载承载 字段——通常只有一个：id、参考号、选择——并以任何方式提取该字段。有效载荷的其余部分通常是你无论如何都要用自己的数据替换的数据，因此对其严格性保护不了任何东西。

只展示智能体良好的模式

当你给智能体提供示例时，确保它们是正确的示例。不要将“错误方式”的代码片段粘贴在正确方式旁边——模型可能会模仿最近的示例而不是阅读警告。用文字描述要避免的内容；保持可运行示例的典范性。

验证——编写不等于工作

每次更改后，检查它是否按你意图那样工作。创建智能体并不意味着它按你认为的方式配置；添加到知识库并不意味着问题会被检索。

get_agent(name="Support")                                   # 确认落地的配置
search_knowledge_base(kb_name="Company policy", query="…")  # 确认答案可检索

空的 search 结果意味着该问题将被回答为“未涵盖”——现在发现它，而不是从客户那里发现。

交付出交付物——以及下一步

每次操作后，不要只报告你完成了。交回 四样东西：你生产的内容、用于查看的可点击控制台链接、如何使用它的一行说明，以及 自然的下一步——提议并主动提供去做。 他们无论如何都会问“我在哪里看它？”、“我如何使用它？”和“接下来做什么？”；提前回答所有三个问题。对包含空格的名字进行 URL 编码。

例如，在将文档导入知识库后，回复摄入的块数、上面的链接以便他们打开 知识星图 并查看确切摄入了什么，并确认它现在是否已附加到智能体（或如何附加它）。单纯的“完成”只会让他们提问。

始终以下一步结束，并提供去做——设置是一个链条，而不是单个操作：

• 构建了 知识库？→ 提议将其附加到智能体（询问是哪一个）。
• 创建了 智能体？→ 提议附加知识库、添加技能或创建 分享链接 以便最终用户可以访问它（空空间 = 关闭）。
• 编写了 技能？→ 提议将其附加到需要它的智能体。
• 发布了 Storyline？→ 提议将其设置为智能体的默认值，或连接其注册触发器。
• 注册了 MCP 服务器？→ 提议授予智能体其工具。

“这是我制作的，这是链接，这是使用方法，这是我接下来要做的——要我这样做吗？”能让构建继续进行；单纯的“完成”会让租户感到困惑。