FareedKhan-dev/all-agentic-architectures: 모든 에이전트 아키텍처 라이브러리 및 교과서

라이브러리이자 살아있는 교과서 — 실제 LLM (Large Language Model) 출력값, 제공자 중립적 (provider-agnostic), 전반에 걸친 결정론적 선택기 (deterministic-picker) 원칙 적용, 그리고 모든 아키텍처를 관련 작업과 비교하여 순위를 매기는 비교 벤치마크 리더보드를 제공합니다.

아키텍처 (ARCHITECTURES) |
테스트 통과 (PASSING TESTS) |
벤치마크 작업 (BENCHMARK TASKS) |
LLM 제공자 (LLM PROVIDERS) |
모의 실행 (MOCKED RUNS) |

문헌에 등장하는 모든 주요 에이전트 AI 패턴을 실행 가능한 Architecture 클래스로 패키징하고, 통일된 계약 (contract)을 제공하는 단일 Python 라이브러리입니다. 각 패턴은 합성 예시가 아닌, 캡처된 실행 결과에 기반하여 이론이 작성된 완전 실행 Jupyter notebook과 함께 제공됩니다. 이 라이브러리는 멀티 프로바이더 (Nebius, OpenAI, Anthropic, Groq, Ollama, Together, Fireworks, Mistral, Google)를 지원하며 LangGraph 상태 머신 (state machines)을 기반으로 구축되었습니다.

이 저장소의 핵심적인 기술적 원칙은 **결정론적 선택기 패턴 (deterministic-picker pattern)**입니다. 모든 LLM-as-Scorer (점수 매기는 도구로서의 LLM) 인터페이스는 LLM이 범주형 특징 (booleans, enums)을 확정하도록 하고, Python이 결정 신호를 구성하도록 합니다. 이는 LLM-as-Scorer의 평탄 대역 병리 현상 (flat-band pathology)에서 벗어날 수 있는 보편적인 탈출구이며, 35개 아키텍처 중 13개에 적용되었습니다. 나머지 9개는 설계상 아키텍처적으로 면역되어 있습니다.

pip install "agentic-architectures[nebius,faiss,tavily]"

from agentic_architectures import get_llm
from agentic_architectures.architectures import Reflection
arch = Reflection(llm=get_llm(), max_iterations=2, target_score=8)
...

35개 모든 아키텍처에 걸쳐 동일한 .run(task) 인터페이스를 사용합니다. 동일한 ArchitectureResult 반환 형태를 가집니다. 클래스를 바꾸고 패턴을 바꿔도, 여러분의 다운스트림 (downstream) 코드는 변경되지 않습니다.

새로운 클론으로부터 가상 환경 (virtualenv) 설정하기

git clone https://github.com/FareedKhan-dev/all-agentic-architectures
cd all-agentic-architectures
python -m venv .venv
...

|
반복을 통해 답변 품질을 높이는 자기 비판 루프 (Self-critique loops).
|
다양한 경로를 샘플링하거나 보상 (Rewards)을 기반으로 트리 (Tree)를 확장.
|
모든 주장에 근거를 제시 — 다섯 가지 검색 형태 (Retrieval shapes).
|
|
호출 간에 학습 — 저장 형태 (Storage shape) 선택.
|
하나의 검색 도구에서 실제 Chromium 브라우저까지.
|
전문가 (Specialists), 토론 (Debate), 다각도 연구 (Multi-perspective research).
|
|
결정론적 Python 게이트 (Deterministic Python gates)를 통한 범주형 동작 (Categorical actions).
|
고유한 형태를 가진 패턴.
|
패밀리 전반에 걸쳐 나타나는 패턴.
|

추론 및 성찰 (Reasoning & Reflection)

아키텍처 (Architecture)	패턴 (Pattern)	참조 (Reference)
Reflection	생성(Generate) → 비판(Critique) → 개선(Refine)	Madaan 2023
Reflexion	에피소드 메모리 (Episodic memory) 내 언어적 성찰 (Verbal reflections)	Shinn 2023
Chain-of-Verification (CoVe)	각 기본 주장(Baseline claim)을 독립적으로 검증	Dhuliawala 2023
Self-Discover	선택(SELECT) → 적응(ADAPT) → 구현(IMPLEMENT) → 해결(SOLVE)	Zhou 2024
Constitutional AI	규칙별 통과/실패(Pass/fail) → 수정(Revise)	Bai 2022

샘플링 및 탐색 (Sampling & Search)

