Upsonic/Upsonic 딥다이브
— 남들이 만든 유명한 API를 전부 한 패키지에 다시 지은 에이전트 프레임워크

1프로젝트 한 줄 요약

두 종류의 에이전트

Upsonic이 제공하는 진입점은 크게 둘이다. 이름이 헷갈리기 쉬우니 먼저 정리한다.

# 전통적 에이전트 — 한 번 물어보고 답 받기
from upsonic import Agent, Task

agent = Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst")
task  = Task(description="현재 시장 트렌드를 분석해줘")
agent.print_do(task)

# 자율 에이전트 — 폴더를 주고 알아서 돌아다니게 하기
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/logs",   # ← 이 폴더 밖으로는 못 나간다
)
agent.print_do(Task("서버 로그를 분석해서 이상 패턴을 찾아줘"))

2왜 주목받는가 — 그리고 왜 논쟁적인가

주목 이유 ① 유명 API를 "그대로" 재구현했다

이게 Upsonic의 가장 큰 특징이자, 가장 논쟁적인 지점이다. 세 군데를 보자.

주목 이유 ② "Ralph 루프" — 파일시스템을 진실원으로 삼는 자율 개발 패턴

ralph/ 모듈은 코드 주석에서 스스로를 "Ralph/Groundhog 기법"이라 부른다. Groundhog Day(사랑의 블랙홀), 즉 "매일 같은 하루가 반복되지만, 기억은 파일에 남아 조금씩 나아진다"는 그 영화의 구조를 그대로 가져온 이름이다.

# ralph/phases/incremental.py — 이터레이션 성공 판정
# LLM이 "다 했어요"라고 말하는 걸 믿지 않는다.
state_after = self.state_manager.load_state()
pending_count_after = len(state_after.get_pending_items())

# 진짜 성공: 체크리스트 항목이 [ ] → [x] 로 바뀌었는가
task_completed = pending_count_after < pending_count_before

return IterationResult(
    iteration=self._current_iteration,
    task_picked=first_item,
    success=task_completed,
    backpressure_passed=task_completed,
)

여기에 백프레셔 게이트가 붙는다. ralph/backpressure/gate.py의 BackpressureGate는 사용자가 지정한 build_command / test_command / lint_command를 실제로 실행해 PASS/FAIL을 판정하고, 그 결과를 문자열로 에이전트에게 되돌려준다. "빌드와 테스트가 통과해야 다음으로 넘어간다"는 물리적 제동장치다.

주목 이유 ③ 16종 안전 정책 엔진

safety_engine/policies/에는 PII, 금융, 의료, 법률, 피싱, 사기 탐지, 내부자 위협, 암호화폐, 사이버보안, 욕설, 성인 콘텐츠, 전화번호, 민감 사회 이슈, 기술 정보, 스킬 프롬프트 인젝션, 도구 안전성 등 16개 영역의 정책이 들어 있다. 각 정책은 정규식 규칙과 LLM 판정 규칙을 모두 갖는 공통 패턴을 따른다.

특히 눈여겨볼 것은 anonymization.py의 가역적 익명화다.

LLM 판정 쪽도 재밌다. safety_engine/llm/upsonic_llm.py의 UpsonicLLMProvider는 판정을 위해 또 다른 Upsonic Agent를 내부에서 생성한다. 즉 에이전트가 에이전트를 감시하는 구조다. 그리고 판정 결과는 Pydantic 모델로 강제되며, confidence >= 0.7일 때만 채택한다.

냉정한 시각: 이 프레임워크의 약점

3기술 스택 전체 지도

기반 — 의외로 가볍다

이 정도 규모의 프레임워크치고 필수 의존성이 적다. pyproject.toml의 기본 dependencies는 22개뿐이고, 무거운 것들은 전부 optional extras로 빠져 있다.

선택 의존성 — 여기가 진짜 전장

이 구조가 주는 교훈: "모든 걸 지원한다"와 "설치가 무겁다"는 양립할 수 있다. 벡터DB 7종을 지원하지만, 실제로 설치되는 건 당신이 고른 하나뿐이다.

LLM 프로바이더 — 29종

providers/ 디렉토리 파일명 기준 전체 목록이다. 코드에 실재하는 것만 적었다.

프론트엔드? 없다 — 대신 채널이 있다

Upsonic에는 웹 UI가 없다. 대신 interfaces/가 메신저를 UI로 삼는다. Slack, Discord, Telegram, WhatsApp, Gmail, 범용 메일 6종이며, 각 폴더는 <채널>.py + schemas.py 구성으로 통일돼 있다.

InterfaceManager.serve(port=...)로 웹훅 서버를 띄우면(uvicorn) 메신저 메시지가 에이전트로 흘러든다. 동작 모드는 둘이다.

