Acorn: 구조화된 I/O와 에이전틱 루프를 지원하는 LLM 에이전트 프레임워크

섹션별 상세

Pydantic을 활용한 구조화된 I/O 시스템을 통해 에이전트의 입력과 출력을 엄격하게 정의한다. 이는 LLM의 응답이 기대하는 스키마를 따르도록 보장하며, 유효성 검사 실패 시 자동으로 재시도를 수행하는 복구 메커니즘을 포함한다. 데이터의 정합성을 코드 수준에서 강제할 수 있어 시스템 안정성이 향상된다.

python

from pydantic import BaseModel, Field
from acorn import Module

class Input(BaseModel):
    text: str = Field(description="The text to summarize")
    max_words: int = Field(default=100, description="Maximum words in summary")

class Output(BaseModel):
    summary: str = Field(description="The concise summary")
    word_count: int = Field(description="Number of words in summary")

class Summarizer(Module):
    """Summarize text concisely."""
    initial_input = Input
    final_output = Output
    model = "anthropic/claude-sonnet-4-5-20250514"

summarizer = Summarizer()
result = summarizer(text="Long article text here...", max_words=50)

Pydantic 모델을 사용하여 입력과 출력 스키마를 정의하고 단일 턴 요약을 수행하는 예시

Module 클래스를 상속받아 에이전트를 정의하며, @tool 데코레이터를 사용하여 파이썬 함수를 LLM이 호출 가능한 도구로 즉시 변환한다. 도구의 스키마는 함수의 타입 힌트와 독스트링에서 자동으로 생성되어 개발자가 별도의 JSON 스키마를 작성할 필요가 없다. 이는 개발 생산성을 높이고 도구 정의 오류를 줄여준다.

멀티턴 실행을 지원하는 에이전틱 루프를 통해 복잡한 작업을 수행한다. on_step 콜백 함수를 사용하여 각 단계의 실행 상태를 세밀하게 제어하고, 실행 도중 동적으로 도구를 추가하거나 제거하며, 특정 조건 충족 시 조기에 실행을 종료할 수 있다. 이를 통해 에이전트의 추론 과정을 유연하게 관리한다.

python

class ResearchAgent(Module):
    """Research assistant with tools."""
    initial_input = Input
    max_steps = 5
    final_output = Output
    model = "anthropic/claude-sonnet-4-5-20250514"

    @tool
    def search(self, query: str) -> list:
        """Search for information."""
        return ["result1", "result2"]

    def on_step(self, step):
        print(f"Step {step.counter}")
        if len(step.tool_results) >= 3:
            step.finish(findings="Sufficient data collected", sources=["source1"])
        return step

도구 호출과 on_step 콜백을 활용하여 멀티턴 에이전틱 루프를 구현하는 예시

브랜칭 워크플로우 기능을 통해 부모 에이전트의 능력을 확장하는 서브 에이전트를 생성할 수 있다. 이를 통해 병렬 분석이나 Map-Reduce 패턴과 같은 복잡한 에이전트 구조를 설계하고 실행하는 것이 가능하다. 대규모 데이터를 처리하거나 다각도의 분석이 필요한 작업에 효과적이다.

프로덕션 안정성을 위해 모델 폴백과 프롬프트 캐싱 기능을 제공한다. 특정 모델 서비스 장애 시 대체 모델로 자동 전환하여 서비스 연속성을 보장하며, 반복되는 프롬프트 접두사를 캐싱하여 지연 시간과 API 비용을 효과적으로 절감한다. LiteLLM 통합으로 다양한 모델 제공업체를 단일 인터페이스로 지원한다.

용어 해설

파이단틱(Pydantic): — 파이썬 타입 힌트를 사용하여 데이터 유효성 검사와 설정을 관리하는 라이브러리이다. LLM의 비정형 응답을 정형화된 객체로 변환하고 검증하는 데 필수적인 도구로 활용된다.
에이전틱 루프(Agentic Loop): — LLM이 목표 달성을 위해 도구 호출, 결과 분석, 다음 행동 결정을 반복하는 멀티턴 실행 구조이다. 단순한 일회성 응답을 넘어 복잡한 문제를 단계별로 해결하는 에이전트의 핵심 메커니즘이다.
프롬프트 캐싱(Prompt Caching): — 자주 사용되는 프롬프트의 접두사 부분을 서버 측에 저장하여 재사용하는 기술이다. 동일한 컨텍스트를 반복해서 보낼 때 발생하는 토큰 비용을 줄이고 응답 지연 시간을 단축하는 효과가 있다.
모델 폴백(Model Fallback): — 주요 모델의 API 호출이 실패하거나 오류가 발생했을 때 사전에 정의된 대체 모델로 자동 전환하는 기능이다. 서비스의 가용성을 높이고 장애 상황에 유연하게 대응하기 위해 사용된다.
구조화된 입출력(Structured I/O): — LLM과 데이터를 주고받을 때 자유 형식의 텍스트 대신 JSON이나 특정 객체 스키마를 따르는 정형화된 형식을 사용하는 방식이다. 프로그램 간의 데이터 연동 안정성을 보장하고 파싱 오류를 최소화한다.

기술

Python
Pydantic
LiteLLM
Anthropic Claude
OpenAI GPT

활용 사례

텍스트 요약 시스템
자동화된 리서치 에이전트
GitHub 저장소 분석 도구
라이선스 호환성 검사기

언급된 리소스

문서Acorn Documentation