Open source · Apache 2.0 · Python 3.11+
Phronesis (φρόνησις): for Aristotle, practical wisdom — the capacity to deliberate well and act with judgment in concrete situations. An LLM has episteme (knowledge). An agent needs phronesis.
from phronesis import Agent, anthropic
researcher = Agent(
name="researcher",
model=anthropic("claude-opus-4-7"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
answer = await researcher.run("What is phronesis in Aristotelian ethics?")from phronesis import Agent, anthropic
researcher = Agent(
name="researcher",
model=anthropic("claude-opus-4-7"),
system_prompt="You investigate questions thoroughly and cite sources.",
)
answer = await researcher.run("What is phronesis in Aristotelian ethics?")Why Phronesis
LLMs know things — that is episteme. But agents must decide and act with judgment in concrete situations. That is phronesis. Most agent frameworks treat agents as enhanced chatbots glued to a tool-use loop. Phronesis treats them as deliberating systems with explicit contracts: typed inputs, declared effects, bounded memory, named execution patterns.
Existing frameworks force a choice. On one side, you write arbitrary control flow as code: maximal expressiveness, and a multi-agent system that nobody can debug six months later. On the other, everything is described in YAML or graph-builders: legible at a glance, impossible the moment you need something non-trivial. Phronesis separates declarative specification from runtime execution. Agents, tools, memory, pipelines are typed, immutable, JSON-serializable specs. Execution patterns come from a closed, well-defined catalog — expressiveness without chaos.
Every run is observable through OpenTelemetry, every spec is versionable, every contract is a runtime check, not a comment in a prompt. This is the difference between a framework that produces demos and one that produces systems you can operate.
Code tour
An agent binds a model, tools, and memory under a single declarative spec.
from phronesis import Agent, anthropic
from phronesis.memory import SemanticMemory
agent = Agent(
name="assistant",
model=anthropic("claude-opus-4-7"),
tools=[search_web, read_file],
memory=SemanticMemory(scope="session"),
system_prompt="You are a careful research assistant.",
)from phronesis import Agent, anthropic
from phronesis.memory import SemanticMemory
agent = Agent(
name="assistant",
model=anthropic("claude-opus-4-7"),
tools=[search_web, read_file],
memory=SemanticMemory(scope="session"),
system_prompt="You are a careful research assistant.",
)Patterns
Agents that gather information, reason over it, and synthesize answers with citations.
Agents that read, structure, and act on documents with explicit memory of what they have seen.
Pipelines composing specialized agents through handoffs, debate, or consensus.
Agents that invoke typed tools and MCP servers under explicit safety contracts.
Principles
Agents are configured from parts — model, tools, memory, prompts — not subclassed. You assemble; you don't override.
Streaming, concurrency, and cancellation are baseline assumptions. There is no synchronous shadow API to maintain.
Pydantic v2 throughout. Types are not documentation — they are runtime contracts the framework enforces.
Definitions are JSON-serializable and reproducible. Execution state lives apart, observable and queryable.
OpenTelemetry spans for every agent run, tool call, and pipeline stage — from the first commit, not bolted on.
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. Named modes you can reason about — not arbitrary control flow.
What's inside
The primitives every agent is built from.
How agents remember and what they share.
How agents compose into systems.
Install
$pip install phronesis-framework
Project status
The API will change. We are working in public to build a framework that takes agent systems seriously — typed, composable, observable. No production claims, no fabricated case studies, no enterprise gates. Just the code, and an honest commitment to its design.
Feedback, ideas, and contributions are welcome through GitHub Discussions and Issues. The roadmap, the rough edges, and the open questions are all in the repository.
