开源Python框架Cayu:5分钟搭建能重启恢复的长时Agent,终极入门指南

原创2026-11-03 14:21:321,440 阅读

开源Python框架Cayu:5分钟搭建能重启恢复的长时Agent,终极入门指南

Cayu 是一个开源的 Python 框架(runtime),专为构建能跨越进程重启而持续运行的长时 Agent 而设计:durable sessions 存活于重启与重新部署,副作用前有人工审批,每次模型调用前强制预算上限。新手只需 5 分钟,即可跑通一个可恢复的长时 Agent 项目。

为什么需要 Cayu:Agent 的"生产陷阱"

原型很好写,但真正跑在生产环境的 Agent 往往死在边界上:

  • 进程在产生副作用后、状态记录前崩溃,任务直接丢失;
  • 运行到一半需要人工审批或补充输入,整个会话就此中断;
  • 重试、fork、子 Agent 让成本与因果归属变得一团糟;
  • 上下文膨胀到模型服务商直接拒绝下一次请求。

Cayu 把这些统统变成 runtime 契约:关键动作是结构化事件,durable session 把转录和检查点持久化到存储中,进程重启后可以从断点恢复。🛠️

5分钟快速开始:4步跑通你的第一个 Agent

要求 Python 3.11+。

第 1 步:安装

pip install cayu pytest

第 2 步:一键生成项目

cayu new myagent
cd myagent

脚手架自带一个无工具依赖的 model-only agent、提示词/工具/策略/环境/工作流等完整目录结构、一个可离线运行的 runtime 测试和 eval。

第 3 步:体检与测试

cayu inspect --json
cayu check --fail-on warning --json
pytest

第 4 步:配置 provider 并运行

通过 configuration/settings.py 或环境变量 CAYU_PROVIDER 配置模型服务后:

python run.py --message "Review this change."

想先看看核心 API 长什么样,参考 examples/send_turn.py:send_turn 传入已存在的 session_id 即自动续接会话,传 None 则新建会话——这正是"重启恢复"的产品级入口。

重启恢复原理:Durable Session 与 SQLite 存储

CayuApp() 默认使用内存存储,仅适合一次性示例和测试;生成的项目会把本地所有 Cayu 存储配置到 data/cayu.db(SQLite),会话因此能存活于进程重启。🔄

核心机制只有两个概念:

概念 作用
Durable SessionStore 会话身份、转录、事件、状态、检查点持久化到 SQLite/Postgres
ResumeRequest 进程死后,从断点续接已有会话并带入新一轮消息

以 long-running 预设为例,项目里会生成一个"发票支付 agent",它的 continue_request 通过 ResumeRequest 绑定 expected_run_epoch——若其他进程已先续接了会话,恢复会立刻被拒绝,而不是盲目重放。每个暂停点(审批、等待回复、定时器)都配有专门的重启测试,可直接作为回归保障。生成逻辑见 src/cayu/cli/scaffold_long_running.py。

多进程生产部署时,把 SQLite 换成 PostgreSQL 即可(pip install 'cayu<a href="https://link.gitcode.com/i/ef07a19f7463253da8a4728599c314dd" target="_blank">postgres]'),解析优先级见 [docs/session-store-targets.md。

按需选择 Preset:别把所有原语都塞进项目

cayu new 提供四种预设,选最小的运行时形状起步:

预设 适合场景
--preset agent 单一模型驱动交互(默认)
--preset service 面向多用户的对外服务,自带安全测试骨架
--preset coding 仓库编码 agent:有界文件/Git 工具、持久知识、后台审查委派、人工输入
--preset long-running 长时任务:审批、等待回复、定时器、按会话预算上限、重启测试

用一条命令预览生成计划(不落地写文件):

cayu new myagent --preset agent --provider anthropic --dry-run --json

想深入理解"任务到底从哪里发起"(run / resume / dispatch / worker / subagent 的取舍),读 docs/triggering-runs.md 这份决策指南。

预算与审批:给长时 Agent 上安全网 🔒

长时运行的 Agent 最怕两件事:花超预算、无人批准就执行副作用。Cayu 内建了双保险:

  • 预算上限:BudgetLimit(按会话)+ BudgetPolicy(按应用),每次模型调用前检查;达到上限的会话以 session.limit_reached 事件 interrupted 停止,且该步的待执行工具调用不会运行;
  • 副作用审批:ToolPolicy 返回 REQUIRE_APPROVAL 时,操作挂起等待人工在 cayu.approvals 中裁决,审批状态本身也是持久的——重启后依然可查可批。

long-running 预设演示了完整闭环:pay_invoice 工具只有获得审批、且携带幂等键后才执行一次支付,重复调用返回首次收据而非重复扣款。

下一步:官方文档与参考示例

从 cayu new 到 python run.py,再到 durable session 跨越重启继续工作——这就是 Cayu 给长时 Agent 提供的最小可行路径。🚀

登录后查看全文
cayu