创建和优化自定义代理的最佳实践

设计良好的自定义代理消耗的 Notion 积分更少，交付的结果更好。以下是如何充分利用每次运行的方法：

• 将自定义代理用于重复性任务。 对于一次性任务，请改用 Notion 代理——它已包含在你的方案中。自定义代理消耗 Notion 积分，因为它们无论你是否在线，都会在后台自主运行。

• 选择特定的触发器。 针对特定的 @提及或属性更改触发，而不是针对每条消息或数据库更新。减少无效启动，减少浪费的运行。

• 保持上下文紧凑。将你的代理指向所需的特定页面或数据库。这样，它只会读取必需的内容，每次运行都保持专注。

• 预先定义“完成”标准。 明确告诉你的代理完整运行的样子。指令越清晰，它达到结果的速度就越快。

• 批量处理独立任务。 例如，要求你的代理一次读取多个信息源，而不是一次读取一个。

  • ✅ “读取项目数据库和 #support Slack 频道，然后撰写每周更新。”

  • 🚫 “读取项目数据库，然后撰写每周更新。接着读取 #support Slack 频道并将其添加到每周更新中。”

• 当工作流程相似时，从现有的代理开始。 如果你需要的工作流程已作为自定义代理存在，请创建副本，而不是从头开始构建。打开这个代理，选择 ••• 并选择 创建副本。

  • 副本默认是私人。

  • 创建副本后，请重新验证 Slack 等工具，检查触发器是否按预期迁移，并重新部署任何 Worker——它们不包含在拷贝中。这对于快速创建现有代理的团队变体特别有用。了解更多关于 创建自定义代理副本 的信息。

当自定义代理拥有明确的任务、正确的信息源和严谨的“完成”定义时，它们最为可靠。这篇最佳实践文章介绍了如何编写更好的指令、选择正确的触发器以及随着时间的推移改善结果。

如果你不确定从哪里开始，就从团队经常重复的工作入手。当工作流程既可预测又容易评价时，自定义代理会发挥最佳效果。

寻找符合以下条件的工作流程：

• 可重复，例如汇总报告、分类处理传入的请求或回答常见的 Slack 问题

• 频繁，意味着它们每天或每周都会发生

• 易于评估，因此你可以快速判断输出是否正确

确定工作流程后，先构建代理的最简版本。在加入更多复杂功能之前，先确保它能稳定运行。

当流程感觉稳定且可预测时，你可以添加触发器或日程（表）以实现完全自动化。

当你为自定义代理提供清晰的指令时，它会产生更一致且可靠的结果。专注于成功是什么样的，并提供实现它所需的背景信息。

从你想要的结果开始

• 描述最终输出应呈现的样子，而不是列出每一个步骤。

• 让自定义代理决定如何实现目标

• 示例：“创建一个每周状态更新，总结已完成的任务、阻碍因素和后续步骤。”

分享一个真实示例

• 粘贴之前的状态更新、格式化报告或已分类的请求

• 使用具体示例，而非抽象描述

明确格式和目标位置

• 指定输出应发送到的位置（Slack、数据库或现有页面）

• 指出应填写哪些属性或部分

• 示例：“将摘要发布到 #team-updates 并将其添加到每周报告数据库中。”

设置简单的边界

• 明确自定义代理应该做什么以及应该 避免 什么

• 示例：“更新现有的每周报告页面，而不是新建一个，”或“仅在 #support 中回复。”

指出边缘情况

• 说明如果没有数据或没有新内容需要报告时应该怎么做

• 示例：“如果本周没有更新，请发布‘无更新’，而不是跳过。”

保持说明简短且重点突出

• 更简短的说明能产生更一致的结果

• 如果你的设置变得冗长，请将工作流程拆分为多个代理。

在设置自定义代理时，决定工作是否应该按日程（表）运行、响应操作，还是两者兼有。

对可预测的工作使用日程（表）

• 当任务需要按固定节奏运行时，请选择日程（表），无论是否有活动发生

• 非常适合周期性工作，如每周报告、每日简报或每月摘要

使用触发器进行响应式工作

