오픈소스 · Apache 2.0 · Python 3.11+

AI 에이전트 시스템을 위한 실천적 지혜.

Phronesis (φρόνησις): 아리스토텔레스에게 실천적 지혜 는 구체적인 상황에서 잘 숙고하고 판단을 가지고 행동하는 능력이다. LLM은 episteme (지식)을 가진다. 에이전트에게는 phronesis가 필요하다.

시작하기 GitHub에서 보기

hello_phronesis.pypython

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?")

왜 Phronesis인가

에이전트는 도구를 가진 챗봇이 아니다.

LLM은 무언가를 안다 — 그것이 에피스테메(episteme)이다. 그러나 에이전트는 구체적인 상황에서 판단을 가지고 결정하고 행동해야 한다. 그것이 프로네시스(phronesis)이다. 대부분의 에이전트 프레임워크는 에이전트를 도구 사용 루프에 붙은 강화된 챗봇으로 취급한다. Phronesis는 이를 명시적인 계약 — 타입화된 입력, 선언된 효과, 경계가 있는 메모리, 이름 붙은 실행 패턴 — 을 가진 숙고하는 시스템으로 취급한다.

기존 프레임워크는 선택을 강요한다. 한편으로는 임의의 제어 흐름을 코드로 작성한다: 최대의 표현력과 6개월 후 아무도 디버그할 수 없는 멀티 에이전트 시스템. 다른 한편으로는 모든 것이 YAML이나 그래프 빌더로 기술된다: 한눈에 읽히지만 사소하지 않은 무언가가 필요해지는 순간 불가능해진다. Phronesis는 선언적 명세와 런타임 실행을 분리한다. 에이전트, 도구, 메모리, 파이프라인은 타입화되고 불변이며 JSON 직렬화 가능한 스펙이다. 실행 패턴은 폐쇄적이고 잘 정의된 카탈로그에서 나온다 — 혼돈 없는 표현력.

모든 실행은 OpenTelemetry로 관측 가능하고, 모든 스펙은 버전화 가능하며, 모든 계약은 프롬프트 안의 주석이 아니라 런타임 검사다. 이것이 데모를 만드는 프레임워크와 운영할 수 있는 시스템을 만드는 프레임워크의 차이다.

코드 투어

네 개의 스니펫으로 보는 API.

진짜 Python. 진짜 형태. 아래의 프레임워크는 초기 알파다 — 표면적은 늘어나겠지만 설계는 이만큼 군더더기 없이 유지될 것이다.

에이전트는 단일 선언적 스펙 아래에서 모델, 도구, 메모리를 묶는다.

agent.pypython

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.",
)

패턴

반복되는 에이전트 형태를 위한 설계.

이는 프레임워크가 오늘 지원하는 패턴이다. 사례 연구가 아니다 — 우리는 아직 주장할 만한 프로덕션 사용자가 없으며, 다른 척하지도 않을 것이다.

리서치 에이전트
정보를 모으고, 그에 대해 추론하며, 인용과 함께 답을 합성하는 에이전트.
문서 에이전트
본 것에 대한 명시적 기억을 가지고 문서를 읽고 구조화하며 행동하는 에이전트.
멀티 에이전트 파이프라인
이양, 토론, 합의를 통해 전문 에이전트를 구성하는 파이프라인.
도구 사용 어시스턴트
명시적 안전 계약 아래 타입화된 도구와 MCP 서버를 호출하는 에이전트.

원칙

여섯 가지 선택, 어디에나 적용.

상속보다 합성
에이전트는 부품 — 모델, 도구, 메모리, 프롬프트 — 으로 구성되며 서브클래스화되지 않는다. 조립하지, 오버라이드하지 않는다.
비동기 우선
스트리밍, 동시성, 취소는 기본 전제다. 유지해야 할 동기 그림자 API가 없다.
강한 타입
전반에 Pydantic v2. 타입은 문서가 아니다 — 프레임워크가 강제하는 런타임 계약이다.
불변 스펙, 가변 실행
정의는 JSON 직렬화 가능하며 재현 가능하다. 실행 상태는 별도로 존재하며 관측 가능하고 조회 가능하다.
내장 관측성
모든 에이전트 실행, 도구 호출, 파이프라인 스테이지에 OpenTelemetry 스팬 — 첫 커밋부터 나중에 덧붙이지 않는다.
실행 패턴의 폐쇄 카탈로그
Sequence, Parallel, ReActLoop, Consensus, Debate, Handoff. 추론할 수 있는 이름 붙은 모드 — 임의의 제어 흐름이 아니다.

내부에 무엇이 있나

작고 원칙적인 표면.

프레임워크는 의도적으로 좁다. 각 계층은 시스템을 더 안전하게 운영하게 만들거나, 6개월 후 코드를 더 쉽게 읽게 만들어 그 자리를 얻는다.

코어

모든 에이전트가 만들어지는 기본 요소.

에이전트
도구
MCP 통합
프롬프트
기능

상태와 컨텍스트

에이전트가 어떻게 기억하고 무엇을 공유하는가.

메모리(에피소딕, 시맨틱, 작업, 공유)
컨텍스트 관리
세션

오케스트레이션

에이전트가 어떻게 시스템으로 구성되는가.

파이프라인
실행 모드
에이전트 간 통신
정책
관측성

설치

명령 하나. Python 3.11 이상.

$pip install phronesis-framework

문서 읽기 GitHub에서 스타

프로젝트 상태

Phronesis는 초기 알파입니다.

API는 바뀔 것이다. 우리는 에이전트 시스템을 진지하게 다루는 프레임워크 — 타입화되고, 합성 가능하며, 관측 가능한 — 를 공개적으로 만들고 있다. 프로덕션 주장도 없고, 조작된 사례 연구도 없으며, 엔터프라이즈 장벽도 없다. 오직 코드와, 그 설계에 대한 정직한 약속뿐이다.

피드백, 아이디어, 기여는 GitHub Discussions와 Issues를 통해 환영한다. 로드맵, 거친 부분, 미해결 질문은 모두 저장소에 있다.

토론 이슈 열기

AI 에이전트 시스템을 위한 실천적 지혜.

리서치 에이전트

문서 에이전트

멀티 에이전트 파이프라인

도구 사용 어시스턴트

상속보다 합성

비동기 우선

강한 타입

불변 스펙, 가변 실행

내장 관측성

실행 패턴의 폐쇄 카탈로그

명령 하나. Python 3.11 이상.