pguso/agents-from-scratch

이 저장소는 12개의 레슨에 걸쳐 단일 에이전트를 점진적으로 구축함으로써 AI 에이전트가 실제로 어떻게 작동하는지 가르치는 교육 프로젝트입니다. 로컬 언어 모델에 대한 간단한 텍스트 입출력 호출로 시작하여, 각 레슨마다 새로운 기능(시스템 프롬프트, 구조화된 출력, 의사결정, 도구, 루프, 메모리, 계획, 원자적 작업, 의존성 그래프, 평가, 텔레메트리)을 추가합니다.

핵심 아이디어는 "마법은 없다"는 것입니다. 모든 것은 명시적이고 읽기 쉬운 코드로 작성됩니다. 계속해서 발전하는 agent.py 파일을 다루며, 별도의 complete_example.py를 통해 각 레슨의 독립적인 예제를 확인할 수 있습니다. 이 프로젝트는 코딩은 할 줄 알지만 에이전트 프레임워크 때문에 혼란을 겪는 개발자를 위해 설계되었습니다. 모든 것은 GGUF 모델을 사용하여 로컬에서 실행됩니다(API 키나 클라우드 불필요).

이 프로젝트의 철학은 에이전트가 인격체가 아니라 루프, 상태, 제약 조건이라는 것입니다. 추론 과정을 숨기거나 모델이 "생각"한다고 주장하는 것을 의도적으로 피합니다. 각 레슨은 이전 레슨을 기반으로 하므로 순서대로 학습하는 것을 권장합니다.

저장소에는 철학 문서, 퀵스타트 가이드, 그리고 메모리, 계획, 도구, 평가, 텔레메트리를 위한 별도의 모듈이 포함된 폴더 구조가 포함되어 있습니다. 이는 프레임워크도, 챗봇 데모도, 프로덕션용 코드도 아니며, 순수하게 학습을 위해 존재합니다.

주요 파일:

• agent/agent.py – 모든 레슨을 거치며 발전하는 메인 Agent 클래스 (프로젝트의 핵심).
• complete_example.py – 각 레슨의 개념을 개별적으로 보여주는 12개의 함수. python complete_example.py로 실행.
• agent/evals.py – 알려진 정상 사례에 대한 회귀 테스트 (레슨 11).
• agent/telemetry.py – 디버깅 및 관측 가능성을 위한 구조화된 로깅 (레슨 12).

커리큘럼 구성: LLM 기초 사용법(레슨 13), 에이전시(의사결정, 도구, 루프 — 레슨 46), 지능(메모리, 계획, 실행 — 레슨 710), 관측 가능성(평가 및 텔레메트리 — 레슨 1112).

요약하자면, 불투명한 프레임워크 없이 AI 에이전트의 메커니즘을 실습을 통해 깊이 이해하고 싶다면, 이 저장소가 로컬 환경에서 처음부터 단계별로 에이전트를 구축하는 방법을 안내해 줄 것입니다.