30개 이상의 오픈소스 프레임워크 코드베이스에서 본 현대 AI 에이전트 구축 방법

현대 AI 에이전트는 어떻게 구축되는가 — 30개 이상의 오픈소스 프레임워크 코드베이스를 통해.

LangGraph와 CrewAI 중 무엇을 사용해야 할까? OpenClaw는 어떤 원리로 작동하는 걸까? Claude Code는 왜 컨텍스트를 92%까지 압축할 수 있을까? 컨텍스트가 25% 채워질 때 에이전트를 망치는 '컨텍스트 부패(context rot)'를 어떻게 막을 수 있을까?

이 가이드가 이 질문들과 200가지 이상의 질문에 답합니다.

30개 이상의 AI 에이전트 프레임워크에서 추출한 패턴, 아키텍처, 구현 세부 사항들을 체계적으로 모았습니다. 실제 소스 코드, 시스템 프롬프트, 압축 로직을 읽고 분석하여 정리했습니다.

의견이 아닙니다. 튜토리얼도 아닙니다. 프로덕션 환경에서 실제로 구동되는 코드베이스에서 추출한 문서화된 패턴일 뿐입니다.

2026년 현재 대부분의 에이전트 지식은 피상적인 블로그 게시물에 있거나, 아무도 읽을 시간이 없는 소스 코드 깊숙한 곳에 묻혀 있습니다. 저희는 OpenClaw, Claude Code, LangGraph, CrewAI, Hermes Agent 등 25개 이상의 코드베이스를 검토하여 이들이 실제로 어떻게 작동하는지 — 에이전트 루프, 프롬프트 조립 방식, 컨텍스트 관리, 메모리 시스템, 도구 아키텍처 등을 문서화했습니다.

• LangGraph vs CrewAI vs PydanticAI — 무엇에 어떤 것을 사용해야 할까?
• OpenClaw의 SOUL.md / AGENTS.md 패턴은 어떻게 작동하며 왜 모두가 이를 따라 하는 걸까?
• 에이전트가 오래 실행될수록 성능이 떨어지는 이유는 무엇일까? (컨텍스트 부패, 그리고 이를 방지하는 12가지 방법)
• MCP 서버들이 제 컨텍스트 창의 72%를 차지하고 있어요 — 도구 확산(tool sprawl)을 어떻게 해결할까요?
• 에이전트를 하나 쓸까요, 여러 개 쓸까요? 멀티 에이전트가 실제로 도움이 되는 경우는 언제일까?
• Claude Code는 압축 처리를 어떻게 할까? 무엇이 살아남고 무엇이 버려지는 걸까?
• 실제 에이전트 루프 코드는 어떤 형태일까? 정말 단순히 while 루프에 불과할까?
• 마크다운 형식의 스킬 vs. 컴파일된 도구 — 최고 프레임워크들은 무엇을 사용할까?
• Hermes Agent는 시간이 지남에 따라 어떻게 스스로를 개선하는 걸까? (에피소드 메모리 + 자가 진화)
• 프로덕션 환경에서 필요한 최소 기능 에이전트 아키텍처는 무엇일까?

Part I-II 에이전트 루프 (Agent Loops)
코드와 함께 살펴볼 8가지 루프 변형: ReAct, Plan+Execute, Reflection, Compaction, Code-as-Action, Event-Driven, Graph State Machine, Heartbeat. 종료(Termination). 오류 복구(Error recovery).

Part III 시스템 프롬프트 (System Prompts)
조립 패턴(Assembly patterns). SOUL.md / AGENTS.md 분리. 스킬 카탈로그(Skill catalogs). 안티패턴(Anti-patterns).

Part IV 컨텍스트 관리 (Context Management)
Claude Code와 OpenClaw에서 가져온 실제 프롬프트로 살펴본 6가지 압축 전략(compaction strategies). 트리거 전략(Trigger strategies). 압축을 거쳐 살아남는 것들.

Part IV-B 컨텍스트 로트 (Context Rot)
3가지 메커니즘. 12가지 방어책. 40-60% 규칙. 에이전트 인지 압축기(Agent Cognitive Compressor). 성능 저하 측정.

