Open source · Apache 2.0 · Python 3.11+
Phronesis (φρόνησις): per Aristotele, saggezza pratica - la capacità di deliberare bene e agire con giudizio in situazioni concrete. Un LLM ha episteme (conoscenza). Un agente ha bisogno di 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)Perché Phronesis
Gli LLM sanno cose - quella è episteme. Ma gli agenti devono decidere e agire con giudizio in situazioni concrete. Quella è phronesis. La maggior parte dei framework per agenti li tratta come chatbot potenziati incollati a un ciclo d'uso degli strumenti. Phronesis li tratta come sistemi deliberativi con contratti espliciti: input tipizzati, effetti dichiarati, memoria limitata, pattern di esecuzione nominati.
I framework esistenti impongono una scelta. Da un lato, scrivi flusso di controllo arbitrario come codice: massima espressività e un sistema multi-agente che nessuno può debugare sei mesi dopo. Dall'altro, tutto è descritto in YAML o costruttori di grafi: leggibile a colpo d'occhio, impossibile appena serve qualcosa di non banale. Phronesis separa la specifica dichiarativa dall'esecuzione runtime. Agenti, strumenti, memoria e pipeline sono spec tipizzate, immutabili, serializzabili in JSON. I pattern di esecuzione provengono da un catalogo chiuso e ben definito - espressività senza caos.
Ogni esecuzione è osservabile tramite OpenTelemetry, ogni spec è versionabile, ogni contratto è un controllo runtime, non un commento in un prompt. Questa è la differenza fra un framework che produce demo e uno che produce sistemi che puoi gestire.
By the numbers
A closed, named catalog - from Sequence and Parallel to Reflexion and Tree Search.
Every mode with a deterministic cassette, plus a full multi-agent mini-app.
Branch coverage gated at 90% - the build fails below the floor.
Agents, tools, memory, providers, MCP, pipelines, observability and more.
mypy --strict across the entire source tree, no escape hatches.
Permissive license, public roadmap, no enterprise gates.
Tour del codice
Un agente lega un modello, strumenti e memoria sotto una singola spec dichiarativa.
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."""Principi
Gli agenti sono configurati a partire da pezzi - modello, strumenti, memoria, prompt - non sottoclassati. Assembli; non sovrascrivi.
Streaming, concorrenza e cancellazione sono ipotesi di base. Non c'è un'API sincrona ombra da mantenere.
Pydantic v2 ovunque. I tipi non sono documentazione - sono contratti runtime che il framework fa rispettare.
Le definizioni sono serializzabili in JSON e riproducibili. Lo stato di esecuzione vive a parte, osservabile e interrogabile.
Span OpenTelemetry per ogni run di agente, chiamata di strumento e stage di pipeline - dal primo commit, non avvitati dopo.
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. Modalità con un nome su cui puoi ragionare - non flusso di controllo arbitrario.
Cosa c'è dentro
Le primitive da cui è costruito ogni agente.
Come gli agenti ricordano e cosa condividono.
Come gli agenti si compongono in sistemi.
Engineering
mypy --strict and Pydantic v2 specs across the whole source tree. No untyped escape hatches.
1,600+ tests with branch coverage gated at 90% - the build fails below it, never above it on paper.
Record once, replay forever: cassette-backed runs make agent behavior reproducible in tests and CI without a network.
OpenTelemetry spans for every agent run, tool call, pipeline stage, and MCP session - correlated by stable ids.
Agents, tools, and pipelines are frozen, JSON-serializable dataclasses - versionable, diffable, reproducible.
ruff format and a strict ruff check gate every commit, alongside the type and test suites.
Installa
$pip install phronesis-framework
Stato del progetto
L'API cambierà. Stiamo lavorando in pubblico per costruire un framework che prenda sul serio i sistemi di agenti - tipizzato, componibile, osservabile. Nessuna rivendicazione di produzione, nessun caso studio inventato, nessuna barriera enterprise. Solo il codice e un impegno onesto verso il suo design.
Feedback, idee e contributi sono benvenuti via GitHub Discussions e Issues. La roadmap, le asperità e le questioni aperte sono tutte nel repository.
