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.10 发布版文档，这是安装 CubePi 并基于 0.10 API 开发的最新稳定文档。

CubePi 0.10 新增 DeferredToolGroup（渐进式 MCP 工具披露——把 schema 藏在目录后面，通过 load_tools 工具按需展开）、 BoundModel.generate_structured()（基于 tool 调用、用 Pydantic 模型 校验的结构化输出）、Provider 协议上的 tool_choice 参数 （"auto" / "required" / "none" / tool 名）、以及 GoalMiddleware （由独立的评估模型判定完成条件的自主目标驱动 run）。on_run_end 现在 在每一轮外层循环都会触发，而不是每次 prompt() 只触发一次； Recorder / Meter 现在会订阅 FallbackBoundModel 链上的每一段 provider，所以故障转移之后的调用对 provider 级 observability 不再隐形 （完整改动见 Changelog）。

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