常见问题

CubePi 是一个 Pythonic、异步原生的 Agent 框架，用于在 Python 中构建 LLM 驱动的 Agent。 它将 Agent 建模为普通的异步 while 循环 —— 无状态图，无需连接节点/边 —— 核心算法五分钟内可读懂。 它内置追加式 checkpointing、可组合中间件、原生 OpenTelemetry 追踪、MCP 支持，以及用于确定性测试的 FauxProvider。

LangGraph 将 Agent 建模为需要手动连接节点、边和类型化通道的状态图。CubePi 将同样的 Agent 建模为普通的 async while 循环。 没有 StateGraph，没有 add_edge，没有 ToolNode，也没有需要维护的 TypedDict。 CubePi 还采用追加式 checkpointing（每轮 O(1) vs. 每步全量快照），且只有三个核心依赖。 查看完整的 LangGraph 对比。

CrewAI 围绕角色扮演的隐喻组织 Agent —— 团队、角色、目标和背景故事。CubePi 省去了这层隐喻：Agent 就是一个带有 system prompt 的函数。 CubePi 还内置了追加式 checkpointing（CrewAI 没有），异步优先，并具有原生 OpenTelemetry。 查看完整的 CrewAI 对比。

两者都是异步优先且基于 Pydantic 的框架。PydanticAI 聚焦于结构化输出和通过 RunContext 实现的依赖注入； CubePi 聚焦于持久化多轮对话、可组合的中间件钩子、Provider 故障转移，以及厂商中立的 OpenTelemetry（而非 Logfire）。 CubePi 还内置了 PydanticAI 所缺乏的 checkpointing。 查看完整的 PydanticAI 对比。

支持。CubePi 内置 AnthropicProvider 和 OpenAIProvider（以及用于 Responses API 的 OpenAIResponsesProvider）。你可以用一个实现 Provider 协议的类添加自定义 Provider。 使用 FallbackBoundModel 链式连接 Provider —— 在限速或故障时自动切换到链中的下一个模型。

CubePi 提供四种 checkpointer 后端：MemoryCheckpointer（开发/测试）、SQLiteCheckpointer（轻量级单节点）、PostgresCheckpointer（生产环境） 和 MySQLCheckpointer（生产环境）。所有后端均使用追加式写入 —— 每轮只写入新消息， 无论对话多长，写入成本保持 O(1)。

大多数 Agent 框架通过每步快照整个消息列表来进行 checkpoint。随着对话增长，写入成本线性增长。 CubePi 只写入每轮产生的新消息 —— 无论线程多长，都是 O(1)。这在规模化时至关重要：数千个并发的长存会话，频繁轮次。

支持。安装 pip install cubepi[mcp]，使用 StdioMCPLoader 或 HttpMCPLoader 从任何兼容 MCP 的服务器加载工具。加载的工具与手写工具使用相同的 AgentTool 接口。

CubePi 内置 Tracer 和 Meter，输出符合 GenAI 语义约定的 OpenTelemetry span 和指标。 Span 通过 OTLP/HTTP 导出到任何兼容后端（Jaeger、Grafana Tempo、Honeycomb、Datadog、AWS X-Ray、Langfuse……） 或本地 JSONL 文件。cubepi trace CLI 可在终端中无需后端直接检查 JSONL trace。 安装：pip install cubepi[tracing,trace-cli]。

使用 FauxProvider。它在不发起任何 API 调用的情况下产生真实的流式 delta（content_block_start、text_delta 等）。通过 provider.set_responses([...]) 配合 faux_text() 和 faux_tool_call() 等辅助函数编写响应脚本。测试完全确定性，无需 API Key。

CubePi 支持 Python 3.11、3.12、3.13 和 3.14。CI 在所有四个版本上运行。

CubePi 处于 Beta 阶段（v0.9）。核心 agent 循环、checkpointing、中间件和追踪 API 均已稳定。 重大变更遵循语义化版本管理，并记录在 更新日志 中。 Postgres 和 MySQL checkpointer 已被早期用户用于生产环境。

核心安装：pip install cubepi。通过 extras 添加可选功能：pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]。 使用 uv：uv add cubepi 或 uv add cubepi[sqlite,postgres,mcp,tracing]。

是的 —— CubePi 的设计目标之一就是最大化 prompt 缓存命中率。LLM 提供商（Anthropic、OpenAI）允许你缓存请求的稳定前缀， 这样相同的 token 不需要在每轮都重新处理，可降低最高 90% 的费用并减少延迟。CubePi 有两个设计决策共同保障了这一点：

追加式消息存储。CubePi 从不重写或重排历史消息 —— 只追加新消息。这意味着每次请求的前缀与上一轮完全相同， 正是缓存命中所需要的。那些每步都从快照重建完整消息列表的框架，一旦序列化细节有任何变化，就会悄悄破坏缓存。

自动缓存断点（Anthropic）。AnthropicProvider 默认标记三个缓存断点：system prompt、 最后一个工具定义，以及历史中的最后一条消息。最后一条消息的断点每轮向前推进，让之前的历史保持热缓存。 查看 Prompt Caching 指南 了解如何避免破坏这些断点， 以及如何从 Usage 中读取缓存命中指标。

是的。CubePi 采用 MIT 许可证。源代码托管在 GitHub 上。