CubePi

CubePi 是一个 Pythonic、原生异步的 Agent 框架，为高性能、可读性和 生产级持久化而设计。它把一次 Agent 运行建模为一个线性的 while 循环——可追踪、可调试，没有 DAG、没有图 DSL、没有出人意料的控制流。 整个核心循环你五分钟就能读完。

pip install cubepi

然后跳到 快速开始，五分钟内跑通一个 能调用工具的 Agent。

你能拿到什么

• 普通 async 函数，不是图节点。 Agent 循环就是一个对消息轮次的 while 循环。你把工具写成 async def 函数，框架负责路由调用并并行 执行。
• 统一的流式模式。 所有 provider 都通过 MessageStream 产出 StreamEvent。你用 async for 迭代它。没有 callback 注册表，也没有 为文本和工具单独的 handler 类型。
• 追加式检查点。 每一轮只写入新消息，而不是整段对话历史。无论 会话多长，数据库 I/O 都是 O(1)——SQLite 适合个人开发,Postgres 适合 生产环境。
• 原生多 provider。 Anthropic 和 OpenAI 开箱即用,通过 Provider Protocol 接入。要新增一个 provider 只需要写一个类。
• 八个 Hook 的中间件。 transform_context、convert_to_llm、 transform_system_prompt、before_tool_call、after_tool_call、 should_stop_after_turn、after_model_response、on_run_end—— 每一个都有明确的组合规则。没有"节点执行顺序之谜"。
• MCP 加载器。 指向任意 Model Context Protocol 服务器 （HTTP 或 stdio),就能拿回一组 AgentTool。
• 原生 OpenTelemetry。 挂一个 Tracer,每次 prompt 就产生符合 GenAI 语义约定的 OTel span 树 —— Jaeger、Tempo、Honeycomb、 Datadog 等任意 OTLP 后端都能直接接收。默认不记录任何 payload； 需要时用 record_content=True 配合 redact 回调显式开启。
• 人机协同（HITL）。 在 run 中途挂起 Agent，把决策路由给人工 （审批 / 拒绝 / 回答），然后继续执行 —— 支持检查点持久化， 等待期间进程可以重启。

接下来去哪儿

如果你想…	从这里开始
安装并跑通第一个 Agent	入门 → 安装
理解骨架	入门 → 核心概念
接入一个真实的工具 Agent	指南 → 构建第一个 Agent
跨重启保留对话	指南 → SQLite 检查点
查找某个具体符号	API 参考
看完整的可运行示例	Recipes
从 langgraph Agent 迁移	迁移 → 来自 langgraph

状态

你正在浏览的是 CubePi 0.8 发布文档，这是基于已发布 0.8 API 的最新稳定 文档。

CubePi 0.8 新增会话分叉（Agent.fork() / Agent.fork_once()）、基于 run 的 checkpointing（全后端 schema v3→v4）、@tool 装饰器（便捷工具定义），以 及 Agent.prompt() 现在会返回 run_id。如需查看 main 分支上的未发布变更， 请通过版本选择器切换到 Next 文档。

源代码、Issue 和讨论都在 GitHub。