Sidekick Agents

按会话事件启动后台角色，配置触发次数、持久运行与上下文发送预算。

Sidekick 是按事件自动在后台运行的 agent，将上下文发布到会话 inbox。与主智能体按任务显式派发的 subagent 不同，Sidekick 的启动由 profile 中的触发器决定。

定义角色

在 agent profile 中加入 sidekick 块：

---
name: Context Gatherer
description: Gathers relevant context when the working directory changes.
sidekick:
  triggers:
    - session.context_changed
    - event: user.message
      limit: 1
  behavior: persistent
  maxSendsPerTurn: 2
---

Gather relevant repository context and summarize changes in project structure.

这是官方配置示例的用途整理。agent 文件的位置和 ID 规则仍见创建与调用 Agents。

触发事件

事件	时机
user.message	每条用户消息
session.context_changed	工作目录、仓库或分支变化

triggers 至少包含一个条目。裸字符串不限制触发次数；对象形式可用 event 和可选 limit，limit 是每会话最大触发次数，设置时必须为正整数。

示例中 context_changed 不设次数上限，user.message 最多一次。这是两个独立触发条件，不是“只在第一条消息之后才监听目录变化”。

运行方式

behavior 默认为 restart：新事件取消上一个运行并从头启动，适合无状态的上下文收集。

persistent 保持同一个长期运行的任务，把新消息送入已有循环，适合跨轮积累状态。选择方式会影响是否保留已有工作，不能只根据名称判断“更快”或“更完整”。

maxSendsPerTurn 默认 1，限制每次触发可以向 inbox 发送多少次。persistent 模式下，每条送达的用户消息重置该预算。触发次数限制与发送预算分别控制启动频率和输出量，应一起考虑。