Part V 메모리 (Memory)
5단계 계층 구조. 파일 기반 대 벡터 기반 대 관찰 기반 대 에피소드 기반. 비교한 8가지 프레임워크 구현체.

Part VI 도구 (Tools)
MCP. 코드-액션(Code-as-action). 마크다운 형태의 스킬(Skills-as-markdown). JIT 로딩(JIT loading). 도구 확산(Tool sprawl) 문제(72% 컨텍스트 소모). 7가지 해결책. 점진적 공개(Progressive disclosure). SDP.

Part VII 오케스트레이션 (Orchestration)
6가지 멀티 에이전트 패턴. 상태 전달(State passing). A2A 프로토콜(Agent-to-Agent protocol). 규모 및 토폴로지 가이드라인.

Part VIII 계획 수립 (Planning)
5가지 전략. 리플렉션 루프(Reflection loops). Cline의 Plan/Act 골드 스탠더드.

Part IX-XI 인간 개입, 상태, 보안 (Human-in-the-Loop, State, Security)
권한 모델(Permission models). 체크포인팅(Checkpointing). 영속적 실행(Durable execution). 샌드박싱(Sandboxing). 프롬프트 주입 방어(Prompt injection defense).

Part XII-XIII 테스트 및 배포 (Testing, Deployment)
벤치마크(Benchmarks). 평가 전략(Eval strategies). 비용 최적화. 관찰 가능성(Observability). 게이트웨이 아키텍처(Gateway architecture).

Part XIV 종합 (Synthesis)
참조 아키텍처(Reference architecture). 스택 선택을 위한 의사 결정 프레임워크.

발견한 비명확한 점들:

100줄 분량의 에이전트가 SWE-bench에서 74% 점수를 얻었습니다. 루프(Loop)를 구현하는 것은 쉬운 부분입니다. 중요한 것은 컨텍스트 조립(Context assembly), 도구 설계(tool design), 그리고 메모리입니다.컨텍스트 품질은 창(window) 채움률이 100%가 아닌, 약 25%부터 저하되기 시작합니다. 테스트된 모든 최첨단 모델에서 이러한 현상이 나타납니다 (Chroma Research, 18개 모델).도구 설명만으로 세 개의 MCP 서버가 200K 토큰 중 143K를 소비했습니다. 에이전트가 단 하나의 사용자 메시지를 읽기도 전에 발생한 일입니다. 도구세트가 비대해지면(bloated toolsets) 도구 선택 정확도가 43%에서 14%로 떨어집니다.개성과 운영 지침은 별도의 파일로 분리되어야 합니다. OpenClaw, Claude Code, 그리고 Hermes는 이 점에 대해 독립적으로 수렴했습니다.서브 에이전트를 사용해야 하는 주된 이유는 병렬성(parallelism)이 아니라 컨텍스트 격리(context isolation)입니다. Anthropic은 90.2%의 개선을 측정했습니다.**마크다운 파일로 정의된 스킬(코드 아님)**이 Claude Code, OpenClaw, 그리고 Cline 전반에 걸쳐 지배적인 확장성 패턴입니다. 점진적 3단계 로딩(Progressive 3-tier loading)은 토큰 비용을 94% 절감합니다.컨텍스트의 끝 부분 근처에 지침을 재주입하는 것은 컨텍스트가 커짐에 따라 시스템 프롬프트의 영향력이 약해지는 '지침 중심화(instruction centrifugation)' 현상을 방지합니다.

Coding agent → Claude Agent SDK, Cline, Roo Code
Visual / no-code → n8n, Dify, Langflow
Personal assistant → OpenClaw, Hermes Agent
... 

├── README.md
├── COMPREHENSIVE_AGENT_ENGINEERING_GUIDE_2026.md ← 가이드 (약 5,000줄)
├── COMPREHENSIVE_AGENT_ENGINEERING_GUIDE_2026.pdf ← PDF 버전
... 

기여 환영합니다. CONTRIBUTING.md를 참조하세요.

수정 사항, 새로운 프레임워크 분석, 발견한 프로덕션 패턴 등 이 자료를 더 정확하고 유용하게 만드는 모든 것이 좋습니다.

Dmitriy Vasilyev · AI Enthusiast