인프라 · 개발 도구

4아키텍처 심화 분석

전체 조감도

설계 패턴 ① Step 파이프라인 — 거대 함수를 27조각으로 자르기

agent/agent.py는 5,424줄짜리 괴물 파일이다. 하지만 실제 실행 로직은 대부분 agent/pipeline/으로 빠져나가 있다. 모든 단계는 하나의 추상 클래스를 상속한다.

# agent/pipeline/step.py (구조 요약)
class Step(ABC):
    async def execute(self, ctx) -> StepResult: ...       # 일반 실행
    async def execute_stream(self, ctx):                  # 스트리밍 실행
        yield AgentEvent(...)                            # 이벤트를 흘려보냄
    async def run(self, ctx): ...                        # 래퍼(에러·로깅)
    async def run_stream(self, ctx): ...

순서 중에 특히 의미 있는 배치가 있다. 10번 UserPolicyStep이 11번 UserInputBuildStep보다 앞이다. 즉 사용자 입력을 프롬프트로 조립하기 전에 안전 검사를 먼저 통과시킨다. 반대로 AgentPolicyStep은 19번 — 모델이 답을 만든 뒤에 출력을 검사한다. 입구와 출구 양쪽에 검문소가 있는 셈이다.

설계 패턴 ② 컨텍스트 매니저 — Step이 일을 떠넘기는 곳

Step은 "언제"를 정하고, 실제 "어떻게"는 agent/context_managers/의 매니저 객체들이 맡는다.

설계 패턴 ③ Ralph 루프 — 상태를 파일에 두는 자율 개발

설계 패턴 ④ 워크스페이스 샌드박싱 — 한 메서드로 통일

파일 툴킷의 모든 함수(read_file, write_file, edit_file, list_dir …)는 경로를 쓰기 전에 반드시 이 메서드를 거친다.

# agent/autonomous_agent/filesystem_toolkit.py:64-87
def _validate_path(self, path: str) -> Path:
    if path.startswith("/"):
        resolved = Path(path).resolve()
    else:
        resolved = (self.workspace / path).resolve()   # ← .. 등을 정규화
    try:
        resolved.relative_to(self.workspace)            # ← 하위인지 검사
    except ValueError:
        raise ValueError(f"Path '{path}' is outside workspace")
    return resolved

반면 셸 쪽은 대조적으로 허술하다. 같은 문서 안에서 이 격차를 인식하는 게 중요하다.

# agent/autonomous_agent/shell_toolkit.py:74-102 — 차단 목록 전체
self.blocked_commands: List[str] = blocked_commands or [
    "rm -rf /", "rm -rf /*", ":(){:|:&};:", "mkfs", "dd if=/dev/zero",
]
# _validate_command()는 이 5개가 문자열에 포함되는지만 확인한다.
# curl, cat /etc/passwd, ssh … 전부 통과한다.

설계 패턴 ⑤ UEL — 파이프 연산자는 어떻게 만들어지나

파이썬에서 a | b는 a.__or__(b)를 호출한다. LCEL류 문법의 비밀은 이 매직 메서드 하나다.

# uel/runnable.py
class Runnable(ABC, Generic[Input, Output]):
    def __or__(self, other):
        other_runnable = coerce_to_runnable(other)   # 함수·dict도 러너블로 변환
        if isinstance(self, RunnableSequence):
            # 이미 시퀀스면 스텝을 뒤에 붙인다 (중첩 방지)
            return RunnableSequence(steps=self.steps + [other_runnable])
        return RunnableSequence(steps=[self, other_runnable])

그래서 이렇게 쓴다.

from upsonic.uel import ChatPromptTemplate, StrOutputParser, RunnableParallel

prompt = ChatPromptTemplate.from_template("{topic}에 대해 설명해줘")
chain  = prompt | model | StrOutputParser()          # 순차 연결
chain.invoke({"topic": "트랜스포머"})

# 병렬 — dict 리터럴이 자동으로 RunnableParallel이 된다
both = {"요약": summarize_chain, "번역": translate_chain} | merge_chain

설계 패턴 ⑥ 메모리 — 저장과 주입을 분리한 6개 플래그

storage/memory/memory.py의 Memory 클래스가 흥미로운 건, "저장할 것"과 "다음에 불러올 것"을 독립적으로 켜고 끌 수 있다는 점이다.

설계 패턴 ⑦ Team — 리더만 기억한다

team/team.py의 Team은 세 가지 모드를 갖는다.

coordinate 모드의 핵심은 DelegationManager.get_delegation_tool()이다. 리더에게 delegate_task(member_id, description, tools, context, expected_output)라는 툴을 동적으로 만들어 쥐어준다. 리더 입장에서 위임은 그냥 함수 호출 하나다.

