hardness1020/learn-agent-architecture

해결하는 문제

AI 모델은 추론 능력은 갖추고 있지만, 스스로 작업을 수행하거나 상태를 유지하거나 워크플로우를 관리할 수는 없습니다. 이 프로젝트는 LLM을 도구 실행, 메모리 관리, 복잡한 작업 조정이 가능한 기능적이고 자율적인 에이전트로 변환하기 위해 LLM을 감싸는 필수 소프트웨어 인프라인 '하네스'의 원리를 명확히 설명합니다.

작동 방식

이 저장소는 에이전트 아키텍처를 24개의 점진적이고 독립적인 섹션으로 나눕니다. 각 섹션은 문제 정의, 메커니즘 설명, 실제 시스템에서의 구현 방식, 일반적인 장애 모드 식별이라는 일관된 구조를 따릅니다. 코드는 누적 방식으로 제공되므로, 제공된 데모를 실행하고 섹션 간의 차이점을 비교하여 에이전트 루프에 새로운 기능 계층이 어떻게 추가되는지 정확히 확인할 수 있습니다.

대상 독자

현대 AI 에이전트의 메커니즘을 이해하고자 하는 개발자와 엔지니어를 위한 자료입니다. 자신만의 에이전트를 구축하든, Claude Code 나 SWE-agent 와 같은 기존 시스템이 어떻게 작동하는지 이해하려 하든, 이 저장소는 에이전트 설계를 마스터하기 위한 명확한 코드 중심의 로드맵을 제공합니다.

주요 특징

• 누적 학습: 각 섹션은 이전 섹션을 기반으로 구축되어, 단순한 루프가 어떻게 복잡한 자율 시스템으로 진화하는지 확인할 수 있습니다.
• 실제 사례: Claude Code, Hermes Agent, deepseek-harness 와 같은 인기 있는 에이전트 프레임워크를 연구하여 이론적 개념을 프로덕션 수준의 코드로 구체화합니다.
• 실행 가능한 데모: 모든 섹션에는 src/ 폴더가 포함되어 있어 로컬에서 코드를 실행하고 에이전트의 동작을 실시간으로 관찰할 수 있습니다.
• 포괄적인 범위: 기본적인 도구 실행 및 권한 제어부터 서브 에이전트, 메모리 하위 시스템, 그래프 기반 제어 흐름과 같은 고급 주제까지 모두 다룹니다.