async-event-agent

异步与事件驱动 Agent

何时使用

• 要让 Agent 在没有用户输入时也行动：定时生成报告、周期性检查服务器、跟进未回复的邮件、到工作时间再拨打电话。
• 要接入外部事件源：新邮件到达、API 回调、IM/短信消息、GitHub PR 变更、支付失败告警。
• 要支持执行期间被打断：长任务运行中用户说"停""改一下预算""先帮我查个天气"。
• 要同时管理多个并发任务：并行跑几个脚本、先完成的先看结果、未达进度就取消。
• 要从回合制 ReAct 循环升级为长期运行的事件循环 Agent。
• 要评估某个模型/接口是否支持原生异步，或为不支持的接口设计兼容层。
• 任务需要在"发起"与"收尾"之间跨越多个回合（如代打电话、长时审批流）。
• Agent 需要以"活人感"与用户异步沟通（发消息、图片、文件、按紧急度推送提醒），而非必须打开指定会话。

核心原则

• 回合制是交互约定，不是环境性质。 世界不会等模型反应完才变化；任务常在"发起"与"收尾"之间跨越多个回合。
• 架构是事件循环，不是轮询。 Agent 是一个长期运行的循环：每轮从输入队列取若干事件 → 追加到轨迹 → 调一次 LLM → 执行它决定的工具 → 回到开头等下一批。不要用"反复问有没有新消息"的轮询。
• "主动服务"的前提是事件能推给 Agent。 Hooks（框架内生命周期事件）、Cron（定时调度）、Heartbeat（每隔 N 分钟唤醒）三种机制里只有后两种让 Agent 自己动起来，且都是时间驱动的；对内置渠道之外的第三方事件源（新邮件、外部回调）必须建实时推送通道，否则只能等下一个周期才察觉——这个延迟在验证码等待、三方通话等场景里不可接受。
• 安全点决定一切。 同步接口中事件只能在循环边界（一段推理结束、一次工具返回）被消费；紧急事件的取消式处理本质是"主动提前制造一个安全点"。取消点必须是工具或推理能安全收尾的位置。
• 取消 ≠ 撤销。 发送取消信号只是让执行器停止；已经发生的动作不会回滚。未完成的工具结果用显式占位符表示，不能伪造成功。
• 三种处理策略按紧急度选择：
  • 取消式（紧急事件：user.interrupt、supervisor.instruction、agent.interrupt、紧急告警）：停当前操作 → 清空队列 → 所有事件连同紧急事件一次性追加到轨迹 → 立即重新调 LLM。
  • 队列式（常规事件：user.input、tool.result、timer.trigger）：放入队尾不打断，等本轮到达安全点后批量追加，减少往返。
  • 并行式（独立、轻量、需快响的查询，如"今天天气怎么样"）：在独立推理会话中执行，结果追加进主轨迹并明确标记为并行，避免 LLM 混淆。
  • 硬编码规则有局限；建议用轻量分类 LLM 做事件路由器。
• 所有输入统一建模为结构化事件：来源（谁）、渠道（方式）、内容（什么/紧急度）、上下文（与哪个任务相关）。这是防止把工具结果误当用户指令、以及提示注入的前提。异构触发器（webhook、定时器、邮件、数据库变更、文件监听）统一建模后，Agent 才能用一致方式处理不同来源的刺激。
• 异步语义要写进工具接口：把"启动"和"完成"解耦——initiate_phone_call 立即返回任务 ID 和初始状态，进展通过 phone_call_connected / phone_call_ended 等事件通知。工具名和描述本身就要传达异步语义（"任务发起后立即返回 ID，你可以继续处理其他事项，结束后会收到单独通知"）。
• 三条路线按模型能力选择：原生异步（工具挂起、模型继续、回合中途 steering）> 同步接口兼容（占位符 + 队列 + 重新请求）> 退化回纯串行。用了 asyncio 不等于模型具备异步能力，仍需应用层管理事件来源、工具生命周期与结果归属。
• 可靠处理比能接收更难：至少要检查——延迟结果能否归入正确任务且缺席时不编造；处理新要求后能否恢复原任务并区分"修改计划"与"停止执行"；多条更新能否同时遵守而不是只记住最后一条。
• 事件优先级要动态判断，不是静态排序：Agent 应像秘书按紧急程度决定先处理哪个、做到一半能否暂停切换，而不是固定先后。长任务异步执行不应阻塞用户交互，被打断的任务要能自然恢复。
• 占位符只在打断时引入：常态下 LLM 看到的就是标准同步轨迹；只有出现打断才插入"工具正在后台执行"的占位 tool result 修复配对格式，后台真实结果到达后再以带来源和任务 ID 的事件送回。