Skip to content
Phronesis v0.1.0 alpha is availableRead the announcement
Phronesis

Open source · Apache 2.0 · Python 3.11+

Practical wisdom for AI agent systems.

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.

Get startedView on GitHub
hello_phronesis.py
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)

Why Phronesis

An agent is not a chatbot with tools.

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.

By the numbers

Built like infrastructure, not a demo.

Phronesis is early, but it is not thin. The surface is small on purpose - and every layer carries its own tests, types, and observability.
19

Execution modes

A closed, named catalog - from Sequence and Parallel to Reflexion and Tree Search.

22

Runnable examples

Every mode with a deterministic cassette, plus a full multi-agent mini-app.

1,600+

Tests

Branch coverage gated at 90% - the build fails below the floor.

14

Stable modules

Agents, tools, memory, providers, MCP, pipelines, observability and more.

100%

Typed surface

mypy --strict across the entire source tree, no escape hatches.

Apache 2.0

Open source

Permissive license, public roadmap, no enterprise gates.

Code tour

The API in four snippets.

Real Python, using the public API as it stands today. The framework is in early alpha - the surface will grow, but the design will stay this lean.

The @agent decorator binds a model, typed tools, and a system prompt into a single declarative spec.

agent.py
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."""

Principles

Six choices, applied everywhere.

  • Composition over inheritance

    Agents are configured from parts - model, tools, memory, prompts - not subclassed. You assemble; you don't override.

  • Async-first

    Streaming, concurrency, and cancellation are baseline assumptions. There is no synchronous shadow API to maintain.

  • Strongly typed

    Pydantic v2 and mypy --strict throughout. Types are not documentation - they are runtime contracts the framework enforces.

  • Immutable specs, mutable runs

    Definitions are frozen, JSON-serializable and reproducible. Execution state lives apart, observable and queryable.

  • Observability built in

    OpenTelemetry spans for every agent run, tool call, and pipeline stage - from the first commit, not bolted on.

  • Closed catalog of execution patterns

    Sequence, Parallel, Debate, Consensus, Handoff, Reflexion, Tree Search and more - nineteen named modes you can reason about, not arbitrary control flow.

What's inside

A small, principled surface.

The framework is intentionally narrow. Each layer earns its place by either making a system safer to operate or making the code simpler to read six months later.

Core

The primitives every agent is built from.

  • Agents (@agent, sessions, tool-calling loop)
  • Tools (typed, effect-declaring)
  • MCP client and server
  • Providers (Anthropic, OpenAI, Ollama, vLLM)
  • Context builders

State and memory

How agents remember and resume.

  • Memory (working, key-value, vector, episodic)
  • Checkpoints (pause and resume)
  • Sessions

Orchestration and ops

How agents compose into systems you can run.

  • Pipelines
  • 19 execution modes
  • Provider middleware
  • Record / replay cassettes
  • OpenTelemetry observability

Engineering

The guarantees, not the promises.

An agent framework is only as trustworthy as the discipline behind it. These are the gates every change passes before it lands.

  • 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.

Install

One command. Python 3.11 or newer.

$pip install phronesis-framework
Read the docsStar on GitHub

Project status

Phronesis is in early alpha.

The API will change. But the foundations are already here: typed, immutable specs; nineteen named execution modes; deterministic record and replay; OpenTelemetry from the first commit; and over 1,600 tests held to a 90% coverage floor. We build in public - 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.

DiscussionsOpen issues