TL;DR

이 저장소는 35개의 생산 수준 agentic 아키텍처를 파이썬 라이브러리와 실행 가능한 교재로 묶어 동일한 .run(task) 계약으로 교체 가능한 패턴들을 제공한다. 결정론적 픽커 패턴을 포함해 일부 아키텍처에선 LLM의 범주형 커밋을 Python 합성으로 결합하여 점수 기반 병목을 회피하고 노트북 캡처를 통해 실제 LLM 출력과 이론을 함께 제시한다. 멀티 프로바이더 지원과 17개 태스크 벤치마크로 패턴-적합성을 계량화하고 최근 Nebius 실행에서 약 25분·$1.50의 비용으로 전체 스위트가 동작함이 보고되었다. 이로 인해 다양한 아키텍처를 빠르게 비교·검증하고 프로덕션 검증용 테스트 스위트를 갖추려는 프로젝트에서 유용하지만, 특정 패턴은 작업 형태에 따라 실패 케이스가 존재한다는 점을 감안해야 한다.

주요 기능

• 패키징한다 모든 주요 에이전트 패턴을 Architecture 클래스 형태로 패키징하여 일관된 .run(task) 인터페이스와 ArchitectureResult 반환 형태를 제공한다. 이 설계로 클래스 교체만으로 패턴을 바꿀 수 있으므로 다운스트림 코드 변경이 불필요하다. 각 패턴은 실행 가능한 Jupyter 노트북과 함께 배포되어 구현과 결과를 곧바로 확인할 수 있다.
• 실행 결과를 캡처한다 모든 노트북은 실제 LLM 호출로 실행된 캡처된 실행 로그를 포함하며 합성 예시가 아닌 실제 출력에 기반한 이론적 설명을 병기한다. 이 접근은 패턴이 현실 LLM 동작에서 어떻게 동작하는지를 직접 보여준다. 노트북들은 저장소 전체에서 재현 가능한 실험 기록 역할을 한다.
• 지원한다 멀티 프로바이더 구성을 통해 Nebius OpenAI Anthropic Groq Ollama Together Fireworks Mistral Google 등 다양한 제공자를 플러그인 방식으로 교체할 수 있다. LLM_PROVIDER 환경변수 설정만으로 백엔드를 전환할 수 있으므로 동일한 아키텍처를 여러 모델에서 빠르게 평가할 수 있다. 일부 제공자는 특정 패턴에서 권장 설정으로 표시되어 실행 품질을 최적화한다.
• 검증 도구를 제공한다 통합된 17개 태스크 벤치마크와 283개의 테스트 케이스를 통해 아키텍처의 동작과 회귀를 자동으로 검증할 수 있다. 저장소는 pytest 기반의 테스트 스위트와 노트북 실행 무결성 검사를 포함하여 코드 변경 시 기능 보장을 제공한다. 이 검증 체계는 새 아키텍처 추가와 리팩터링을 안전하게 만든다.

어떻게 동작하는가

저장소는 각 에이전트 패턴을 Architecture 클래스라는 단일 계약으로 구현하여 동일한 .run(task) 인터페이스와 동일한 반환 형태로 실행할 수 있게 한다. 결정론적 픽커 패턴은 LLM이 범주형 응답을 반환하도록 유도한 뒤 외부 Python 논리로 최종 결정을 합성하여 점수 기반 스코어링 병목을 회피한다. 각 패턴은 실행 가능한 노트북과 통합되어 실제 LLM 호출 결과를 바탕으로 단계별 동작과 내부 상태를 재현한다.

해결 문제

이 프로젝트는 에이전트 아키텍처를 통합된 라이브러리 형태로 정형화하여 패턴 간 비교와 재현 가능한 실행을 가능하게 만든다. 동일한 인터페이스로 아키텍처를 교체할 수 있으므로 설계 실험과 프로덕션 전환에서 아키텍처별 코드 이식 비용을 제거한다. 또한 실행된 노트북과 17개 태스크 벤치마크를 통해 패턴-적합성(pattern-fit) 문제를 계량화하여 어떤 아키텍처가 특정 작업에 적합한지 판단할 수 있게 한다.

지금 주목받는 이유

저장소는 35개의 생산 수준 아키텍처와 17개 태스크 벤치마크를 한곳에 모아 실무자와 연구자가 설계 대안을 빠르게 비교할 수 있게 했다. GitHub 상에서 수천 개의 스타와 실행 가능한 데모 노트북 및 자동화된 벤치마크가 결합되어 빠른 입문과 신뢰 가능한 비교를 동시에 제공한다. 또한 멀티 프로바이더와 경량 비용의 벤치마크 실행(예로 Nebius에서 약 25분과 $1.50 소요 사례)이 공유되어 실무 실험 장벽을 낮췄다.

