CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Examples
Runnable scripts demonstrating CubeLoop features.
Run any example with uv:
uv run python examples/<name>.py
Provider setup
Recipe examples use a real LLM. Set one of the following before running:
# Anthropic (or Anthropic-compatible endpoint):
export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_BASE_URL=https://... # optional, for compatible endpoints
export MODEL=claude-sonnet-4-6 # optional, this is the default
# OpenAI (or OpenAI-compatible endpoint):
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://... # optional, for compatible endpoints
export MODEL=gpt-4o # optional, this is the default
The shared _provider.py module reads these env vars and exposes provider
and MODEL_ID for each example to import. ANTHROPIC_API_KEY takes priority
when both are set.
Recipes
| Example | What it shows | Extra deps |
|---|---|---|
weather_agent.py |
Tool calling, streaming output, Ctrl-C cancellation | httpx |
persistent_chat.py |
SQLite-backed chat that survives restarts | cubeloop[sqlite] |
multi_provider_failover.py |
Automatic failover between providers on error | — |
ask_user_form.py |
HITL multi-question form via ask_user_tool |
— |
sandbox_confirm.py |
ApprovalPolicyMiddleware — auto-allow, deny, or confirm tool calls |
— |
resumable_tasks.py |
Crash-resilient tasks with idempotent tools and checkpointing | cubeloop[sqlite] |
postgres_fastapi.py |
Production HTTP service: FastAPI + SSE streaming + Postgres | cubeloop[postgres] fastapi uvicorn[standard] sse-starlette |
weather_agent.py
uv run --with httpx python examples/weather_agent.py
persistent_chat.py
uv run python examples/persistent_chat.py alice
# Chat, then Ctrl-D. Re-run same command — history is restored.
uv run python examples/persistent_chat.py bob
# Different thread, clean slate.
Requires: cubeloop[sqlite]
multi_provider_failover.py
uv run python examples/multi_provider_failover.py
Runs with a bad primary key to demonstrate failover, then succeeds via the real secondary key.
ask_user_form.py
uv run python examples/ask_user_form.py
The host loop answers the form programmatically (simulating a UI). In a real app you'd render the questions to a frontend.
sandbox_confirm.py
uv run python examples/sandbox_confirm.py
Shows auto-allow (echo, ls, cat), hard-deny (rm -rf /), and
human-confirm (any other command, auto-approved in the simulated host).
resumable_tasks.py
# Start a job:
uv run python examples/resumable_tasks.py job-1 start
# Kill mid-flight, then resume:
uv run python examples/resumable_tasks.py job-1
Items already processed are skipped on resume (idempotent tool backed by
a file-based job store in /tmp/cubeloop-jobs/).
Requires: cubeloop[sqlite]
postgres_fastapi.py
uv sync --extra postgres
export DATABASE_URL=postgresql://user:pass@localhost/cubeloop
uv run --with fastapi --with "uvicorn[standard]" --with sse-starlette \
uvicorn examples.postgres_fastapi:app --reload --port 8000
curl -N -X POST http://localhost:8000/chat/conv1/messages \
-H "content-type: application/json" \
-d '{"text":"hi"}'
Checkpointing (service integration)
| Example | What it shows | Requires |
|---|---|---|
checkpointing_postgres.py |
Persist an agent conversation in Postgres and resume it after a simulated restart | A reachable Postgres |
checkpointing_mysql.py |
Same, on MySQL 8.0.13+ | A reachable MySQL |
Both use FauxProvider (no API key needed) and create a throwaway database
that is dropped on exit — safe to re-run against a dev server.
CUBELOOP_PG_DSN=postgresql://user:pass@host:5432/dbname \
uv run python examples/checkpointing_postgres.py
CUBELOOP_MYSQL_DSN=mysql://user:pass@host:3306/dbname \
uv run python examples/checkpointing_mysql.py
Each script bootstraps the CubeLoop schema inline so it runs standalone, but in production the schema is owned by your host application's Alembic migration. See the host-integration runbooks for the migration recipe and version-upgrade flow: