Código aberto · Apache 2.0 · Python 3.11+
Phronesis (φρόνησις): para Aristóteles, sabedoria prática - a capacidade de deliberar bem e agir com discernimento em situações concretas. Um LLM tem episteme (conhecimento). Um agente precisa de 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)Por que Phronesis
Os LLMs sabem coisas - isso é episteme. Mas os agentes precisam decidir e agir com discernimento em situações concretas. Isso é phronesis. A maioria dos frameworks de agentes os trata como chatbots aprimorados colados a um laço de uso de ferramentas. Phronesis os trata como sistemas deliberativos com contratos explícitos: entradas tipadas, efeitos declarados, memória delimitada, padrões de execução nomeados.
Frameworks existentes forçam uma escolha. De um lado, você escreve fluxo de controle arbitrário como código: expressividade máxima e um sistema multiagente que ninguém consegue depurar seis meses depois. Do outro, tudo é descrito em YAML ou construtores de grafos: legível à primeira vista, impossível assim que você precisa de algo não trivial. Phronesis separa a especificação declarativa da execução em tempo de execução. Agentes, ferramentas, memória, pipelines são specs tipadas, imutáveis, serializáveis em JSON. Os padrões de execução vêm de um catálogo fechado e bem definido - expressividade sem caos.
Cada execução é observável via OpenTelemetry, cada spec é versionável, cada contrato é uma verificação em tempo de execução, não um comentário num prompt. Essa é a diferença entre um framework que produz demos e um que produz sistemas que você pode operar.
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 pelo código
Um agente vincula um modelo, ferramentas e memória sob uma única spec declarativa.
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."""Princípios
Agentes são configurados a partir de partes - modelo, ferramentas, memória, prompts - não subclassificados. Você monta; não sobrescreve.
Streaming, concorrência e cancelamento são premissas básicas. Não há API síncrona paralela para manter.
Pydantic v2 em tudo. Tipos não são documentação - são contratos em tempo de execução que o framework faz cumprir.
Definições são serializáveis em JSON e reproduzíveis. O estado de execução vive à parte, observável e consultável.
Spans do OpenTelemetry para cada execução de agente, chamada de ferramenta e etapa de pipeline - desde o primeiro commit, não parafusados depois.
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. Modos nomeados sobre os quais se pode raciocinar - não fluxo de controle arbitrário.
O que tem dentro
As primitivas a partir das quais cada agente é construído.
Como agentes se lembram e o que compartilham.
Como agentes se compõem em sistemas.
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.
Instalar
$pip install phronesis-framework
Status do projeto
A API vai mudar. Estamos trabalhando em público para construir um framework que leva sistemas de agentes a sério - tipado, componível, observável. Sem afirmações de produção, sem estudos de caso fabricados, sem barreiras corporativas. Apenas o código e um compromisso honesto com seu design.
Feedback, ideias e contribuições são bem-vindos via GitHub Discussions e Issues. O roteiro, as arestas e as perguntas em aberto estão todos no repositório.