차별점

• 결정성 규율을 적용한다 저장소는 결정론적 픽커 규율을 핵심 기술로 채택하여 LLM의 범주형 커밋과 Python 기반 합성을 결합한다. 이 방식은 LLM이 연속 점수만 생성하여 판단 신호가 희석되는 문제를 완화하며 13개의 아키텍처에 명시적으로 적용되었다. 추가로 9개 아키텍처는 설계상으로 본 병목을 회피하도록 구성되어 있어 다양한 접근이 공존한다.
• 실행 중심 노트북을 포함한다 모든 아키텍처는 실제 LLM 호출로 실행된 Jupyter 노트북과 함께 제공되어 이론과 실행 결과가 1:1 대응한다. 노트북은 캡처된 실행 로그와 주석을 포함하여 패턴의 내부 동작을 추적 가능하게 만들었다. 이 점은 합성 예시만 제공하는 레퍼런스와 구별되는 핵심 차별점이다.
• 프로바이더 독립성을 보장한다 저장소는 여러 LLM 제공자에 대한 옵션을 제공하며 환경변수 한 줄로 백엔드를 전환할 수 있다. Nebius를 기본값으로 삼되 OpenAI Anthropic Groq Ollama Together Fireworks Mistral Google 등을 지원하여 동일 아키텍처를 다양한 모델에서 평가할 수 있게 했다. 이 구조는 특정 모델 종속성을 줄이고 이식성을 높였다.

사용 사례

• 패턴 탐색과 프로토타이핑에 활용한다 연구나 PoC 단계에서 다양한 에이전트 패턴을 동일 인터페이스로 빠르게 비교할 수 있다. 노트북과 실행 예시가 병행되어 설계 결정의 근거를 바로 얻을 수 있다. 이 과정은 아키텍처 선택에 소요되는 시간과 실험 비용을 줄인다.
• 프로덕션 아키텍처 검증에 사용한다 저장소가 제공하는 테스트 스위트와 벤치마크로 새 아키텍처의 패턴-적합성을 계량화하여 운영 전 검증을 수행할 수 있다. 결정론적 픽커 등 규율은 프로덕션 안정성 측면에서 행동 규칙을 부여한다. 또한 통합된 provider 전환 기능으로 모델 교체 실험이 용이하다.
• 교육용 교재와 사례 연구로 활용한다 실행된 노트북은 이론과 실제 동작을 동시에 보여주므로 실무 교육이나 내부 워크숍의 교재로 적합하다. 학습 경로와 튜토리얼이 정리되어 있어 초급자부터 고급자까지 학습 로드맵을 따르기 쉽다. 결과 캡처는 학습자에게 실험 결과의 원인과 영향을 명확히 제시한다.

시작하기

가장 빠른 시작은 pip install "agentic-architectures[nebius,faiss,tavily]"로 필수 옵션을 포함해 패키지를 설치하는 것이다. 예시 코드는 from agentic_architectures import get_llm 로 LLM을 얻어 Reflection 같은 Architecture 클래스를 인스턴스화한 뒤 .run(task)로 실행하면 된다. 로컬에서 재현하려면 .env.example을 복사해 공급자 API 키를 채우고 pytest로 제공되는 테스트 스위트를 실행해 무결성을 확인하면 된다.

요구사항

• Python 런타임과 가상환경이 필요하다 프로젝트는 가상환경 내에서 pip로 설치하여 사용하도록 설계되어 있으며 Python 3.x 호환성을 전제로 한다. 가상환경을 만들고 활성화한 뒤 pip install -e .[dev,...] 명령으로 의존성을 설치해야 실행과 테스트가 정상 동작한다. 일부 통합 테스트는 외부 API 키를 요구하므로 환경변수 설정이 필수다.
• 프로바이더 API 키와 선택적 익스트라가 필요하다 Nebius OpenAI Anthropic 등 각 제공자별로 API 키를 .env에 설정해야 통합 데모와 일부 노트북이 정상 실행된다. 특정 기능은 faiss networkx tavily 같은 추가 패키지 설치를 요구하므로 quickstart 옵션을 통해 필요한 익스트라를 포함해 설치해야 한다. 로컬 Ollama 같은 경우 로컬 모델 구성으로 API 키 없이도 동작하는 옵션이 있다.
• 테스트와 문서 빌드를 위한 도구가 필요하다 pytest가 테스트 러너로 사용되며 문서와 레퍼런스는 mkdocs 기반으로 제공된다. CI 통합을 위해 GitHub Actions 워크플로가 포함되어 있고 도커·Codespaces 같은 개발 환경에서 빠르게 열어볼 수 있다. 통합 테스트 중 일부는 env-gated로 분리되어 있어 실행 시 환경설정에 주의해야 한다.

벤치마크