아키텍처 (Architecture)	패턴 (Pattern)	참조 (Reference)
Self-Consistency	N개의 경로를 샘플링하여 다수결 투표 (Majority-vote)	Wang 2022
Tree of Thoughts	사고(Thoughts)에 대한 빔 서치 (Beam search)	Yao 2023
LATS	보상 백업 (Reward backup)을 포함한 MCTS 트리	Zhou 2024
Mental Loop	시뮬레이션(Simulate) → 점수 산정(Score) (결정론적 선택기)	본 리포지토리
Ensemble	N명의 투표자, 가중치 합산 (Weighted aggregation)	본 리포지토리

검색 (Retrieval, RAG)

아키텍처 (Architecture)	패턴 (Pattern)	참조 (Reference)
Agentic RAG	에이전트가 언제 무엇을 검색할지 결정	LangGraph 참조
Corrective RAG (CRAG)	문서 등급 판정, 웹 검색으로 폴백 (Fall back)	Yan 2024
Self-RAG	문서별 성찰 토큰 (Reflection tokens)	Asai 2024
Adaptive RAG	쿼리 복잡도에 따른 사전 라우팅 (Pre-route)	Jeong 2024
GraphRAG	지식 그래프 (KG) + 커뮤니티 요약 (Community summaries)	Microsoft 2024

메모리 (Memory)

아키텍처 (Architecture)	저장 단위 (Stored unit)	참고 문헌 (Reference)
에피소드 + 의미론적 (Episodic + Semantic)	대화 턴 (Conversation turns) + 트리플 (triples)	Park 2023
그래프 메모리 (Graph Memory)	(주어, 술어, 목적어) 트리플 (subject, predicate, object triples)	본 리포지토리 (this repo)
MemGPT	OS 스타일 컨텍스트 (OS-style context) + 아카이브 계층 (archival tiers)	Packer 2023
Voyager	재사용 가능한 Python 기술 (Reusable Python skills) (실제 서브프로세스)	Wang 2023
에이전트 워크플로우 메모리 (Agent Workflow Memory)	상위 수준 워크플로우 레시피 (High-level workflow recipes)	Wang 2024

도구 및 행동 (Tools & Actions)

아키텍처 (Architecture)	패턴 (Pattern)	참고 문헌 (Reference)
도구 사용 (Tool Use)	하나의 도구를 가진 에이전트 (Agent with one tool)	LangChain 참고 문헌 (LangChain reference)
ReAct	사고 (Thought) → 행동 (Action) → 관찰 (Observation)	Yao 2022
계획 (Planning)	분해 (Decompose) → 실행 (execute) → 재계획 (replan)	Wei 2022
계획-실행-검증 (Plan-Execute-Verify, PEV)	단계별 실행 후 검증 (Post-execution verification per step)	본 리포지토리 (this repo)
SWE-Agent	샌드박스 파일 시스템 에이전트 (Sandboxed file-system agent)	Yang 2024
BrowserAgent	실제 Playwright + 안전 게이트 (safety gate)	Anthropic Computer-Use 2024

멀티 에이전트 (Multi-Agent)

아키텍처 (Architecture)	패턴 (Pattern)	참고 문헌 (Reference)
멀티 에이전트 (Multi-Agent)	관리자 + 전문가 (Supervisor + specialists)	LangGraph 참고 문헌 (LangGraph reference)
블랙보드 (Blackboard)	공유 작업 공간 + 에이전트 (Shared workspace + agents)	고전 AI (classical AI)
토론 (Debate)	N개 에이전트 × K개 라운드 (N agents × K rounds)	Du 2023
STORM	다각도 조사 → 기사 작성 (Multi-perspective research → article)	Shao 2024
메타 컨트롤러 (Meta-Controller)	아키텍처 상위의 라우터 (Router over architectures)	본 리포지토리 (this repo)

안전, 라우팅 및 특화 (Safety, Routing & Specialty)

아키텍처 (Architecture)	패턴 (Pattern)	참고 문헌 (Reference)
드라이 런 (Dry-Run)	제안 (Propose) → 시뮬레이션 (simulate) → 승인 게이트 (approval gate)	본 리포지토리 (this repo)
성찰적 메타인지 (Reflexive Metacognitive)	자기 인식 능력 라우팅 (Self-aware capability routing)	본 리포지토리 (this repo)
RLHF 자기 개선 (RLHF Self-Improvement)	다차원 결정론적 점수 산정 + 아카이브 (Multi-dim deterministic scoring + archive)	본 리포지토리 (this repo)
셀룰러 오토마타 (Cellular Automata)	그리드 상의 LLM 규칙 (LLM rules over a grid)	본 리포지토리 (this repo)

