오픈소스 · 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는 이를 명시적인 계약 - 타입화된 입력, 선언된 효과, 경계가 있는 메모리, 이름 붙은 실행 패턴 - 을 가진 숙고하는 시스템으로 취급한다.
기존 프레임워크는 선택을 강요한다. 한편으로는 임의의 제어 흐름을 코드로 작성한다: 최대의 표현력과 6개월 후 아무도 디버그할 수 없는 멀티 에이전트 시스템. 다른 한편으로는 모든 것이 YAML이나 그래프 빌더로 기술된다: 한눈에 읽히지만 사소하지 않은 무언가가 필요해지는 순간 불가능해진다. Phronesis는 선언적 명세와 런타임 실행을 분리한다. 에이전트, 도구, 메모리, 파이프라인은 타입화되고 불변이며 JSON 직렬화 가능한 스펙이다. 실행 패턴은 폐쇄적이고 잘 정의된 카탈로그에서 나온다 - 혼돈 없는 표현력.
모든 실행은 OpenTelemetry로 관측 가능하고, 모든 스펙은 버전화 가능하며, 모든 계약은 프롬프트 안의 주석이 아니라 런타임 검사다. 이것이 데모를 만드는 프레임워크와 운영할 수 있는 시스템을 만드는 프레임워크의 차이다.
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 스팬 - 첫 커밋부터 나중에 덧붙이지 않는다.
실행 패턴의 폐쇄 카탈로그
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.
프로젝트 상태