structure｜1️⃣ 三级笔记、思想框架

🧭 文章主旨

Notion 官方总结的 Custom Agent 最佳实践：一个可靠的 Agent = 明确的目标 + 最小化的上下文 + 清晰的完成定义 + 持续的迭代调试。核心思想是——先做减法，再做加法。

一、Custom Agent 的基本使用原则

• 用 Custom Agent 做重复性工作——一次性任务用 Notion Agent 就够了，Custom Agent 是为后台自主运行设计的
• 选择精确的触发器——触发特定 @mention 或属性变更，而非所有消息或数据库更新；fewer false starts, fewer wasted runs
• 保持上下文紧凑——只指向 agent 真正需要的页面或数据库，每次运行保持聚焦
• 提前定义「完成」——告诉 agent 一次完整运行的结果是什么样；指令越清晰，到达结果越快
• 批量处理独立任务——让 agent 同时读多个来源，而非逐个串行
  • ✅ "Read the Projects database and the #support Slack channel, then write the weekly update."
  • 🚫 "Read the Projects database, then write the weekly update. Then read the #support Slack channel and add to the weekly update."
• 模型设为 Auto——让 Notion 自动选择最适合的模型，平衡质量和 credit 消耗

二、选择可重复的工作流

• 从团队频繁重复的工作开始，寻找三个特征：
  • Repeatable：编译报告、分拣请求、回答常见 Slack 问题
  • Frequent：每天或每周发生
  • Easy to evaluate：能快速判断产出是否正确
• 先建最简版本，跑通后再加复杂度
• 流程稳定且可预测后，再加 triggers 或 schedules 实现全自动

三、写清晰、目标导向的指令

• 从期望的结果开始——描述最终产出的样子，而非列出每个步骤；让 agent 自己决定怎么到达终点
• 给一个真实案例——粘贴之前的状态更新、格式化报告，用具体例子替代抽象描述
• 明确格式和目的地——产出发到哪里（Slack、数据库、现有页面），哪些属性或 section 需要填写
• 设简单边界——明确 agent 该做什么、不该做什么
  • 例："Update the existing weekly report page, not a new one"
• 标注边缘情况——没有数据或没有更新时应该怎么处理
  • 例："If there are no updates this week, post 'No updates' instead of skipping."
• 保持指令短而聚焦——越短的指令产出越一致；如果指令太长，拆成多个 agent

四、决定运行方式：Triggers vs. Schedules

• Schedules 用于可预测的工作——周报、日报、月度总结，不依赖特定事件，按固定节奏运行
• Triggers 用于响应式工作——Bug 报告、新页面创建、特定发件人的邮件，有事件发生才运行
• 两者可以组合——例：一个 trigger agent 实时分拣 bug + 一个 scheduled agent 编译周度 bug 汇总
• 从低频和小范围开始——先周运行再日运行，先一个频道再五个频道；确认产出稳定可靠后再扩大规模

五、测试与排错

• 先手动测试，再激活 triggers/schedules——用 Run 按钮手动执行，确认行为符合预期
• 小范围测试——先分享给几个队友收集反馈，再大范围推广
• Expect iteration——大多数 agent 需要多次测试才能跑对；根据实际产出而非意图来调整指令
• 先看 activity log——点时钟图标查看触发原因和执行过程；用日志诊断问题，确认行为正确后再扩大使用范围
• 常见修复方向
  • "Incorrect output" → 指令需要更多 specificity
  • "Missing data" → agent 需要访问更多页面/数据库（在 Tools and access 中设置）
  • "Failed runs" → 通常是权限缺口或指令不清晰

六、提升可靠性与性能

三个影响效率的因素：运行频率 × 读取内容量 × 完成任务的步骤数

• 1. 减少运行频率
  • 从低频开始，逐步提升
  • 使用高信号触发器——Slack 用 @mention 或 emoji reaction，Notion 用特定属性变更，Mail 用过滤后的邮件子集
  • "No action needed" 的运行是正常的——agent 检查后发现无事可做就退出，这很高效
• 2. 精确控制 agent 读取的内容
  • 指向尽可能小的范围——理想情况是单个页面或几个链接到子页面的页面
  • 如果你已经知道 source of truth 在哪，就不要让 agent 做广泛搜索
