Frequently Asked Questions

CubePi is a Pythonic, async-native agent framework for building LLM-powered agents in Python. It models the agent as a plain async while-loop — no state graphs, no nodes/edges to wire — so the core algorithm is readable in five minutes. It ships with append-only checkpointing, composable middleware, native OpenTelemetry tracing, MCP support, and a FauxProvider for deterministic tests.

LangGraph models an agent as a state graph you wire together with nodes, edges, and typed channels. CubePi models the same agent as a plain async while loop. There is no StateGraph, no add_edge, no ToolNode, and no TypedDict to maintain. CubePi also checkpoints append-only (O(1) per turn vs. full snapshot per step) and has only three core dependencies. See the full LangGraph comparison.

CrewAI organises agents around role-playing metaphors — crews, roles, goals, and backstories. CubePi skips the metaphor: an agent is a function with a system prompt. CubePi also ships built-in append-only checkpointing (CrewAI has none), is async-first, and has native OpenTelemetry. See the full CrewAI comparison.

Both frameworks are async-first and built on Pydantic. PydanticAI focuses on structured output and dependency injection via RunContext; CubePi focuses on persistent multi-turn conversations, composable middleware hooks, provider fallback, and vendor-neutral OpenTelemetry (vs. Logfire). CubePi also ships built-in checkpointing that PydanticAI lacks. See the full PydanticAI comparison.

Yes. CubePi ships AnthropicProvider and OpenAIProvider (plus OpenAIResponsesProvider for the Responses API) out of the box. You can add your own provider with a single class that implements the Provider protocol. Use FallbackBoundModel to chain providers — on a rate-limit or outage the next model in the chain is tried automatically.

CubePi ships four checkpointer backends: MemoryCheckpointer (development/testing), SQLiteCheckpointer (lightweight single-node), PostgresCheckpointer (production), and MySQLCheckpointer (production). All use append-only writes — each turn writes only the new messages, so write cost stays O(1) regardless of conversation length. Postgres and MySQL use Alembic for schema management; your app owns the DDL.

Most agent frameworks checkpoint by snapshotting the entire message list on every step. As conversations grow, write cost grows linearly. CubePi writes only the new messages produced in each turn — O(1) regardless of how long the thread is. This matters at scale: thousands of concurrent long-lived sessions with frequent turns.

Yes. Install pip install cubepi[mcp] and use StdioMCPLoader or HttpMCPLoader to load tools from any MCP-compatible server. Loaded tools plug into the same AgentTool interface as hand-written tools.

CubePi includes a Tracer and Meter that emit OpenTelemetry spans and metrics aligned with the GenAI Semantic Conventions. Spans export via OTLP/HTTP to any compatible backend (Jaeger, Grafana Tempo, Honeycomb, Datadog, AWS X-Ray, Langfuse, …) or to local JSONL files. The cubepi trace CLI lets you inspect JSONL traces in the terminal without a backend. Install with pip install cubepi[tracing,trace-cli].

Use FauxProvider. It emits realistic streaming deltas (content_block_start, text_delta, etc.) without making any API calls. You script the responses with provider.set_responses([...]) using helpers like faux_text() and faux_tool_call(). Tests run fully deterministically with no API keys.

CubePi supports Python 3.11, 3.12, 3.13, and 3.14. CI runs on all four versions.

CubePi is in beta (v0.9). The core agent loop, checkpointing, middleware, and tracing APIs are stable. Breaking changes follow semantic versioning and are documented in the changelog. The Postgres and MySQL checkpointers are used in production by early adopters.

pip install cubepi for the core. Add extras for optional features: pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]. With uv: uv add cubepi or uv add cubepi[sqlite,postgres,mcp,tracing].

Yes — CubePi is designed to maximise prompt cache hit rates. LLM providers (Anthropic, OpenAI) let you cache the stable prefix of a request so repeated turns don't re-process the same tokens, cutting costs by up to 90% and reducing latency. Two CubePi design decisions work together to make this reliable:

Append-only message storage. CubePi never rewrites or reorders history — it only appends new messages. This means the prefix of every request is byte-identical to the previous turn, which is exactly what the cache needs to get a hit. Frameworks that rebuild the full message list from a snapshot on every step silently break the cache if any serialisation detail changes.

Automatic cache breakpoints (Anthropic). AnthropicProvider marks three cache breakpoints by default: the system prompt, the last tool definition, and the last message in history. The last-message breakpoint moves forward each turn, keeping prior history warm. See the Prompt Caching guide for details on how to avoid breaking these breakpoints and how to read cache hit metrics from Usage.

Yes. CubePi is MIT licensed. Source code is on GitHub.