작은 최적화 하나가 눈에 띈다 — ResultCombiner.should_combine_results()는 len(results) > 1일 때만 병합용 LLM을 호출한다. 결과가 하나면 그대로 반환한다. 불필요한 LLM 호출 = 불필요한 비용이라는 감각이 코드에 박혀 있다.

설계 패턴 ⑧ 안전 정책의 구조 — 규칙과 행동의 분리

16개 정책(PII, 금융, 의료, 법률, 피싱, 사기, 내부자 위협, 암호화폐, 사이버보안, 욕설, 성인, 전화번호, 민감 사회 이슈, 기술, 스킬 인젝션, 툴 안전성)이 전부 이 골격을 공유한다. 새 정책을 추가하려면 Rule 하나와 Action 하나만 쓰면 된다는 게 이 설계의 이득이다.

설계 패턴 ⑨ graphv2 — LangGraph를 그대로

# graphv2/state_graph.py:227-235
def compile(
    self, *,
    checkpointer: Optional[BaseCheckpointer] = None,   # MemorySaver / SqliteCheckpointer
    store: Optional[BaseStore] = None,                 # 스레드 간 공유 저장소
    cache: Optional[BaseCache] = None,                 # 노드 단위 결과 캐시
    interrupt_before: Optional[List[str]] = None,      # HITL: 실행 전 멈춤
    interrupt_after: Optional[List[str]] = None,
    durability: Literal["exit", "async", "sync"] = "async",
) -> "CompiledStateGraph":

LangGraph를 써본 사람이라면 시그니처가 거의 그대로임을 즉시 알아볼 것이다. Command, Send, InterruptException, GraphRecursionError까지 이름이 일치한다.

설계 패턴 ⑩ OCR — 2계층 파이프라인

from upsonic.ocr import OCR
from upsonic.ocr.layer_1.engines import EasyOCREngine

engine = EasyOCREngine(languages=["en"])
ocr = OCR(layer_1_ocr_engine=engine)        # ← 엔진을 주입
text = ocr.get_text("invoice.pdf")

엔진을 생성자 인자로 주입하는 게 핵심이다. Tesseract로 시작했다가 정확도가 아쉬우면 engine= 한 줄만 바꿔 DeepSeek 비전 모델로 갈아탈 수 있다. 이게 의존성 주입(DI)의 실용적 이득이다.

5디렉토리 구조 해부

최상위

src/upsonic — 기능군으로 묶어보기

읽기 순서 추천

documents/ai — 이 저장소가 AI에게 일 시키는 방법

흥미로운 폴더가 하나 있다. documents/ai/guides/에는 feature 추가, refactor, bug-fix, testing, coding-standards, serena, memory, subagents, 새 프리빌트 에이전트 추가, commit — 총 9~10개의 AI 에이전트용 작업 가이드가 들어 있다.

그리고 documents/ai/explanation/<서브시스템>/<서브시스템>.md를 "행위 계약(behavior contract)의 권위 있는 문서"로 취급하며, 코드를 바꾸면 이 문서도 함께 갱신하도록 프로세스에 못 박아뒀다.

6학습 포인트 — 기술별 배울 것

7시스템 · 실행 요구사항

# tools/mcp.py:66-76
console.print(
    "[yellow]⚠️  MCP Security: Only connect to MCP servers you trust. "
    "Stdio servers run arbitrary processes on your machine; "
    "do not use commands or config from untrusted sources.[/yellow]"
)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식

• GitHub — Upsonic/Upsonic (MIT · 별 7,913 · 포크 738)
• 공식 문서 docs.upsonic.ai
• 퀵스타트 · 체인지로그
• PyPI — upsonic
• llms-full.txt — 코딩 도구(Cursor·VSCode 등)에 문서 소스로 등록하는 용도

비교 대상 (재구현의 원본)

• LangChain LCEL 개념 문서 — uel/과 비교
• LangGraph 문서 — graphv2/와 비교
• anthropics/skills — skills/의 스펙 원본
• Model Context Protocol 공식 사이트

저장소 안에서 꼭 볼 파일

• src/upsonic/uel/runnable.py — 파이프 연산자의 전부
• src/upsonic/agent/pipeline/steps.py — 27개 Step 목록
• src/upsonic/agent/autonomous_agent/filesystem_toolkit.py — 샌드박싱
• src/upsonic/ralph/phases/incremental.py — 자율 루프 판정 로직
• src/upsonic/safety_engine/anonymization.py — 가역 익명화
• documents/ai/guides/ — AI 에이전트용 작업 가이드 9종
• tests/doc_examples/ — 실제로 돌아가는 예제 136개