☁ Puff ☁ - 深层堆栈框架。
The deep stack runtime for Python. An all-in-one async runtime for AI Agents, GraphQL, ASGI, WSGI, Postgres, PubSub, Redis, Distributed Tasks, and HTTP2 Client.
Now with a built-in Agent Runtime — one binary, one process, everything agents need.
[![Crates.io][crates-badge]][crates-url] [![MIT licensed][mit-badge]][mit-url] [crates-badge]: https://img.shields.io/crates/v/puff_rs.svg [crates-url]: https://crates.io/crates/puff_rs [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg [mit-url]: https://github.com/hansonkd/puff/blob/master/LICENSE
Puff is a batteries included "deep stack" for Python. It's an experiment to minimize the barrier between Python and Rust to unlock the full potential of high level languages. Build your own Runtime using standard CPython and extend it with Rust. Imagine if GraphQL, Postgres, Redis, PubSub, Distributed Tasks, and now AI Agents were part of the standard library. That's Puff.
The old approach for integrating Rust in Python would be to make a Python package that uses rust and import it from Python. This approach has some flaws as the rust packages can't cooperate. Puff gives Rust its own layer, so you can build a cohesive set of tools in Rust that all work flawlessly together without having to re-enter Python.
Puff v2 takes this further. Every agent framework today is pure Python, stitching together HTTP calls to external services, serializing everything, managing state through hope. Puff already has the infrastructure — Postgres for memory, Redis for caching, pub/sub for coordination, task queues for background work, WebSockets for streaming. It just needed to be pointed at the right problem. Now it has a built-in agent runtime where LLM calls stream through Rust, tools execute on real threads, and everything runs in one process.
High level overview is that Puff gives Python
The idea is Rust and Python are near perfect complements to each other and building a framework to let them talk leads to greater efficiency in terms of productivity, scalability and performance.
| Python | Rust |
|---|---|
| ✅ High-Level | ✅ Low-Level |
| ✅ Lots of tools and packages | ✅ Lots of tools and packages |
| ✅ Easy to get started | ✅ Easy to get started |
| Interpreted (productivity at the cost of speed) | Compiled (speed at the cost of productivity) |
| ✅ Easy to get master | ❌ The learning curve gets steep quickly. |
| ✅ Fast iteration to prototype | ❌ Requires planning for correctness |
| ✅ Google a problem, copy paste, it works. | ❌ Less examples floating in the wild |
| ❌ Weak type system | ✅ Great Type System |
| ✅ Free-threaded mode (3.13+) unlocks parallelism | ✅ High Performance |
| ❌ Not-so safe | ✅ Safe |
The Zen of deepstack is recognizing that no language is the ultimate answer. Seek progress instead of perfection by using Python for rapid development and Rust to optimize the most critical paths once you find them later. Find the balance.
Install Rust to compile Puff for your platform.
Follow the instructions to install Cargo for your platform.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shUse cargo to install Puff.
cargo install puff-rsPuff requires Python >= 3.10. Python's Poetry is optional.
Your Puff Project needs to find your Python project. Even if they are in the same folder, they need to be added to the PYTHONPATH.
One way to set up a Puff project is like this:
poetry new my_puff_proj_py
cd my_puff_proj_py
poetry add puff-pyNow from my_puff_proj_py you can run your project with poetry run puff to access puff from poetry.
The Python project doesn't need to be inside off your Rust package. It only needs to be on the PYTHONPATH or inside an virtualenv. If you don't want to use poetry, you will have to set up something like a virtual environment when running Puff.
Puff v2 is a deep stack agent runtime. Define agents in Python, back them with Rust-speed infrastructure, serve them with one command. Every piece of infrastructure an agent needs — LLM calls, tool execution, memory, multi-agent coordination, streaming — is baked in, not bolted on.
from puff import Agent
# Define an agent with a system prompt and model
support = Agent(
name="customer-support",
model="claude-sonnet-4-6",
system_prompt="You are a helpful customer support agent for Acme Corp.",
skills=["./skills/github", "./skills/database"],
memory=True,
)Tools are organized as skills — curated packages of whitelisted CLI commands with context for the agent. No arbitrary shell access. Every command pattern is explicitly allowed.
# skills/github/skill.toml
[skill]
name = "github"
description = "Interact with GitHub repositories"
[[tools]]
name = "list-prs"
description = "List open pull requests"
command = "gh pr list --json number,title,author,url"
output = "json"
[[tools]]
name = "create-pr"
description = "Create a new pull request"
command = "gh pr create"
args = { title = { type = "str" }, body = { type = "str" } }
requires_approval = true # human-in-the-loop for mutations
[permissions]
allow = ["gh pr *", "gh issue *"]
deny = ["gh repo delete *"]Skills can include a context.md that gets injected into the agent's system prompt — domain knowledge that helps the agent use the tools effectively.
Multiple agents working together. Router dispatches to specialists. Supervisor delegates and reviews. Chain pipes output through a sequence. Parallel runs agents simultaneously on real threads.
from puff import Agent, Router
billing = Agent(name="billing", model="claude-haiku-4-5", skills=["./skills/billing"])
technical = Agent(name="technical", model="claude-sonnet-4-6", skills=["./skills/docs"])
support_desk = Router(
name="support-desk",
agents=[billing, technical],
router_prompt="Route billing/payment to billing, technical issues to technical.",
model="claude-haiku-4-5",
)One command starts everything — REST API, WebSocket streaming, health checks:
puff agent --port 8080# Start a conversation
curl -X POST http://localhost:8080/api/conversations \
-d '{"agent": "support-desk", "message": "I was double-charged"}'
# Real-time streaming via WebSocket
wscat -c ws://localhost:8080/ws/conversations/abc-123Agents remember things. Conversation history in Redis, long-term facts in Postgres with pgvector for semantic search. Puff manages it automatically — the developer never touches it.
All LLM calls go through Rust. Streaming SSE parsed at native speed. Multi-provider (Anthropic, OpenAI, Ollama) with automatic retry, exponential backoff, and provider fallback chains. Cost tracked per call, per agent, per conversation.
# puff.toml
[llm]
default_model = "claude-sonnet-4-6"
[llm.providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
[llm.providers.openai]
api_key_env = "OPENAI_API_KEY"
[llm.fallback]
"claude-sonnet-4-6" = ["gpt-4o"]
[memory]
auto_extract = true
recall_k = 10Test your agents like you test your code:
$ puff agent-ask --agent support-desk
> I was charged twice for order #123
Looking into that for you...Python programs in Puff are run by building a Program in Rust and registering the Python function there.
The Python method is bootstrapped and run on a thread in the Puff runtime.
Create a puff.toml
[[commands]]
function = "my_puff_proj_py.hello_world"
command_name = "hello_world"Python:
…While it can run any WSGI app, Puff has a special affection for Django. Puff believes that business logic should be implemented on a higher level layer and Rust should be used as an optimization. Django is a perfect high level framework to use with Puff as it handles migrations, admin, etc. Puff mimics the psycopg2 drivers and cache so that Django uses the Puff Database and Redis pool.
Transform your sync Django project into a highly concurrent Puff program with a few lines of code. Puff wraps the management commands so migrate, etc. all work as expected. Simply run poetry run run_cargo django [command] instead of using ./manage.py [command]. For example poetry run run_cargo django migrate. Don't use django's dev server, instead use Puff's with poetry run run_cargo serve.
Create a puff.toml
django = true
wsgi = "my_django_application.wsgi.application"
[[postgres]]
name = "default"
[[redis]]
name = "default"Use Puff everywhere in your Django app. Even create Django management commands that use Rust!
See puff-py repo for a more complete Django example.
Puff exposes Graphql Mutations, Queries and Subscriptions based on Python Class definitions. A core "killer feature" of the Puff Graphql engine is that it works on a "layer base" instead of a Node base. This allows each step of Graphql to gather the c
暂无开放 Issues,或尚未同步最近议题。