开源 · Apache 2.0 · Python 3.11+
面向 AI 智能体系统的实践智慧。
Phronesis (φρόνησις):对亚里士多德而言, 实践智慧 - 是在具体情境中善于审议并以判断力行动的能力。LLM 拥有 episteme (知识)。智能体需要 phronesis。
from phronesis.agents import agent
from phronesis.providers import anthropic
@agent(
model=anthropic(model="claude-sonnet-4-6"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
def researcher() -> str:
"""Investigate a question and synthesize a cited answer."""
result = await researcher.run("What is phronesis in Aristotelian ethics?")
print(result.output)from phronesis.agents import agent
from phronesis.providers import anthropic
@agent(
model=anthropic(model="claude-sonnet-4-6"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
def researcher() -> str:
"""Investigate a question and synthesize a cited answer."""
result = await researcher.run("What is phronesis in Aristotelian ethics?")
print(result.output)为何选择 Phronesis
智能体不是带工具的聊天机器人。
LLM 知道事物 - 那是 知识(episteme)。但智能体必须在具体情境中带着判断力 做出决定并采取行动 。那是 实践智慧(phronesis)。多数智能体框架把它们当作粘在工具使用循环上的增强聊天机器人。Phronesis 把它们当作具有显式契约的审议系统:类型化输入、声明的副作用、有界记忆、命名的执行模式。
现有框架强迫做出选择。一方面,你以代码编写任意控制流:表达力最大,而六个月后没人能调试的多智能体系统。另一方面,一切都用 YAML 或图构造器描述:一眼可读,需要稍微复杂一点的东西时却不可能。Phronesis 将声明式规范与运行时执行分离。智能体、工具、记忆、管道都是 类型化、不可变、可序列化为 JSON 的规范。执行模式来自一个闭合、明确定义的目录 - 在不混乱的前提下保有表达力。
每次运行都可通过 OpenTelemetry 观测,每份规范都可版本化,每个契约都是运行时校验,而不是提示词中的注释。这就是产出 demo 的框架与产出可运维系统的框架之间的区别。
By the numbers
Built like infrastructure, not a demo.
Execution modes
A closed, named catalog - from Sequence and Parallel to Reflexion and Tree Search.
Runnable examples
Every mode with a deterministic cassette, plus a full multi-agent mini-app.
Tests
Branch coverage gated at 90% - the build fails below the floor.
Stable modules
Agents, tools, memory, providers, MCP, pipelines, observability and more.
Typed surface
mypy --strict across the entire source tree, no escape hatches.
Open source
Permissive license, public roadmap, no enterprise gates.
代码导览
四段代码看懂 API。
一个智能体在单一声明式规范下绑定模型、工具与记忆。
from phronesis import ToolEffect
from phronesis.agents import agent
from phronesis.providers import anthropic
from phronesis.tools import tool
@tool(effects=(ToolEffect.NETWORK,))
async def search_web(query: str, limit: int = 5) -> list[str]:
"""Search the web and return ranked snippets."""
...
@agent(
model=anthropic(model="claude-sonnet-4-6"),
tools=(search_web,),
system_prompt="You are a careful research assistant.",
max_iterations=8,
)
def assistant() -> str:
"""Answer questions grounded in live search results."""from phronesis import ToolEffect
from phronesis.agents import agent
from phronesis.providers import anthropic
from phronesis.tools import tool
@tool(effects=(ToolEffect.NETWORK,))
async def search_web(query: str, limit: int = 5) -> list[str]:
"""Search the web and return ranked snippets."""
...
@agent(
model=anthropic(model="claude-sonnet-4-6"),
tools=(search_web,),
system_prompt="You are a careful research assistant.",
max_iterations=8,
)
def assistant() -> str:
"""Answer questions grounded in live search results."""原则
六项选择,处处适用。
组合优于继承
智能体由组件 - 模型、工具、记忆、提示词 - 配置而成,而非通过子类化。你在装配,而不是覆写。
异步优先
流式、并发与取消是基本假设。没有同步的影子 API 要维护。
强类型
全程使用 Pydantic v2。类型不是文档 - 它们是框架强制执行的运行时契约。
规范不可变,运行可变
定义可 JSON 序列化且可复现。执行状态独立存在,可观测且可查询。
内置可观测性
每次智能体运行、每次工具调用、每个管道阶段都有 OpenTelemetry span - 从首次提交起,而非后期硬拼。
执行模式的闭合目录
Sequence、Parallel、ReActLoop、Consensus、Debate、Handoff。可推理的命名模式 - 而非任意控制流。
内部构成
小而有原则的表面。
核心
每个智能体所依赖的基本元素。
- 智能体
- 工具
- MCP 集成
- Providers (Anthropic, OpenAI, Ollama, vLLM)
- Context builders
状态与上下文
智能体如何记忆,以及它们共享什么。
- 记忆(情景、语义、工作、共享)
- Checkpoints (pause and resume)
- 会话
编排
智能体如何组合成系统。
- 管道
- 执行模式
- Provider middleware
- Record / replay cassettes
- 可观测性
Engineering
The guarantees, not the promises.
Typed end to end
mypy --strict and Pydantic v2 specs across the whole source tree. No untyped escape hatches.
Tested to a floor
1,600+ tests with branch coverage gated at 90% - the build fails below it, never above it on paper.
Deterministic replay
Record once, replay forever: cassette-backed runs make agent behavior reproducible in tests and CI without a network.
Observable by construction
OpenTelemetry spans for every agent run, tool call, pipeline stage, and MCP session - correlated by stable ids.
Immutable specs
Agents, tools, and pipelines are frozen, JSON-serializable dataclasses - versionable, diffable, reproducible.
Lint-clean
ruff format and a strict ruff check gate every commit, alongside the type and test suites.
项目状态