• 3. 保持步骤数低
  • 明确 definition of done，让 agent 用更少步骤完成
  • 鼓励并行工具调用——独立的数据源同时读取，而非逐个串行
• 4. 警惕循环和重试
  • 如果 agent 频繁追问、重试相同操作、反复检查相同页面或以可预测方式报错——说明指令或设置需要改进
  • 权限问题导致的运行失败 → 调整 Tools and access 或在指令中告诉 agent 避开那些操作

concepts｜2️⃣ 关键概念、概念网络

一、核心概念解析 (Core Concepts)

• 【Custom Agent】

  • context：

    Custom Agents run on Notion credits because they work autonomously in the background, whether you're online or not.

  • 费曼一下：Notion 平台上的自定义 AI 助手，与内置的 Notion Agent 不同，Custom Agent 能在后台自主运行、响应触发器、按时间表执行任务，是为重复性自动化工作设计的。消耗 credits 而非免费。

• 【Definition of Done】

  • context：

    Define “done” upfront. Tell your agent exactly what a complete run looks like. The cleaner the instructions, the faster it gets to the result.

  • 费曼一下：在给 agent 写指令时，明确告诉它「一次完整运行的结果是什么样」。这个概念借自敏捷开发，在 agent 语境下意味着：不要只列步骤，要描述最终产出的样子。指令越清晰，agent 越快完成，消耗越少。

• 【Trigger（触发器）】

  • context：

    Choose a trigger when the task should run in response to something happening. Examples include a bug filed in Slack, a new page added to a database, or an email from a specific sender.

  • 费曼一下：事件驱动的运行机制——某件事发生时自动启动 agent。关键是选择「高信号触发器」（high-signal triggers）：触发特定 @mention 或特定属性变更，而非所有消息或每次数据库更新。触发越精准，无效运行越少。

• 【Schedule（定时任务）】

  • context：

    Choose a schedule when the task should run at a set cadence, regardless of activity. Ideal for recurring work like weekly reports, daily briefs, or monthly summaries.

  • 费曼一下：时间驱动的运行机制——不管有没有事件发生，按固定节奏执行。适合周报、日报等可预测的重复性工作。与 trigger 可以组合使用。

• 【Context Scope（上下文范围）】

  • context：

    Point the agent to the smallest possible scope. Ideally a single page or a few pages that link to sub-pages the agent can load only if needed. Avoid asking the agent to search broadly if you already know which database or page it should use as the source of truth.

  • 费曼一下：agent 每次运行时能读取的内容范围。文章的核心主张是「越小越好」：指向尽可能小的范围，让 agent 只读它必须读的内容。范围越紧，每次运行越聚焦、越快、越省 credit。

• 【Parallel Tool Use（并行工具调用）】

  • context：

    It’s more efficient if the agent calls multiple tools at the same time. Encourage parallel tool use in your instructions when possible.

  • 费曼一下：让 agent 同时执行多个独立操作，而非逐个串行。比如同时读取三个不相关的数据源，而非先读第一个再读第二个。但有依赖关系的步骤必须串行（如先创建页面再发链接）。这是减少步骤数、提升效率的关键策略。

• 【Activity Log（活动日志）】
• 【High-Signal Trigger（高信号触发器）】

二、概念网络 (Concept Network)

• Custom Agent 是整篇文章的主体，所有其他概念都围绕它展开
• Definition of Done → 直接决定 agent 的指令质量，是写好指令的核心前提
• Trigger 与 Schedule 是 Custom Agent 的两种运行机制，互补关系：事件驱动 vs. 时间驱动
• High-Signal Trigger 是 Trigger 的优化版本，直接影响运行频率和 credit 消耗
• Context Scope 决定了 agent 每次运行读取的内容量，直接影响效率和准确性
• Parallel Tool Use 是减少步骤数的具体策略，与 Context Scope 共同服务于性能优化目标
• Activity Log 是迭代调试的基础设施，连接「测试与排错」和「提升可靠性」两大主题
• 整体逻辑链：选择可重复工作流 → 写清晰指令（含 Definition of Done） → 配置运行方式（Trigger/Schedule） → 测试迭代（Activity Log） → 性能优化（Context Scope + Parallel Tool Use + High-Signal Trigger）

agentic reading｜3️⃣ 费曼 x3