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

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

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

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

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

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

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

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

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

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

  • 副本默认是私人。

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

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

如果你不确定从哪里开始，请从团队经常重复的工作入手。当工作流程可预测且易于审查时，自定义代理最为有效。

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

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

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

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

选择工作流程后，请先构建你的自定义代理的最简版本。在增加复杂性之前，先确保它运行稳定。

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

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

从你想要的结果开始

• 描述最终输出应该是什么样子，而不是列出每一个步骤

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

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

分享一个真实示例

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

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

明确格式和目标位置

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

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

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

设置简单的边界

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

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

指出边缘情况

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

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

保持说明简短且重点突出

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

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

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

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

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

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

使用触发器处理响应式工作

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

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

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

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

• 例如，一个基于触发器的自定义代理可以在错误出现时进行分类，而另一个独立的定时自定义代理则负责汇总这些已分类错误的每周摘要

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

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

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

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

在完全激活工作流之前，请花时间测试并调整你的设置。

在激活触发器或日程（表）前进行测试

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

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

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

使用小规模群组进行测试

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

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

预留迭代空间

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

• 根据实际输出结果而非你预期的指令意图来优化指令

首先检查活动日志

• 点击时钟图标以查看触发运行的原因

• 查看自定义代理执行的操作及其可能失败的位置

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

了解常见修复方法

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

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

  工具和访问权限

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

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

• 代理运行的频率，

• 它读取的内容量，以及

• 完成任务所需的步骤数

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

从小处着手，逐步扩展

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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