Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

3.6 KB
Raw Blame
---
id: intro
title: "CubePi — Pythonic async-native agent framework"
description: "A Pythonic, async-native agent framework. Plain async functions, append-only checkpointing, three dependencies."
slug: /
sidebar_position: 0
---

# CubePi

**CubePi** is a Pythonic, async-native agent framework designed for high
performance, readability, and production-grade persistence. It provides a
leaner alternative to graph-based agent runtimes by modeling agent logic as
a linear `while` loop that developers can easily trace and debug.

```bash
pip install cubepi
```

Then jump to the [Quick Start](./getting-started/quick-start) to ship a
working tool-using agent in under five minutes.

## What you get

- **Plain async functions, not graph nodes.** The agent loop is a
  `while` loop over message turns. You build tools as `async def`
  functions; the framework routes calls and executes them in parallel.
- **One streaming pattern.** Every provider yields `StreamEvent`s
  through a `MessageStream`. You iterate it with `async for`. No
  callback registries, no separate handler types for text vs. tools.
- **Append-only checkpointing.** Persistence writes the new messages on
  each turn, not the full transcript. O(1) DB I/O regardless of
  conversation length — SQLite for laptops, Postgres for production.
- **Native multi-provider.** Anthropic and OpenAI ship in the box,
  through a `Provider` Protocol. Add a new provider in one class.
- **Eight-hook middleware.** `transform_context`, `convert_to_llm`,
  `transform_system_prompt`, `before_tool_call`, `after_tool_call`,
  `should_stop_after_turn`, `after_model_response`, `on_run_end` — each
  with explicit composition rules. No mystery node ordering.
- **MCP loaders.** Point at any
  [Model Context Protocol](https://modelcontextprotocol.io) server
  (HTTP or stdio) and get back a list of `AgentTool`s.
- **OpenTelemetry built in.** Attach a `Tracer` and every prompt
  produces a tree of OTel spans aligned with the GenAI Semantic
  Conventions — works with Jaeger, Tempo, Honeycomb, Datadog, or any
  OTLP-compatible backend. No payloads recorded by default; opt in
  with `record_content=True` and a `redact` callback.
- **Human-in-the-Loop.** Suspend an agent mid-run, route a decision to
  a human (approve/reject/answer), then resume — with full checkpoint
  persistence so the agent survives a process restart while waiting.

## Where to go next

| If you want to… | Start here |
|---|---|
| Install and run your first agent | [Getting Started → Installation](./getting-started/installation) |
| Understand the building blocks | [Getting Started → Core Concepts](./getting-started/core-concepts) |
| Wire a real tool-using agent | [Guides → Building Your First Agent](./guides/agents/first-agent) |
| Persist a conversation across restarts | [Guides → SQLite Checkpointing](./guides/checkpointing/sqlite) |
| Ship traces to Jaeger / Tempo / Honeycomb | [Guides → Tracing](./guides/tracing/overview) |
| Look up a specific symbol | [API Reference](./api/) |
| See full working examples | [Recipes](./recipes/weather-agent) |
| Port an existing langgraph agent | [Migration → From langgraph](./migration/from-langgraph) |

## Status

You are reading the **CubePi 0.7** release docs. This is the latest stable
documentation set for installing CubePi and building against the published
0.7 API.

CubePi 0.7 adds provider-level `generate()`, compaction and subagent
middleware, `on_run_end`, typed provider errors, `Tracer.oneshot()`, and
checkpointed HITL run IDs. For unreleased changes on `main`, switch to the
**Next** docs from the version picker.

Source, issues, and discussion live on
[GitHub](https://github.com/cubeplexai/cubepi).