Skip to content

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

feat(website): SEO/geo marketing pages and prompt-caching guide

xf gong56a573ab9392
diff --git a/.gitignore b/.gitignore
index f4cca3d..35bc346 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,3 +34,6 @@ website/docs/api/*.mdx
# Playwright CLI session artifacts
.playwright-cli/
+
+# Marketing drafts (local only)
+dev/marketing/
diff --git a/pyproject.toml b/pyproject.toml
index 5cb8f41..50f6c14 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ readme = "README.md"
license = "MIT"
requires-python = ">=3.11"
classifiers = [
- "Development Status :: 3 - Alpha",
+ "Development Status :: 4 - Beta",
"Framework :: AsyncIO",
"Intended Audience :: Developers",
"Programming Language :: Python :: 3.11",
diff --git a/website/docs/guides/agents/prompt-caching.md b/website/docs/guides/agents/prompt-caching.md
new file mode 100644
index 0000000..61518de
--- /dev/null
+++ b/website/docs/guides/agents/prompt-caching.md
@@ -0,0 +1,237 @@
+---
+title: Prompt Caching
+description: "How CubePi maximises prompt cache hit rates — append-only message storage, automatic cache breakpoints, and how to avoid breaking the cache."
+---
+
+# Prompt Caching
+
+Prompt caching lets LLM providers reuse the KV computation for the
+stable prefix of a request instead of reprocessing it on every turn.
+The savings are significant: Anthropic charges cached tokens at
+**10% of the normal input price**, and cache hits also reduce
+time-to-first-token.
+
+CubePi is designed from the ground up to maximise cache hit rates.
+This guide explains how caching works, why CubePi's architecture
+keeps the cache warm, and what you can do (or avoid doing) to
+preserve those hits.
+
+---
+
+## How prompt caching works
+
+Every LLM API request is a sequence of content blocks: system prompt,
+tool definitions, then the conversation history. The provider hashes
+the byte content of each block. If an incoming request shares a
+prefix with a recently-seen request up to the TTL, the cached KV
+state for that prefix is reused — the provider only processes the
+new tokens beyond the cache boundary.
+
+```
+Request N: [system] [tools] [msg 1] [msg 2] [msg 3]
+ ↑ ↑ ↑
+ cached cached cached ← all hits on turn N+1
+ [msg 4] ← new tokens only
+```
+
+Two things are required for a cache hit:
+
+1. **The prefix is byte-identical** to the previous request. Any
+ change — reordering, reformatting, adding a character — is a miss.
+2. **The TTL hasn't expired.** Anthropic offers 5-minute (`"short"`)
+ and 1-hour (`"long"`) retention; OpenAI caches automatically for
+ prompts over 1 024 tokens.
+
+---
+
+## Why append-only storage matters
+
+Many agent frameworks rebuild the full message list from a checkpoint
+snapshot on every turn. If serialisation details change — dict key
+ordering, whitespace, a timestamp field — the resulting byte sequence
+differs from the previous request and **every cache breakpoint from
+that point on misses**.
+
+CubePi's checkpointer is append-only: it only ever adds new messages
+to the end of the thread. The in-memory `agent.state.messages` list
+grows by appending; it is never rebuilt or reshuffled. This means the
+prefix of every request is guaranteed to be byte-identical to the
+previous turn, which is the most fundamental requirement for cache
+hits.
+
+---
+
+## Anthropic: automatic cache breakpoints
+
+`AnthropicProvider` inserts `cache_control` markers automatically
+via `DefaultCacheMarkerPolicy`. By default, three breakpoints are
+placed on each request:
+
+| Breakpoint | What gets cached | Why here |
+|---|---|---|
+| System prompt | The full system prompt block | Most stable content — rarely changes across turns |
+| Last tool definition | All tool schemas up to and including the last one | Tool lists change infrequently |
+| Last message in history | All prior conversation history | Moves forward each turn; prior turns stay warm |
+
+On turn N+1, the first two breakpoints are identical to turn N (same
+system prompt, same tools), so they get cache hits. The
+last-message breakpoint has moved one message forward, so it writes
+a new cache entry covering the slightly-longer history — and that
+entry will be a hit on turn N+2.
+
+### Configuration
+
+```python
+from cubepi.providers.anthropic import AnthropicProvider
+
+# Default: short TTL (5 min), automatic breakpoints
+provider = AnthropicProvider(api_key="…")
+
+# Long TTL (1 h) — use when turns are slow or infrequent
+provider = AnthropicProvider(api_key="…", cache_retention="long")
+
+# Disable caching entirely
+provider = AnthropicProvider(api_key="…", cache_retention="none")
+```
+
+### Reading cache metrics
+
+Each `AssistantMessage` carries a `Usage` object. The cache fields:
+
+```python
+agent.subscribe(lambda event, signal=None: None)
+await agent.prompt("Summarise the document")
+
+last_msg = agent.state.messages[-1] # AssistantMessage
+usage = last_msg.usage
+print(usage.input_tokens) # total prompt tokens (inclusive of cache_read)
+print(usage.cache_read_tokens) # tokens served from cache ← savings here
+print(usage.cache_write_tokens) # tokens written to cache this turn
+```
+
+Cache hit rate for a turn: `cache_read_tokens / input_tokens`.
+
+:::tip
+`input_tokens` in CubePi's `Usage` is the **inclusive** total (prompt
+= input + cache_read + cache_creation). Do **not** add `cache_read_tokens`
+to the denominator — you would be double-counting.
+:::
+
+You can also see these fields in the `cubepi trace` CLI output and in
+the OTel spans emitted by `Tracer`:
+
+```
+gen_ai.usage.input_tokens = 8 420 (inclusive)
+gen_ai.usage.cache_read.input_tokens = 7 980 (subset)
+```
+
+---
+
+## OpenAI: automatic caching
+
+OpenAI caches automatically for prompts longer than 1 024 tokens —
+no explicit `cache_control` markers are needed. CubePi surfaces the
+hit data through the same `Usage` interface:
+
+```python
+usage.cache_read_tokens # maps to prompt_tokens_details.cached_tokens
+```
+
+There is nothing to configure on the CubePi side. Keep the system
+prompt and tool definitions stable across turns and OpenAI's cache
+will warm up naturally.
+
+---
+
+## How to avoid breaking the cache
+
+### ✅ Do
+
+- **Keep the system prompt stable across turns.** The system prompt
+ is the outermost cache breakpoint. Changing it invalidates
+ everything.
+- **Keep the tool list stable.** Add or remove tools between
+ *conversations*, not between *turns*. The tool-definition
+ breakpoint covers the entire tool list; any change invalidates
+ from there.
+- **Use `cache_retention="long"`** if your agent turns take more than
+ 5 minutes (long thinking runs, slow tools, infrequent users).
+- **Use `agent.steer()`** to inject mid-turn guidance instead of
+ prepending a new message to history — steer appends, not inserts.
+
+### ❌ Avoid
+
+- **Injecting messages into the middle of history.** Inserting a
+ message before the last position shifts all subsequent messages,
+ making the sequence differ from what the provider cached.
+- **Changing the system prompt to include per-request data** (e.g.
+ current timestamp, request ID). Put volatile data in the user
+ message instead.
+- **Reordering tool definitions.** The tool list is serialised in
+ order; changing the order is a cache miss even if the tools
+ themselves are identical.
+- **Modifying a tool's description between turns** for the same
+ thread. Description changes are serialised into the schema and
+ will break the tool-definition breakpoint.
+
+---
+
+## Custom cache policy (Anthropic)
+
+If the default three-breakpoint strategy does not fit your use case,
+implement `CacheMarkerPolicy` and pass it to the provider:
+
+```python
+from cubepi.providers.anthropic import CacheMarkerPolicy, AnthropicProvider
+from cubepi.providers.base import Message
+
+class SystemOnlyPolicy:
+ """Cache only the system prompt — useful when tool lists change often."""
+
+ def mark_system(self) -> bool:
+ return True
+
+ def mark_last_tool(self) -> bool:
+ return False
+
+ def message_breakpoint_indices(self, messages: list[Message]) -> list[int]:
+ return [] # no message breakpoints
+
+provider = AnthropicProvider(
+ api_key="…",
+ cache_policy=SystemOnlyPolicy(),
+)
+```
+
+The three methods map directly onto the three default breakpoints.
+Return `True` / a non-empty list to enable a breakpoint, `False` /
+`[]` to skip it.
+
+---
+
+## Multi-tenant considerations
+
+In a multi-tenant setup each `thread_id` is an independent
+conversation. Cache hits are per-thread: user A's history warms a
+cache entry that benefits only user A's subsequent turns.
+
+For maximum cache efficiency across tenants:
+
+- Use a **stable, shared system prompt** for all tenants rather than
+ embedding per-tenant data in the system prompt. Per-tenant context
+ belongs in the first user message or in tool results.
+- Keep tool definitions identical across all tenant agents. If
+ different tenants need different tool sets, consider separate
+ `Agent` instances with separate `AnthropicProvider` configurations
+ rather than dynamically mutating the tool list.
+
+---
+
+## See also
+
+- [Anthropic Provider](../providers/anthropic) — `cache_retention`,
+ `CacheMarkerPolicy`, and the `on_payload` hook for inspecting raw requests.
+- [Multi-turn Conversations](./multi-turn) — how message history grows
+ across turns and why append semantics matter.
+- [Tracing](../tracing/overview) — reading `cache_read.input_tokens`
+ from OTel spans.
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index a7feb03..e0d00d9 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -159,10 +159,13 @@ const config: Config = {
position: 'left',
items: [
{ to: '/compare/langgraph', label: 'vs LangGraph' },
+ { to: '/compare/crewai', label: 'vs CrewAI' },
+ { to: '/compare/pydantic-ai', label: 'vs PydanticAI' },
{ to: '/compare/pi-agent-core', label: 'vs pi-agent-core' },
],
},
{ to: '/changelog', label: 'Changelog', position: 'left' },
+ { to: '/faq', label: 'FAQ', position: 'left' },
{ type: 'docsVersionDropdown', position: 'right' },
{ type: 'localeDropdown', position: 'right' },
{ href: 'https://github.com/cubeplexai/cubepi', label: 'GitHub', position: 'right' },
diff --git a/website/package.json b/website/package.json
index 767c04b..070309e 100644
--- a/website/package.json
+++ b/website/package.json
@@ -28,6 +28,7 @@
"@docusaurus/preset-classic": "3.10.1",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
+ "pnpm": "^11.5.2",
"posthog-js": "^1.373.4",
"prism-react-renderer": "^2.3.0",
"react": "^19.0.0",
diff --git a/website/pnpm-lock.yaml b/website/pnpm-lock.yaml
index 06a45f4..736854c 100644
--- a/website/pnpm-lock.yaml
+++ b/website/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
clsx:
specifier: ^2.0.0
version: 2.1.1
+ pnpm:
+ specifier: ^11.5.2
+ version: 11.5.2
posthog-js:
specifier: ^1.373.4
version: 1.373.4
@@ -4825,6 +4828,11 @@ packages:
resolution: {integrity: sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw==}
engines: {node: '>=16.0.0'}
+ resolution: {integrity: sha512-ccYx44IGbvwlYl1c8CkHXeB7YbN/bic1D72Esb2lhkyMGWetwoB3a0XDCnFcA1mjvgj+9C1bsJ4rmQKZeWkpFg==}
+ engines: {node: '>=22.13'}
+ hasBin: true
+
resolution: {integrity: sha512-Uai+SupNSqzlschRyNx3kbCTWgY/2hcwtHEI/ej2LJWc9JJ77qKgGptd8DHwY1mXtZ7Aoh4z4yxfwMBue9eNgw==}
engines: {node: '>=18'}
@@ -12593,6 +12601,8 @@ snapshots:
pvutils: 1.1.5
tslib: 2.8.1
+
dependencies:
postcss: 8.5.14
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 287617c..b83b226 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = {
'guides/agents/multi-turn',
'guides/agents/streaming',
'guides/agents/forking',
+ 'guides/agents/prompt-caching',
]},
{ type: 'category', label: 'Providers', items: [
'guides/providers/overview',
diff --git a/website/src/pages/compare/crewai.tsx b/website/src/pages/compare/crewai.tsx
new file mode 100644
index 0000000..5106664
--- /dev/null
+++ b/website/src/pages/compare/crewai.tsx
@@ -0,0 +1,167 @@
+import React from 'react';
+import ComparePage, { type CompareContent } from '@site/src/components/Compare/ComparePage';
+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';
+
+const EN: CompareContent = {
+ them: 'CrewAI',
+ title: 'CubePi vs CrewAI — a leaner Python agent framework',
+ description:
+ 'CubePi vs CrewAI: a side-by-side comparison. CrewAI models agents as role-playing crew members with assigned tasks. CubePi models the agent as a plain async while-loop with typed middleware, append-only checkpointing, and 3 core dependencies.',
+ keywords:
+ 'CubePi vs CrewAI, CrewAI alternative, Python agent framework, async agent framework, CrewAI vs CubePi, multi-agent framework, crewai 替代品',
+ h1: 'CubePi vs CrewAI',
+ intro: [
+ 'CrewAI organises your agent system around role-playing metaphors — crews, agents with roles and backstories, and tasks that agents are assigned to. CubePi starts from a different premise: an agent is a plain async while-loop that calls the model, runs tools, and repeats.',
+ 'If the role-based abstraction is solving a problem you do not have, CubePi removes that layer. Here is how the two compare.',
+ ],
+ tableHeading: 'Side-by-side',
+ rows: [
+ { label: 'Abstraction', them: 'Crews of role-playing agents with roles, goals, and backstories', us: 'A plain async while-loop — readable top to bottom in five minutes' },
+ { label: 'Multi-agent', them: 'First-class: hierarchical or sequential process types', us: 'Subagent middleware — spawn child agents, await results, compose freely' },
+ { label: 'Async', them: 'Synchronous by default; async support added later', us: 'Async-first — every entry point is async' },
+ { label: 'Streaming', them: 'Limited streaming support', us: 'async for event in stream — one pattern, eleven event types' },
+ { label: 'Checkpointing', them: 'No built-in persistence layer', us: 'Append-only — O(1) DB I/O; backends: memory, SQLite, Postgres, MySQL' },
+ { label: 'Dependencies', them: 'langchain-core + many transitive deps', us: '3 core deps: pydantic, anthropic, openai' },
+ { label: 'Tools', them: 'Tool classes with schema boilerplate', us: 'Decorate any async function with @tool — schema auto-derived' },
+ { label: 'Observability', them: 'Basic logging; no native OTel', us: 'Native OpenTelemetry — GenAI semconv, OTLP / JSONL exporters' },
+ { label: 'Testing', them: 'Requires live API calls for most tests', us: 'FauxProvider — deterministic streaming, no API keys needed' },
+ ],
+ code: {
+ h2: 'A tool-using agent',
+ themTitle: '# CrewAI',
+ them: `from crewai import Agent, Task, Crew, Process
+from crewai.tools import BaseTool
+from pydantic import BaseModel
+
+class WeatherInput(BaseModel):
+ city: str
+
+class WeatherTool(BaseTool):
+ name: str = "get_weather"
+ description: str = "Get current weather for a city."
+ args_schema: type[BaseModel] = WeatherInput
+
+ def _run(self, city: str) -> str:
+ return f"72F and sunny in {city}"
+
+weather_tool = WeatherTool()
+
+agent = Agent(
+ role="Weather Assistant",
+ goal="Answer weather questions accurately.",
+ backstory="You are a helpful weather assistant.",
+ tools=[weather_tool],
+ llm="claude-sonnet-4-6",
+)
+
+task = Task(
+ description="What's the weather in {city}?",
+ expected_output="A weather report for the city.",
+ agent=agent,
+)
+
+crew = Crew(agents=[agent], tasks=[task], process=Process.sequential)
+result = crew.kickoff(inputs={"city": "Tokyo"})
+`,
+ usTitle: '# CubePi',
+ us: `from cubepi import Agent, tool
+from cubepi.providers.anthropic import AnthropicProvider
+
+
+@tool
+async def get_weather(city: str) -> str:
+ "Get current weather for a city."
+ return f"72F and sunny in {city}"
+
+
+provider = AnthropicProvider(provider_id="anthropic", api_key="...")
+agent = Agent(
+ model=provider.model("claude-sonnet-4-6"),
+ tools=[get_weather],
+ system_prompt="You are a helpful weather assistant.",
+)
+await agent.prompt("What's the weather in Tokyo?")
+`,
+ },
+ sections: [
+ {
+ h2: 'Roles, goals, and backstories — or just a system prompt',
+ body: [
+ 'CrewAI\'s "role", "goal", and "backstory" fields are a structured way to write a system prompt. When you have one agent doing one job, the role metaphor adds ceremony without adding capability. In CubePi, `system_prompt` is a string you own completely — no framework vocabulary to learn, no structure to maintain.',
+ 'For genuine multi-agent scenarios, CubePi provides a `SubagentsMiddleware` that spawns child agents and wires their results back to the parent — without the crew/process/task object model.',
+ ],
+ },
+ {
+ h2: 'Persistence that does not require you to wire it yourself',
+ body: [
+ 'CrewAI does not ship a built-in checkpointing layer. If you want conversations to survive restarts you add your own database logic. CubePi\'s append-only checkpointing ships out of the box — `SQLiteCheckpointer`, `PostgresCheckpointer`, and `MySQLCheckpointer` each write only the new messages from each turn, so write cost stays O(1) regardless of how long the thread grows.',
+ ],
+ },
+ {
+ h2: 'When CrewAI is the better fit',
+ body: [
+ 'CrewAI is a reasonable choice if your workflow maps naturally onto the crew metaphor — a team of specialist agents each assigned a discrete task in a pipeline. If you are building a single conversational agent, a stateful assistant, or anything that needs production-grade persistence or OTel observability, CubePi is the leaner path.',
+ ],
+ },
+ ],
+ cta: [
+ { text: 'Quick Start →', href: '/docs/getting-started/quick-start' },
+ { text: 'Core Concepts →', href: '/docs/getting-started/core-concepts' },
+ ],
+};
+
+const ZH: CompareContent = {
+ them: 'CrewAI',
+ title: 'CubePi vs CrewAI — 更精简的 Python Agent 框架',
+ description:
+ 'CubePi 与 CrewAI 对比:CrewAI 将 Agent 建模为具有角色和背景故事的"角色扮演"团队成员。CubePi 将 Agent 建模为普通的异步 while 循环,具备类型化中间件、追加式 checkpointing 和 3 个核心依赖。',
+ keywords:
+ 'CubePi vs CrewAI, CrewAI 替代品, Python Agent 框架, 异步 Agent 框架, CrewAI vs CubePi, 多 Agent 框架, crewai 替代品',
+ h1: 'CubePi vs CrewAI',
+ intro: [
+ 'CrewAI 围绕角色扮演的隐喻组织 Agent 系统 —— 团队(crew)、带有角色和背景故事的 Agent,以及分配给 Agent 的任务。CubePi 从不同的前提出发:Agent 是一个普通的异步 while 循环,调用模型、执行工具、循环往复。',
+ '如果角色抽象并不能解决你的问题,CubePi 直接省去这一层。以下是两者的详细对比。',
+ ],
+ tableHeading: '并排对比',
+ rows: [
+ { label: '抽象层', them: '具有角色、目标和背景故事的角色扮演 Agent 团队', us: '普通的异步 while 循环 —— 五分钟内可从头读完' },
+ { label: '多 Agent', them: '一等公民:层次化或顺序化进程类型', us: 'Subagent 中间件 —— 派生子 Agent,等待结果,自由组合' },
+ { label: '异步支持', them: '默认同步;异步支持后来追加', us: '异步优先 —— 每个入口都是 async' },
+ { label: '流式输出', them: '流式支持有限', us: 'async for event in stream —— 统一模式,11 种事件类型' },
+ { label: 'Checkpointing', them: '无内置持久化层', us: '追加式 —— O(1) DB I/O;后端:memory、SQLite、Postgres、MySQL' },
+ { label: '依赖', them: 'langchain-core + 大量传递依赖', us: '3 个核心依赖:pydantic、anthropic、openai' },
+ { label: '工具', them: '需要编写 schema 样板代码的工具类', us: '用 @tool 装饰任意 async 函数 —— schema 自动推导' },
+ { label: '可观测性', them: '基础日志;无原生 OTel', us: '原生 OpenTelemetry —— GenAI 语义约定,OTLP / JSONL 导出器' },
+ { label: '测试', them: '大多数测试需要真实 API 调用', us: 'FauxProvider —— 确定性流式仿真,无需 API Key' },
+ ],
+ sections: [
+ {
+ h2: '角色、目标、背景故事 —— 还是直接写 system prompt',
+ body: [
+ 'CrewAI 的"角色"、"目标"和"背景故事"字段本质上是一种结构化写 system prompt 的方式。当你只有一个 Agent 做一件事时,角色隐喻增加的是仪式感而非能力。在 CubePi 中,`system_prompt` 就是你完全掌控的一个字符串 —— 没有框架词汇要学,没有结构要维护。',
+ '对于真正的多 Agent 场景,CubePi 提供 `SubagentsMiddleware`,可以派生子 Agent 并将其结果回传给父 Agent —— 无需 crew/process/task 对象模型。',
+ ],
+ },
+ {
+ h2: '开箱即用的持久化,无需自己接线',
+ body: [
+ 'CrewAI 没有内置的 checkpointing 层。如果你希望对话在重启后依然存在,需要自己添加数据库逻辑。CubePi 的追加式 checkpointing 开箱即用 —— `SQLiteCheckpointer`、`PostgresCheckpointer` 和 `MySQLCheckpointer` 每轮只写入新消息,无论对话多长,写入成本保持 O(1)。',
+ ],
+ },
+ {
+ h2: 'CrewAI 更适合的场景',
+ body: [
+ '如果你的工作流自然地映射到 crew 的隐喻 —— 一组专家 Agent 各自负责流水线中的一个离散任务 —— CrewAI 是合理的选择。如果你在构建单一的对话 Agent、有状态的助手,或任何需要生产级持久化或 OTel 可观测性的系统,CubePi 是更精简的路径。',
+ ],
+ },
+ ],
+ cta: [
+ { text: '快速开始 →', href: '/docs/getting-started/quick-start' },
+ { text: '核心概念 →', href: '/docs/getting-started/core-concepts' },
+ ],
+};
+
+export default function CompareCrewAI(): React.ReactElement {
+ const zh = useIsZhHans();
+ return <ComparePage content={zh ? ZH : EN} />;
+}
diff --git a/website/src/pages/compare/pydantic-ai.tsx b/website/src/pages/compare/pydantic-ai.tsx
new file mode 100644
index 0000000..9dfd795
--- /dev/null
+++ b/website/src/pages/compare/pydantic-ai.tsx
@@ -0,0 +1,168 @@
+import React from 'react';
+import ComparePage, { type CompareContent } from '@site/src/components/Compare/ComparePage';
+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';
+
+const EN: CompareContent = {
+ them: 'PydanticAI',
+ title: 'CubePi vs PydanticAI — Python agent frameworks compared',
+ description:
+ 'CubePi vs PydanticAI: both are async-first Python agent frameworks built on Pydantic. PydanticAI centres on dependency injection and structured output. CubePi centres on append-only checkpointing, composable middleware, and vendor-neutral OpenTelemetry observability.',
+ keywords:
+ 'CubePi vs PydanticAI, PydanticAI alternative, pydantic-ai alternative, Python agent framework, async agent framework, PydanticAI vs CubePi, pydantic ai 替代品',
+ h1: 'CubePi vs PydanticAI',
+ intro: [
+ 'PydanticAI and CubePi share the same foundation — Pydantic v2, asyncio-native design, and a belief that agents should be plain Python rather than graph-based state machines. Where they diverge is in the abstractions built on top.',
+ 'PydanticAI centres on type-safe structured output and dependency injection via `RunContext`. CubePi centres on persistent multi-turn conversations, composable middleware hooks, and vendor-neutral OpenTelemetry tracing. Here is how the two compare.',
+ ],
+ tableHeading: 'Side-by-side',
+ rows: [
+ { label: 'Core abstraction', them: 'Typed Agent[OutputType] with dependency injection', us: 'Stateful Agent with a while-loop core — composable via middleware' },
+ { label: 'Structured output', them: 'First-class — result_type enforces Pydantic model output', us: 'Via tool return types; use a "final answer" tool for structured output' },
+ { label: 'Dependency injection', them: 'RunContext[Deps] — deps injected at run time', us: 'Pass context through tool closures or middleware; no DI container' },
+ { label: 'Checkpointing', them: 'No built-in persistence layer', us: 'Append-only — O(1) DB I/O; backends: memory, SQLite, Postgres, MySQL' },
+ { label: 'Streaming', them: 'async for chunk in agent.run_stream()', us: 'async for event in stream — 11 typed event types including tool lifecycle' },
+ { label: 'Multi-provider', them: 'Anthropic, OpenAI, Gemini, Groq, and more', us: 'Anthropic & OpenAI built in; Provider protocol for custom backends' },
+ { label: 'Provider fallback', them: 'Not built in', us: 'FallbackBoundModel — auto-failover on rate-limit or outage' },
+ { label: 'Observability', them: 'Logfire (Pydantic\'s own platform)', us: 'Native OpenTelemetry — GenAI semconv, OTLP / JSONL; vendor-neutral' },
+ { label: 'Middleware', them: 'No middleware system', us: '8 typed hooks with declarative composition rules' },
+ { label: 'Testing', them: 'TestModel for deterministic tests', us: 'FauxProvider — realistic streaming deltas, no API keys needed' },
+ { label: 'Core deps', them: 'pydantic-ai-slim + provider adapters', us: 'pydantic, anthropic, openai — everything else is an optional extra' },
+ ],
+ code: {
+ h2: 'A tool-using agent',
+ themTitle: '# PydanticAI',
+ them: `from pydantic_ai import Agent
+from pydantic_ai.models.anthropic import AnthropicModel
+
+
+model = AnthropicModel("claude-sonnet-4-6")
+agent = Agent(model, system_prompt="You are a helpful weather assistant.")
+
+
+async def get_weather(city: str) -> str:
+ """Get current weather for a city."""
+ return f"72F and sunny in {city}"
+
+
+result = await agent.run("What's the weather in Tokyo?")
+print(result.output)
+`,
+ usTitle: '# CubePi',
+ us: `from cubepi import Agent, tool
+from cubepi.providers.anthropic import AnthropicProvider
+
+
+@tool
+async def get_weather(city: str) -> str:
+ "Get current weather for a city."
+ return f"72F and sunny in {city}"
+
+
+provider = AnthropicProvider(provider_id="anthropic", api_key="...")
+agent = Agent(
+ model=provider.model("claude-sonnet-4-6"),
+ tools=[get_weather],
+ system_prompt="You are a helpful weather assistant.",
+)
+await agent.prompt("What's the weather in Tokyo?")
+`,
+ },
+ sections: [
+ {
+ h2: 'Structured output vs persistent conversation',
+ body: [
+ 'PydanticAI\'s standout feature is `result_type`: you declare the Pydantic model you want back and the framework forces the model to return it. This is excellent for batch extraction pipelines and single-turn tasks where the output shape matters more than the conversation.',
+ 'CubePi optimises for the other axis — multi-turn conversations that survive restarts. Append-only checkpointing means a thread\'s write cost does not grow with conversation length, which matters when you have thousands of concurrent long-lived sessions. For structured output in CubePi, define a tool whose return value IS the structured result and instruct the model to call it when done.',
+ ],
+ },
+ {
+ h2: 'Dependency injection vs middleware',
+ body: [
+ 'PydanticAI\'s `RunContext[Deps]` is a clean pattern for injecting services (databases, HTTP clients) into tool functions. CubePi achieves the same via closures — capture your dependencies when you define the tool function — which requires no new abstraction to learn.',
+ 'Where CubePi adds structure is in cross-cutting concerns: middleware hooks (`before_tool_call`, `transform_context`, `should_stop_after_turn`, etc.) let you add rate-limiting, safety checks, compaction, or subagent orchestration without touching the core agent loop.',
+ ],
+ },
+ {
+ h2: 'Observability: Logfire vs vendor-neutral OTel',
+ body: [
+ 'PydanticAI integrates with Logfire, Pydantic\'s own observability platform. It works well if Logfire fits your stack. CubePi emits standard OpenTelemetry spans with GenAI semantic-convention attributes that land in any OTLP-compatible backend — Jaeger, Grafana Tempo, Honeycomb, Datadog, AWS X-Ray — with no vendor dependency. The `cubepi trace` CLI also lets you inspect traces locally from JSONL files without a backend at all.',
+ ],
+ },
+ {
+ h2: 'When PydanticAI is the better fit',
+ body: [
+ 'PydanticAI is the stronger choice for single-turn structured extraction pipelines where you need guaranteed output schemas, or if you are already using Logfire and want tight integration. Choose CubePi when you need production-grade multi-turn persistence, composable middleware, provider failover, or vendor-neutral observability.',
+ ],
+ },
+ ],
+ cta: [
+ { text: 'Quick Start →', href: '/docs/getting-started/quick-start' },
+ { text: 'Core Concepts →', href: '/docs/getting-started/core-concepts' },
+ ],
+};
+
+const ZH: CompareContent = {
+ them: 'PydanticAI',
+ title: 'CubePi vs PydanticAI — Python Agent 框架对比',
+ description:
+ 'CubePi 与 PydanticAI 对比:两者都是基于 Pydantic 的异步优先 Python Agent 框架。PydanticAI 聚焦于依赖注入和结构化输出;CubePi 聚焦于追加式 checkpointing、可组合中间件和厂商中立的 OpenTelemetry 可观测性。',
+ keywords:
+ 'CubePi vs PydanticAI, PydanticAI 替代品, pydantic-ai 替代品, Python Agent 框架, 异步 Agent 框架, pydantic ai 替代品',
+ h1: 'CubePi vs PydanticAI',
+ intro: [
+ 'PydanticAI 和 CubePi 共享同一基础 —— Pydantic v2、asyncio 原生设计,以及"Agent 应该是普通 Python 而非基于图的状态机"的理念。两者的分歧在于在此之上构建的抽象。',
+ 'PydanticAI 聚焦于通过 `RunContext` 实现类型安全的结构化输出和依赖注入。CubePi 聚焦于持久化多轮对话、可组合的中间件钩子和厂商中立的 OpenTelemetry 追踪。以下是两者的详细对比。',
+ ],
+ tableHeading: '并排对比',
+ rows: [
+ { label: '核心抽象', them: '带依赖注入的类型化 Agent[OutputType]', us: '有状态 Agent,核心为 while 循环 —— 通过中间件可组合' },
+ { label: '结构化输出', them: '一等公民 —— result_type 强制 Pydantic 模型输出', us: '通过工具返回类型;用"最终答案"工具实现结构化输出' },
+ { label: '依赖注入', them: 'RunContext[Deps] —— 运行时注入依赖', us: '通过工具闭包或中间件传递上下文;无 DI 容器' },
+ { label: 'Checkpointing', them: '无内置持久化层', us: '追加式 —— O(1) DB I/O;后端:memory、SQLite、Postgres、MySQL' },
+ { label: '流式输出', them: 'async for chunk in agent.run_stream()', us: 'async for event in stream —— 11 种类型化事件,含工具生命周期' },
+ { label: '多 Provider', them: 'Anthropic、OpenAI、Gemini、Groq 等', us: '内置 Anthropic 和 OpenAI;Provider 协议支持自定义后端' },
+ { label: 'Provider 故障转移', them: '无内置支持', us: 'FallbackBoundModel —— 限速或故障时自动切换' },
+ { label: '可观测性', them: 'Logfire(Pydantic 自有平台)', us: '原生 OpenTelemetry —— GenAI 语义约定,OTLP / JSONL;厂商中立' },
+ { label: '中间件', them: '无中间件系统', us: '8 个类型化钩子,带声明式组合规则' },
+ { label: '测试', them: 'TestModel 用于确定性测试', us: 'FauxProvider —— 真实流式仿真,无需 API Key' },
+ { label: '核心依赖', them: 'pydantic-ai-slim + provider 适配器', us: 'pydantic、anthropic、openai —— 其余皆为可选 extra' },
+ ],
+ sections: [
+ {
+ h2: '结构化输出 vs 持久化对话',
+ body: [
+ 'PydanticAI 的核心亮点是 `result_type`:你声明想要返回的 Pydantic 模型,框架强制模型输出它。对于输出格式比对话更重要的批量提取流水线和单轮任务,这非常出色。',
+ 'CubePi 在另一个轴上优化 —— 能在重启后存活的多轮对话。追加式 checkpointing 意味着线程的写入成本不会随对话长度增长,当你有数千个并发长存会话时,这一点至关重要。在 CubePi 中实现结构化输出,可以定义一个返回值即为结构化结果的工具,并指示模型在完成时调用它。',
+ ],
+ },
+ {
+ h2: '依赖注入 vs 中间件',
+ body: [
+ 'PydanticAI 的 `RunContext[Deps]` 是将服务(数据库、HTTP 客户端)注入工具函数的简洁模式。CubePi 通过闭包实现同样效果 —— 在定义工具函数时捕获依赖 —— 无需学习新抽象。',
+ 'CubePi 在横切关注点上增加了结构:中间件钩子(`before_tool_call`、`transform_context`、`should_stop_after_turn` 等)让你在不触碰核心 agent 循环的情况下添加限速、安全检查、上下文压缩或子 Agent 编排。',
+ ],
+ },
+ {
+ h2: '可观测性:Logfire vs 厂商中立的 OTel',
+ body: [
+ 'PydanticAI 与 Logfire(Pydantic 自有的可观测性平台)集成。如果 Logfire 适合你的技术栈,效果很好。CubePi 输出带有 GenAI 语义约定属性的标准 OpenTelemetry span,可以落入任何 OTLP 兼容后端 —— Jaeger、Grafana Tempo、Honeycomb、Datadog、AWS X-Ray —— 无厂商依赖。`cubepi trace` CLI 也可以让你在没有后端的情况下从 JSONL 文件本地检查追踪。',
+ ],
+ },
+ {
+ h2: 'PydanticAI 更适合的场景',
+ body: [
+ '如果你需要保证输出 schema 的单轮结构化提取流水线,或者你已经在使用 Logfire 并希望紧密集成,PydanticAI 是更强的选择。当你需要生产级多轮持久化、可组合中间件、Provider 故障转移或厂商中立可观测性时,选择 CubePi。',
+ ],
+ },
+ ],
+ cta: [
+ { text: '快速开始 →', href: '/docs/getting-started/quick-start' },
+ { text: '核心概念 →', href: '/docs/getting-started/core-concepts' },
+ ],
+};
+
+export default function ComparePydanticAI(): React.ReactElement {
+ const zh = useIsZhHans();
+ return <ComparePage content={zh ? ZH : EN} />;
+}
diff --git a/website/src/pages/faq.tsx b/website/src/pages/faq.tsx
new file mode 100644
index 0000000..5d1c368
--- /dev/null
+++ b/website/src/pages/faq.tsx
@@ -0,0 +1,427 @@
+import React from 'react';
+import Head from '@docusaurus/Head';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';
+
+interface FaqItem {
+ q: string;
+ a: React.ReactNode;
+}
+
+const EN_ITEMS: FaqItem[] = [
+ {
+ q: 'What is CubePi?',
+ a: (
+ <>
+ 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 <code>FauxProvider</code> for
+ deterministic tests.
+ </>
+ ),
+ },
+ {
+ q: 'How is CubePi different from LangGraph?',
+ a: (
+ <>
+ 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 <code>async while</code> loop. There is no <code>StateGraph</code>,
+ no <code>add_edge</code>, no <code>ToolNode</code>, and no <code>TypedDict</code> 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 <Link to="/compare/langgraph">LangGraph comparison</Link>.
+ </>
+ ),
+ },
+ {
+ q: 'How is CubePi different from CrewAI?',
+ a: (
+ <>
+ 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 <Link to="/compare/crewai">CrewAI comparison</Link>.
+ </>
+ ),
+ },
+ {
+ q: 'How is CubePi different from PydanticAI?',
+ a: (
+ <>
+ Both frameworks are async-first and built on Pydantic. PydanticAI focuses on structured output and
+ dependency injection via <code>RunContext</code>; 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 <Link to="/compare/pydantic-ai">PydanticAI comparison</Link>.
+ </>
+ ),
+ },
+ {
+ q: 'Does CubePi support multiple LLM providers?',
+ a: (
+ <>
+ Yes. CubePi ships <code>AnthropicProvider</code> and <code>OpenAIProvider</code> (plus{' '}
+ <code>OpenAIResponsesProvider</code> for the Responses API) out of the box. You can add your own
+ provider with a single class that implements the <code>Provider</code> protocol. Use{' '}
+ <code>FallbackBoundModel</code> to chain providers — on a rate-limit or outage the next model in the
+ chain is tried automatically.
+ </>
+ ),
+ },
+ {
+ q: 'What databases does CubePi support for checkpointing?',
+ a: (
+ <>
+ CubePi ships four checkpointer backends: <code>MemoryCheckpointer</code> (development/testing),{' '}
+ <code>SQLiteCheckpointer</code> (lightweight single-node), <code>PostgresCheckpointer</code>{' '}
+ (production), and <code>MySQLCheckpointer</code> (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.
+ </>
+ ),
+ },
+ {
+ q: 'What is append-only checkpointing and why does it matter?',
+ a: (
+ <>
+ 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.
+ </>
+ ),
+ },
+ {
+ q: 'Does CubePi support MCP (Model Context Protocol)?',
+ a: (
+ <>
+ Yes. Install <code>pip install cubepi[mcp]</code> and use <code>StdioMCPLoader</code> or{' '}
+ <code>HttpMCPLoader</code> to load tools from any MCP-compatible server. Loaded tools plug into
+ the same <code>AgentTool</code> interface as hand-written tools.
+ </>
+ ),
+ },
+ {
+ q: 'How does CubePi handle observability?',
+ a: (
+ <>
+ CubePi includes a <code>Tracer</code> and <code>Meter</code> 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 <code>cubepi trace</code> CLI lets you inspect JSONL traces in the
+ terminal without a backend. Install with <code>pip install cubepi[tracing,trace-cli]</code>.
+ </>
+ ),
+ },
+ {
+ q: 'How do I test agents without hitting real APIs?',
+ a: (
+ <>
+ Use <code>FauxProvider</code>. It emits realistic streaming deltas (<code>content_block_start</code>,{' '}
+ <code>text_delta</code>, etc.) without making any API calls. You script the responses with{' '}
+ <code>provider.set_responses([...])</code> using helpers like <code>faux_text()</code> and{' '}
+ <code>faux_tool_call()</code>. Tests run fully deterministically with no API keys.
+ </>
+ ),
+ },
+ {
+ q: 'What Python versions does CubePi support?',
+ a: 'CubePi supports Python 3.11, 3.12, 3.13, and 3.14. CI runs on all four versions.',
+ },
+ {
+ q: 'Is CubePi production-ready?',
+ a: (
+ <>
+ 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{' '}
+ <Link to="/changelog">changelog</Link>. The Postgres and MySQL checkpointers are used in
+ production by early adopters.
+ </>
+ ),
+ },
+ {
+ q: 'How do I install CubePi?',
+ a: (
+ <>
+ <code>pip install cubepi</code> for the core. Add extras for optional features:{' '}
+ <code>pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]</code>.
+ With uv: <code>uv add cubepi</code> or <code>uv add cubepi[sqlite,postgres,mcp,tracing]</code>.
+ </>
+ ),
+ },
+ {
+ q: 'Is CubePi cache-friendly?',
+ a: (
+ <>
+ 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:
+ <br /><br />
+ <strong>Append-only message storage.</strong> 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.
+ <br /><br />
+ <strong>Automatic cache breakpoints (Anthropic).</strong> <code>AnthropicProvider</code> 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{' '}
+ <Link to="/docs/guides/agents/prompt-caching">Prompt Caching guide</Link> for details on how to
+ avoid breaking these breakpoints and how to read cache hit metrics from <code>Usage</code>.
+ </>
+ ),
+ },
+ {
+ q: 'Is CubePi open source?',
+ a: (
+ <>
+ Yes. CubePi is MIT licensed. Source code is on{' '}
+ <a href="https://github.com/cubeplexai/cubepi" target="_blank" rel="noopener noreferrer">GitHub</a>.
+ </>
+ ),
+ },
+];
+
+const ZH_ITEMS: FaqItem[] = [
+ {
+ q: 'CubePi 是什么?',
+ a: (
+ <>
+ CubePi 是一个 Pythonic、异步原生的 Agent 框架,用于在 Python 中构建 LLM 驱动的 Agent。
+ 它将 Agent 建模为普通的异步 while 循环 —— 无状态图,无需连接节点/边 —— 核心算法五分钟内可读懂。
+ 它内置追加式 checkpointing、可组合中间件、原生 OpenTelemetry 追踪、MCP 支持,以及用于确定性测试的 <code>FauxProvider</code>。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 与 LangGraph 有何不同?',
+ a: (
+ <>
+ LangGraph 将 Agent 建模为需要手动连接节点、边和类型化通道的状态图。CubePi 将同样的 Agent 建模为普通的 <code>async while</code> 循环。
+ 没有 <code>StateGraph</code>,没有 <code>add_edge</code>,没有 <code>ToolNode</code>,也没有需要维护的 <code>TypedDict</code>。
+ CubePi 还采用追加式 checkpointing(每轮 O(1) vs. 每步全量快照),且只有三个核心依赖。
+ 查看完整的 <Link to="/compare/langgraph">LangGraph 对比</Link>。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 与 CrewAI 有何不同?',
+ a: (
+ <>
+ CrewAI 围绕角色扮演的隐喻组织 Agent —— 团队、角色、目标和背景故事。CubePi 省去了这层隐喻:Agent 就是一个带有 system prompt 的函数。
+ CubePi 还内置了追加式 checkpointing(CrewAI 没有),异步优先,并具有原生 OpenTelemetry。
+ 查看完整的 <Link to="/compare/crewai">CrewAI 对比</Link>。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 与 PydanticAI 有何不同?',
+ a: (
+ <>
+ 两者都是异步优先且基于 Pydantic 的框架。PydanticAI 聚焦于结构化输出和通过 <code>RunContext</code> 实现的依赖注入;
+ CubePi 聚焦于持久化多轮对话、可组合的中间件钩子、Provider 故障转移,以及厂商中立的 OpenTelemetry(而非 Logfire)。
+ CubePi 还内置了 PydanticAI 所缺乏的 checkpointing。
+ 查看完整的 <Link to="/compare/pydantic-ai">PydanticAI 对比</Link>。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 支持多个 LLM Provider 吗?',
+ a: (
+ <>
+ 支持。CubePi 内置 <code>AnthropicProvider</code> 和 <code>OpenAIProvider</code>(以及用于 Responses API 的{' '}
+ <code>OpenAIResponsesProvider</code>)。你可以用一个实现 <code>Provider</code> 协议的类添加自定义 Provider。
+ 使用 <code>FallbackBoundModel</code> 链式连接 Provider —— 在限速或故障时自动切换到链中的下一个模型。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 的 checkpointing 支持哪些数据库?',
+ a: (
+ <>
+ CubePi 提供四种 checkpointer 后端:<code>MemoryCheckpointer</code>(开发/测试)、
+ <code>SQLiteCheckpointer</code>(轻量级单节点)、<code>PostgresCheckpointer</code>(生产环境)
+ 和 <code>MySQLCheckpointer</code>(生产环境)。所有后端均使用追加式写入 —— 每轮只写入新消息,
+ 无论对话多长,写入成本保持 O(1)。
+ </>
+ ),
+ },
+ {
+ q: '什么是追加式 checkpointing,为什么重要?',
+ a: (
+ <>
+ 大多数 Agent 框架通过每步快照整个消息列表来进行 checkpoint。随着对话增长,写入成本线性增长。
+ CubePi 只写入每轮产生的新消息 —— 无论线程多长,都是 O(1)。这在规模化时至关重要:数千个并发的长存会话,频繁轮次。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 支持 MCP(模型上下文协议)吗?',
+ a: (
+ <>
+ 支持。安装 <code>pip install cubepi[mcp]</code>,使用 <code>StdioMCPLoader</code> 或{' '}
+ <code>HttpMCPLoader</code> 从任何兼容 MCP 的服务器加载工具。加载的工具与手写工具使用相同的 <code>AgentTool</code> 接口。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 如何处理可观测性?',
+ a: (
+ <>
+ CubePi 内置 <code>Tracer</code> 和 <code>Meter</code>,输出符合 GenAI 语义约定的 OpenTelemetry span 和指标。
+ Span 通过 OTLP/HTTP 导出到任何兼容后端(Jaeger、Grafana Tempo、Honeycomb、Datadog、AWS X-Ray、Langfuse……)
+ 或本地 JSONL 文件。<code>cubepi trace</code> CLI 可在终端中无需后端直接检查 JSONL trace。
+ 安装:<code>pip install cubepi[tracing,trace-cli]</code>。
+ </>
+ ),
+ },
+ {
+ q: '如何在不调用真实 API 的情况下测试 Agent?',
+ a: (
+ <>
+ 使用 <code>FauxProvider</code>。它在不发起任何 API 调用的情况下产生真实的流式 delta(<code>content_block_start</code>、
+ <code>text_delta</code> 等)。通过 <code>provider.set_responses([...])</code> 配合 <code>faux_text()</code> 和{' '}
+ <code>faux_tool_call()</code> 等辅助函数编写响应脚本。测试完全确定性,无需 API Key。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 支持哪些 Python 版本?',
+ a: 'CubePi 支持 Python 3.11、3.12、3.13 和 3.14。CI 在所有四个版本上运行。',
+ },
+ {
+ q: 'CubePi 是否可用于生产环境?',
+ a: (
+ <>
+ CubePi 处于 Beta 阶段(v0.9)。核心 agent 循环、checkpointing、中间件和追踪 API 均已稳定。
+ 重大变更遵循语义化版本管理,并记录在 <Link to="/changelog">更新日志</Link> 中。
+ Postgres 和 MySQL checkpointer 已被早期用户用于生产环境。
+ </>
+ ),
+ },
+ {
+ q: '如何安装 CubePi?',
+ a: (
+ <>
+ 核心安装:<code>pip install cubepi</code>。通过 extras 添加可选功能:
+ <code>pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]</code>。
+ 使用 uv:<code>uv add cubepi</code> 或 <code>uv add cubepi[sqlite,postgres,mcp,tracing]</code>。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 对缓存友好吗?',
+ a: (
+ <>
+ 是的 —— CubePi 的设计目标之一就是最大化 prompt 缓存命中率。LLM 提供商(Anthropic、OpenAI)允许你缓存请求的稳定前缀,
+ 这样相同的 token 不需要在每轮都重新处理,可降低最高 90% 的费用并减少延迟。CubePi 有两个设计决策共同保障了这一点:
+ <br /><br />
+ <strong>追加式消息存储。</strong>CubePi 从不重写或重排历史消息 —— 只追加新消息。这意味着每次请求的前缀与上一轮完全相同,
+ 正是缓存命中所需要的。那些每步都从快照重建完整消息列表的框架,一旦序列化细节有任何变化,就会悄悄破坏缓存。
+ <br /><br />
+ <strong>自动缓存断点(Anthropic)。</strong><code>AnthropicProvider</code> 默认标记三个缓存断点:system prompt、
+ 最后一个工具定义,以及历史中的最后一条消息。最后一条消息的断点每轮向前推进,让之前的历史保持热缓存。
+ 查看 <Link to="/docs/guides/agents/prompt-caching">Prompt Caching 指南</Link> 了解如何避免破坏这些断点,
+ 以及如何从 <code>Usage</code> 中读取缓存命中指标。
+ </>
+ ),
+ },
+ {
+ q: 'CubePi 是开源的吗?',
+ a: (
+ <>
+ 是的。CubePi 采用 MIT 许可证。源代码托管在{' '}
+ <a href="https://github.com/cubeplexai/cubepi" target="_blank" rel="noopener noreferrer">GitHub</a> 上。
+ </>
+ ),
+ },
+];
+
+function FaqSection({ items }: { items: FaqItem[] }) {
+ return (
+ <div style={{ maxWidth: 860, margin: '0 auto', padding: '2rem 1.5rem 4rem' }}>
+ {items.map((item, i) => (
+ <details
+ key={i}
+ style={{
+ borderBottom: '1px solid var(--ifm-color-emphasis-200)',
+ padding: '1rem 0',
+ }}
+ >
+ <summary
+ style={{
+ fontWeight: 600,
+ fontSize: '1.05rem',
+ cursor: 'pointer',
+ listStyle: 'none',
+ display: 'flex',
+ justifyContent: 'space-between',
+ alignItems: 'center',
+ gap: '1rem',
+ }}
+ >
+ {item.q}
+ <span style={{ fontSize: '1.2rem', flexShrink: 0 }}>+</span>
+ </summary>
+ <p style={{ marginTop: '0.75rem', marginBottom: 0, lineHeight: 1.7, color: 'var(--ifm-color-content-secondary)' }}>
+ {item.a}
+ </p>
+ </details>
+ ))}
+ </div>
+ );
+}
+
+export default function FAQ(): React.ReactElement {
+ const zh = useIsZhHans();
+
+ const title = zh ? 'CubePi 常见问题' : 'Frequently Asked Questions — CubePi';
+ const description = zh
+ ? 'CubePi 常见问题:与 LangGraph、CrewAI、PydanticAI 的区别,checkpointing、MCP、OpenTelemetry 支持,安装方式,以及生产可用性。'
+ : 'Answers to common questions about CubePi — how it compares to LangGraph, CrewAI, and PydanticAI; checkpointing, MCP, OpenTelemetry, installation, and production readiness.';
+
+ const faqJsonLd = {
+ '@context': 'https://schema.org',
+ '@type': 'FAQPage',
+ mainEntity: (zh ? ZH_ITEMS : EN_ITEMS).map((item) => ({
+ '@type': 'Question',
+ name: item.q,
+ acceptedAnswer: {
+ '@type': 'Answer',
+ // Strip JSX to plain text for structured data — good enough for schema.org
+ text: typeof item.a === 'string' ? item.a : String(item.q),
+ },
+ })),
+ };
+
+ return (
+ <Layout title={title} description={description}>
+ <Head>
+ <meta
+ name="keywords"
+ content="CubePi FAQ, CubePi vs LangGraph, CubePi vs CrewAI, CubePi vs PydanticAI, Python agent framework FAQ, async agent FAQ"
+ />
+ <script type="application/ld+json">{JSON.stringify(faqJsonLd)}</script>
+ </Head>
+ <main>
+ <div
+ style={{
+ textAlign: 'center',
+ padding: '3rem 1.5rem 1.5rem',
+ maxWidth: 860,
+ margin: '0 auto',
+ }}
+ >
+ <h1>{zh ? '常见问题' : 'Frequently Asked Questions'}</h1>
+ <p style={{ fontSize: '1.1rem', color: 'var(--ifm-color-content-secondary)' }}>
+ {zh
+ ? '关于 CubePi 的常见问题解答'
+ : 'Common questions about CubePi, how it compares to alternatives, and how to get started.'}
+ </p>
+ </div>
+ <FaqSection items={zh ? ZH_ITEMS : EN_ITEMS} />
+ </main>
+ </Layout>
+ );
+}
diff --git a/website/static/llms.txt b/website/static/llms.txt
new file mode 100644
index 0000000..ed31b1d
--- /dev/null
+++ b/website/static/llms.txt
@@ -0,0 +1,79 @@
+# CubePi
+
+> CubePi is a Pythonic, async-native agent framework for building LLM-powered agents in Python. It is a leaner alternative to LangGraph, CrewAI, and PydanticAI.
+
+CubePi models an agent as a plain async while-loop — no state graphs, no nodes/edges, no channel wiring. The core loop (`run_agent_loop`) is a readable while-loop you can trace top to bottom in five minutes. This makes CubePi easier to debug, test, and extend than graph-based runtimes.
+
+## Key features
+
+- **Async-first**: every entry point is `async`; no split `invoke`/`ainvoke` surface
+- **Minimal dependencies**: only `anthropic`, `openai`, and `pydantic` as core deps
+- **Multi-provider**: native `Provider` protocol with Anthropic, OpenAI, and OpenAI Responses built in; bring your own with one class
+- **Provider fallback**: `FallbackBoundModel` chains providers — on rate-limit or outage the next model is tried automatically
+- **Append-only checkpointing**: O(1) DB writes per turn regardless of conversation length; backends: in-memory, SQLite, PostgreSQL, MySQL
+- **Tools**: decorate any async function with `@tool`; framework handles schema generation, parallel execution, and error wrapping
+- **Middleware**: 8 typed hooks (`transform_context`, `before_tool_call`, `after_tool_call`, etc.) with declarative composition rules
+- **MCP support**: load tools from any MCP server over stdio or HTTP
+- **Human-in-the-loop (HITL)**: `ask_user` channel for mid-run approvals and interrupts
+- **OpenTelemetry tracing**: GenAI semantic conventions, OTLP/JSONL exporters, `cubepi trace` terminal viewer
+- **FauxProvider**: deterministic test provider — no API calls, realistic streaming deltas
+
+## Install
+
+```
+pip install cubepi
+pip install cubepi[sqlite] # SQLite checkpointer
+pip install cubepi[postgres] # PostgreSQL checkpointer
+pip install cubepi[mysql] # MySQL checkpointer
+pip install cubepi[mcp] # MCP tool loaders
+pip install cubepi[tracing] # OpenTelemetry tracing
+pip install cubepi[trace-cli] # cubepi trace terminal viewer
+```
+
+## Minimal example
+
+```python
+import asyncio
+from cubepi import Agent, tool
+from cubepi.providers.anthropic import AnthropicProvider
+
+provider = AnthropicProvider(provider_id="anthropic", api_key="sk-...")
+
+@tool
+async def get_weather(city: str) -> str:
+ "Get current weather for a city."
+ return f"72°F and sunny in {city}"
+
+agent = Agent(
+ model=provider.model("claude-sonnet-4-6"),
+ tools=[get_weather],
+ system_prompt="You are a helpful assistant.",
+)
+agent.subscribe(lambda event, signal=None: print(event.delta, end="", flush=True) if event.type == "text_delta" else None)
+asyncio.run(agent.prompt("What's the weather in Tokyo?"))
+```
+
+## Comparison with alternatives
+
+| | LangGraph | CrewAI | PydanticAI | CubePi |
+|---|---|---|---|---|
+| Abstraction | State graph (nodes + edges) | Role-based crews and tasks | Typed agents with dependency injection | Plain async while-loop |
+| Streaming | Callback-based, multiple modes | Limited | `async for` | `async for event in stream` |
+| Checkpointing | Full snapshot per step | None built-in | None built-in | Append-only, O(1) per turn |
+| Core deps | langchain-core + transitive | crewai + many | pydantic-ai | anthropic + openai + pydantic |
+| Observability | LangSmith/Langfuse | None built-in | Logfire (optional) | Native OpenTelemetry |
+
+## Links
+
+- Homepage: https://cubepi.ai
+- Documentation: https://cubepi.ai/docs
+- GitHub: https://github.com/cubeplexai/cubepi
+- PyPI: https://pypi.org/project/cubepi/
+- Changelog: https://cubepi.ai/changelog
+- vs LangGraph: https://cubepi.ai/compare/langgraph
+- vs pi-agent-core: https://cubepi.ai/compare/pi-agent-core
+- Twitter/X: https://x.com/cubeplexai
+
+## License
+
+MIT
diff --git a/website/static/robots.txt b/website/static/robots.txt
index ba3369d..547384e 100644
--- a/website/static/robots.txt
+++ b/website/static/robots.txt
@@ -3,3 +3,19 @@ Allow: /
Sitemap: https://cubepi.ai/sitemap.xml
Sitemap: https://cubepi.ai/zh-Hans/sitemap.xml
+
+# AI/LLM crawlers — explicitly allowed
+User-agent: GPTBot
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+User-agent: anthropic-ai
+Allow: /
+
+# LLM context file (https://llmstxt.org)
+LLMs: https://cubepi.ai/llms.txt
diff --git a/website/versioned_docs/version-0.9/guides/agents/prompt-caching.md b/website/versioned_docs/version-0.9/guides/agents/prompt-caching.md
new file mode 100644
index 0000000..61518de
--- /dev/null
+++ b/website/versioned_docs/version-0.9/guides/agents/prompt-caching.md
@@ -0,0 +1,237 @@
+---
+title: Prompt Caching
+description: "How CubePi maximises prompt cache hit rates — append-only message storage, automatic cache breakpoints, and how to avoid breaking the cache."
+---
+
+# Prompt Caching
+
+Prompt caching lets LLM providers reuse the KV computation for the
+stable prefix of a request instead of reprocessing it on every turn.
+The savings are significant: Anthropic charges cached tokens at
+**10% of the normal input price**, and cache hits also reduce
+time-to-first-token.
+
+CubePi is designed from the ground up to maximise cache hit rates.
+This guide explains how caching works, why CubePi's architecture
+keeps the cache warm, and what you can do (or avoid doing) to
+preserve those hits.
+
+---
+
+## How prompt caching works
+
+Every LLM API request is a sequence of content blocks: system prompt,
+tool definitions, then the conversation history. The provider hashes
+the byte content of each block. If an incoming request shares a
+prefix with a recently-seen request up to the TTL, the cached KV
+state for that prefix is reused — the provider only processes the
+new tokens beyond the cache boundary.
+
+```
+Request N: [system] [tools] [msg 1] [msg 2] [msg 3]
+ ↑ ↑ ↑
+ cached cached cached ← all hits on turn N+1
+ [msg 4] ← new tokens only
+```
+
+Two things are required for a cache hit:
+
+1. **The prefix is byte-identical** to the previous request. Any
+ change — reordering, reformatting, adding a character — is a miss.
+2. **The TTL hasn't expired.** Anthropic offers 5-minute (`"short"`)
+ and 1-hour (`"long"`) retention; OpenAI caches automatically for
+ prompts over 1 024 tokens.
+
+---
+
+## Why append-only storage matters
+
+Many agent frameworks rebuild the full message list from a checkpoint
+snapshot on every turn. If serialisation details change — dict key
+ordering, whitespace, a timestamp field — the resulting byte sequence
+differs from the previous request and **every cache breakpoint from
+that point on misses**.
+
+CubePi's checkpointer is append-only: it only ever adds new messages
+to the end of the thread. The in-memory `agent.state.messages` list
+grows by appending; it is never rebuilt or reshuffled. This means the
+prefix of every request is guaranteed to be byte-identical to the
+previous turn, which is the most fundamental requirement for cache
+hits.
+
+---
+
+## Anthropic: automatic cache breakpoints
+
+`AnthropicProvider` inserts `cache_control` markers automatically
+via `DefaultCacheMarkerPolicy`. By default, three breakpoints are
+placed on each request:
+
+| Breakpoint | What gets cached | Why here |
+|---|---|---|
+| System prompt | The full system prompt block | Most stable content — rarely changes across turns |
+| Last tool definition | All tool schemas up to and including the last one | Tool lists change infrequently |
+| Last message in history | All prior conversation history | Moves forward each turn; prior turns stay warm |
+
+On turn N+1, the first two breakpoints are identical to turn N (same
+system prompt, same tools), so they get cache hits. The
+last-message breakpoint has moved one message forward, so it writes
+a new cache entry covering the slightly-longer history — and that
+entry will be a hit on turn N+2.
+
+### Configuration
+
+```python
+from cubepi.providers.anthropic import AnthropicProvider
+
+# Default: short TTL (5 min), automatic breakpoints
+provider = AnthropicProvider(api_key="…")
+
+# Long TTL (1 h) — use when turns are slow or infrequent
+provider = AnthropicProvider(api_key="…", cache_retention="long")
+
+# Disable caching entirely
+provider = AnthropicProvider(api_key="…", cache_retention="none")
+```
+
+### Reading cache metrics
+
+Each `AssistantMessage` carries a `Usage` object. The cache fields:
+
+```python
+agent.subscribe(lambda event, signal=None: None)
+await agent.prompt("Summarise the document")
+
+last_msg = agent.state.messages[-1] # AssistantMessage
+usage = last_msg.usage
+print(usage.input_tokens) # total prompt tokens (inclusive of cache_read)
+print(usage.cache_read_tokens) # tokens served from cache ← savings here
+print(usage.cache_write_tokens) # tokens written to cache this turn
+```
+
+Cache hit rate for a turn: `cache_read_tokens / input_tokens`.
+
+:::tip
+`input_tokens` in CubePi's `Usage` is the **inclusive** total (prompt
+= input + cache_read + cache_creation). Do **not** add `cache_read_tokens`
+to the denominator — you would be double-counting.
+:::
+
+You can also see these fields in the `cubepi trace` CLI output and in
+the OTel spans emitted by `Tracer`:
+
+```
+gen_ai.usage.input_tokens = 8 420 (inclusive)
+gen_ai.usage.cache_read.input_tokens = 7 980 (subset)
+```
+
+---
+
+## OpenAI: automatic caching
+
+OpenAI caches automatically for prompts longer than 1 024 tokens —
+no explicit `cache_control` markers are needed. CubePi surfaces the
+hit data through the same `Usage` interface:
+
+```python
+usage.cache_read_tokens # maps to prompt_tokens_details.cached_tokens
+```
+
+There is nothing to configure on the CubePi side. Keep the system
+prompt and tool definitions stable across turns and OpenAI's cache
+will warm up naturally.
+
+---
+
+## How to avoid breaking the cache
+
+### ✅ Do
+
+- **Keep the system prompt stable across turns.** The system prompt
+ is the outermost cache breakpoint. Changing it invalidates
+ everything.
+- **Keep the tool list stable.** Add or remove tools between
+ *conversations*, not between *turns*. The tool-definition
+ breakpoint covers the entire tool list; any change invalidates
+ from there.
+- **Use `cache_retention="long"`** if your agent turns take more than
+ 5 minutes (long thinking runs, slow tools, infrequent users).
+- **Use `agent.steer()`** to inject mid-turn guidance instead of
+ prepending a new message to history — steer appends, not inserts.
+
+### ❌ Avoid
+
+- **Injecting messages into the middle of history.** Inserting a
+ message before the last position shifts all subsequent messages,
+ making the sequence differ from what the provider cached.
+- **Changing the system prompt to include per-request data** (e.g.
+ current timestamp, request ID). Put volatile data in the user
+ message instead.
+- **Reordering tool definitions.** The tool list is serialised in
+ order; changing the order is a cache miss even if the tools
+ themselves are identical.
+- **Modifying a tool's description between turns** for the same
+ thread. Description changes are serialised into the schema and
+ will break the tool-definition breakpoint.
+
+---
+
+## Custom cache policy (Anthropic)
+
+If the default three-breakpoint strategy does not fit your use case,
+implement `CacheMarkerPolicy` and pass it to the provider:
+
+```python
+from cubepi.providers.anthropic import CacheMarkerPolicy, AnthropicProvider
+from cubepi.providers.base import Message
+
+class SystemOnlyPolicy:
+ """Cache only the system prompt — useful when tool lists change often."""
+
+ def mark_system(self) -> bool:
+ return True
+
+ def mark_last_tool(self) -> bool:
+ return False
+
+ def message_breakpoint_indices(self, messages: list[Message]) -> list[int]:
+ return [] # no message breakpoints
+
+provider = AnthropicProvider(
+ api_key="…",
+ cache_policy=SystemOnlyPolicy(),
+)
+```
+
+The three methods map directly onto the three default breakpoints.
+Return `True` / a non-empty list to enable a breakpoint, `False` /
+`[]` to skip it.
+
+---
+
+## Multi-tenant considerations
+
+In a multi-tenant setup each `thread_id` is an independent
+conversation. Cache hits are per-thread: user A's history warms a
+cache entry that benefits only user A's subsequent turns.
+
+For maximum cache efficiency across tenants:
+
+- Use a **stable, shared system prompt** for all tenants rather than
+ embedding per-tenant data in the system prompt. Per-tenant context
+ belongs in the first user message or in tool results.
+- Keep tool definitions identical across all tenant agents. If
+ different tenants need different tool sets, consider separate
+ `Agent` instances with separate `AnthropicProvider` configurations
+ rather than dynamically mutating the tool list.
+
+---
+
+## See also
+
+- [Anthropic Provider](../providers/anthropic) — `cache_retention`,
+ `CacheMarkerPolicy`, and the `on_payload` hook for inspecting raw requests.
+- [Multi-turn Conversations](./multi-turn) — how message history grows
+ across turns and why append semantics matter.
+- [Tracing](../tracing/overview) — reading `cache_read.input_tokens`
+ from OTel spans.
diff --git a/website/versioned_sidebars/version-0.9-sidebars.json b/website/versioned_sidebars/version-0.9-sidebars.json
index cd7421a..92ba992 100644
--- a/website/versioned_sidebars/version-0.9-sidebars.json
+++ b/website/versioned_sidebars/version-0.9-sidebars.json
@@ -23,7 +23,8 @@
"guides/agents/tool-use",
"guides/agents/multi-turn",
"guides/agents/streaming",
- "guides/agents/forking"
+ "guides/agents/forking",
+ "guides/agents/prompt-caching"
]
},
{