• 当任务需要针对特定事件做出响应时，请选择触发器

• 例如在 Slack 中提交的错误、添加到数据库的新页面或来自特定寄件人的电子邮件

必要时结合使用日程（表）和触发器

• 有些工作流程包含两种模式

• 例如，一个基于触发器的代理可以在 bug 出现时对其进行分类，而另一个定时代理则可以汇总这些已分类 bug 的每周摘要。

从较低频率和有限范围开始

• 先从每周日程（表）开始，而不是每天

• 先从一个频道开始，而不是五个

• 在确认输出结果一致且可靠后，再进行扩展

在全面启用工作流程之前，花点时间测试并调整你的设置。

在激活触发器或日程之前进行测试

• 点击 运行 以手动执行自定义代理

• 检查输出结果以确认其行为符合预期

• 仅在结果看起来正确时才开启触发器或日程（表）

使用小群组进行测试

• 与几位团队成员分享自定义代理以收集反馈

• 利用早期反馈在更广泛地推广之前发现问题

预留迭代空间

• 大多数自定义代理需要多次测试运行才能达到预期效果

• 根据实际输出结果，而不是你原先设想的指令内容，来优化指令。

首先检查活动日志

• 点击时钟图标，查看是什么触发了运行。

• 检查一下代理都做了什么，以及可能出问题的地方。

• 在扩大访问权限之前，使用日志诊断问题并确认自定义代理的行为符合预期

了解常见修复方法

• “输出不正确”通常意味着指令需要更具体一些

• “缺少数据”通常意味着自定义代理需要访问其他页面或数据库

  工具和访问权限

• “运行失败”通常指向权限缺失或指令不明确的问题

设计良好的代理运行速度更快，且能避免不必要的工作。三个因素会影响效率：

• 代理运行的频率，

• 它读取的内容量，以及

• 完成任务所需的步骤数

提高性能最简单的方法是限制不必要的运行。设计触发器，使代理仅在可能采取行动时才运行。

从小处着手，逐步扩展

• 从每周运行开始，而不是每天运行

• 在扩展到更多渠道或工作流之前，先使用一个渠道或工作流

• 一旦结果可靠，再增加频率

使用高信号触发器，以便你的代理仅在需要时运行

• 对于 Slack：触发 @提及或特定表情符号反应，而不是所有消息

• 对于 Notion：在特定属性更改时触发，而不是在每次数据库更新时触发

• 对于 Notion Mail：触发一组过滤后的电子邮件，而不是每条消息

预留一些“无需操作”的运行

• 当代理确定无需执行任何操作时，就会发生这种情况

• 这是正常且高效的——代理仅在退出前检查触发器和指令

代理读取的内容越多，每次运行所需的工作量就越大。请保持范围精简。

• 将代理指向尽可能小的范围。理想情况下是单个页面或几个链接到子页面的页面，代理仅在需要时才加载这些子页面。

• 如果您已经知道代理应该使用哪个数据库或页面作为事实来源，请避免让代理进行广泛搜索。

运行中的每增加一个步骤都会增加工作量，尤其是当自定义代理执行多次搜索时。

• 明确定义完成标准，以便代理能以更少的步骤完成任务。

• 如果代理同时调用多个工具，效率会更高。请尽可能在说明中鼓励并行使用工具。

  • 可以同时运行：“同时读取项目数据库、工程 Slack 频道和最新的冲刺笔记页面。”这三个来源是独立的，因此代理会同时读取所有来源，而不是逐个读取。

  • 必须按顺序运行：“在报告数据库中创建一个摘要页面，然后将链接发布到 Slack 的 #team-updates 中。”代理需要先获得页面 URL 才能发布链接，因此这些步骤必须按顺序执行。

如果代理频繁提出多个后续问题、重试同一操作、重复检查同一页面，或以可预测的方式报错，这说明指令或设置需要改进。

• 如果运行因权限原因（无法在 Slack 中回复，或 URL 不受信任）频繁报错，请在 工具和访问权限 下调整代理的访问权限，或在说明中告知代理避免执行这些操作。