FareedKhan-dev/all-agentic-architectures: 모든 에이전트 아키텍처 라이브러리 및 교과서
요약
모든 주요 에이전트 AI 패턴을 실행 가능한 Python 클래스로 패키징한 라이브러리이자 교과서입니다. LangGraph를 기반으로 구축되었으며, 다양한 LLM 제공자를 지원하고 결정론적 선택기 패턴을 통해 LLM의 불확실성을 제어합니다.
핵심 포인트
- 35개의 주요 에이전트 아키텍처를 통일된 인터페이스로 제공
- LangGraph 기반의 상태 머신 및 멀티 프로바이더 지원
- 결정론적 선택기 패턴을 통한 LLM 출력의 안정성 확보
- 실제 실행 결과에 기반한 Jupyter Notebook 및 벤치마크 포함
라이브러리이자 살아있는 교과서 — 실제 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] | 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.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Trending Jupyter Notebook (weekly)의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기