开源Python框架Cayu:5分钟搭建能重启恢复的长时Agent,终极入门指南
开源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 工具只有获得审批、且携带幂等键后才执行一次支付,重复调用返回首次收据而非重复扣款。
下一步:官方文档与参考示例
- 项目总览与能力矩阵:README.md
- 运行时契约(持久化、重放、审批、中断、预算的精确行为):docs/runtime-contracts.md
- 可运行示例索引:examples/README.md
- 架构与设计记录:docs/architecture.md
- 长时任务专题指南(安装包后运行):
cayu guide long-running
从 cayu new 到 python run.py,再到 durable session 跨越重启继续工作——这就是 Cayu 给长时 Agent 提供的最小可行路径。🚀