제공자 (Provider)	추가 설치 (Install extra)	참고 사항 (Notes)
Nebius (기본값)	[nebius]	Llama-3.3-70B + Qwen3-Thinking; 포함된 데모 실행 시 가장 저렴함
OpenAI	[openai]	모든 아키텍처 작동 가능; 추론 패턴 (reasoning patterns)에 대해 최고 품질 제공
Anthropic	[anthropic]	긴 컨텍스트 (long context)에 강점; 프로덕션 환경의 Computer-Use 구현 시 필수
Groq	[groq]	빠른 추론 (fast inference); 대량의 자기 일관성 (Self-Consistency) 작업에 적합
Ollama (로컬)	[ollama]	API 키 불필요; 도구 호출 (tool calling)은 모델에 따라 다름
Together	[together]	광범위한 모델 카탈로그
Fireworks	[fireworks]	함수 호출 (Function-calling)을 일급 시민 (first-class)으로 지원
Mistral	[mistral]	EU 호스팅 옵션
Google	[google]	Generative AI API를 통한 Gemini 2.x

LLM_PROVIDER 환경 변수를 통해 전환하세요.

• .env 파일의 해당 키를 사용하세요.

코드 변경은 필요 없습니다.

17개의 태스크로 구성된 스위트 (suite)가 모든 아키텍처를 실행하고 결과를 점수화합니다. 가장 최근 실행 결과 (실제 Nebius Llama-3.3-70B 사용, 약 25분 소요, 토큰 비용 약 $1.50):

결과 (Outcome)	아키텍처 (Architectures)
강력한 2/2 또는 3/3 성공	Reflection SelfConsistency SelfDiscover BrowserAgent
시도한 1/1 항목에서 완벽함	21개 추가 항목 — 리더보드(leaderboard) 참조
패턴 적합 실패 (Pattern-fit failures)	산술 연산에서의 LATS (잘못된 형태) · Sally trick에서의 Debate + Ensemble (집단 사고) · 가공되지 않은 사실 회상에서의 Reflexion + AWM (잘못된 메모리 형태)
전체 (Overall)	42개 중 33개 정답 (78%)

전체 리더보드 (Full leaderboard) (태스크별 답변 발췌 포함): docs/benchmarks.md

수행하려는 목적에 따라 선별된 네 가지 학습 경로 (reading orders)가 있습니다.

경로 (Path)	대상 (For)	순서 (Order)
초보자 (Beginner)	멘탈 모델 (Mental model)	Reflection → Tool Use → ReAct → Planning → Self-Consistency
RAG 중심 (RAG-focused)	프로덕션 검색 (Production retrieval)	Agentic RAG → CRAG → Self-RAG → Adaptive RAG → GraphRAG
멀티 에이전트 (Multi-agent)	조정 (Coordination)	Multi-Agent → Blackboard → Debate → STORM → Meta-Controller
안전성 (Safety)	가드레일 (Guardrails)	Dry-Run → Constitutional AI → Reflexive Metacognitive → BrowserAgent (안전 게이트)

pytest -q
283 passed, 37 skipped (env-gated integration), 1 warning in ~30s

Suite	Coverage
Registry sweep	35개 아키텍처 전체 (metadata + instantiate + build)
Pure-Python helpers	Haiku checker, composite scorers, subprocess executor, safety gate, sandbox path
Notebook integrity	35개 노트북 전체 실행 완료, 오류 출력 없음, §9 주석은 실제 캡처된 실행 결과에 맞춰 작성됨
Integration (env-gated)	아키텍처당 하나의 실제 LLM happy-path 테스트, RUN_INTEGRATION=1을 통해 제어됨

Full docs site |
노트북이 내장된 다크 모드 사이트 (첫 배포 후 활성화) |
| Quickstart | 한 줄 명령 설치, 8줄 예제 |
| Switching providers | 기능 매트릭스 (Capability matrix); 환경 변수 하나로 교체 가능 |
| Add your own architecture | 5단계 기여자 레시피 |
| ... |

기여를 환영합니다. 두 가지 경로가 있습니다:

새로운 아키텍처 추가— 5단계 레시피를 따르세요. PR 템플릿에는 결정론적 선택기 (deterministic-picker) 체크리스트가 포함되어 있습니다. 기존 아키텍처 개선— 버그 수정, 프롬프트 튜닝 (prompt tuning), 성능, 채점 루브릭 (scoring rubric). 먼저 이슈 (issue)를 생성하여 범위를 논의하세요.

개발 환경 설정, 코드 스타일, 커밋 메시지 규약 (Conventional Commits — release-please가 CHANGELOG를 자동 생성함)에 대해서는 CONTRIBUTING.md를 참조하세요.

@misc{khan2026agentic,
title = {Agentic Architectures: A Library of 35 Production-Grade Agentic AI Patterns},
author = {Khan, Fareed},
...

MIT — © 2026 Fareed Khan.