AI Agents From Scratch – 프레임워크 없이 로컬 LLM으로 AI 에이전트 작동 원리를 처음부터 배우는 저장소

등장 배경
AI 에이전트란?
11단계 학습 경로
아키텍처 진화 패턴
차별점 — 프레임워크 없이 ‘직접 구현’
설치 및 실행
누가 쓰면 좋은가
관련 리소스
라이선스 및 관련 문서

AI Agents From Scratch는 LangChain·LlamaIndex 같은 프레임워크를 쓰기 전에 에이전트가 내부에서 무엇을 하는지 먼저 이해하자는 철학으로 만들어진 오픈소스 학습 저장소다. GitHub: pguso/ai-agents-from-scratch. node-llama-cpp로 로컬 LLM을 구동하며, 기본 프롬프트 호출부터 ReAct 루프·AoT(Atom of Thought) 계획 에이전트까지 11개 예제를 단계적으로 제공한다.

등장 배경

에이전트 프레임워크가 빠르게 발전하면서 “왜 프레임워크가 이런 설계를 선택했는가”를 모르는 채 사용하는 경우가 늘었다. AI Agents From Scratch는 프레임워크를 걷어내고 로컬 LLM + 순수 코드로 동일한 패턴을 구현해, 함수 호출(function calling)·메모리·추론 루프의 실제 작동 방식을 노출한다.

AI 에이전트란?

저장소는 에이전트를 다음 공식으로 정의한다:

AI Agent = LLM + System Prompt + Tools + Memory + Reasoning Pattern
           ─┬─   ──────┬──────   ──┬──   ──┬───   ────────┬────────
            │          │           │       │              │
         Brain      Identity    Hands   State         Strategy

11단계 학습 경로

#	예제	핵심 개념
1	Intro	LLM 로딩·프롬프트·응답 사이클
2	OpenAI Intro (선택)	호스팅 LLM 호출, 비용·프라이버시 트레이드오프
3	Translation	시스템 프롬프트로 에이전트 역할 특화
4	Think	논리 추론 설정, 외부 도구가 필요한 한계 이해
5	Batch	병렬 컨텍스트 시퀀스로 처리량 최적화
6	Coding	스트리밍 응답·토큰 예산 관리
7	Simple Agent	함수 호출(function calling) — 텍스트 생성이 에이전시로 전환되는 지점
8	Simple Agent with Memory	세션 간 장기 기억·상태 관리
9	ReAct Agent	Reason → Act → Observe 반복 루프, 다단계 도구 사용
10	AoT Agent	Atom of Thought 계획: 의존성 있는 원자 연산을 JSON 플랜으로 결정론적 실행
11	Error Handling	오류 분류·재시도·타임아웃·폴백·에이전트 수준 내결함성

아키텍처 진화 패턴

Simple:   User → LLM → Response
Tool:     User → LLM ⟷ Tools → Response
Memory:   User → LLM ⟷ Tools → Response
                 ↕
               Memory
ReAct:    User → LLM → Think → Act → Observe
                 ↑      ↓      ↓      ↓
                 └──────┴──────┴──────┘
                     Iterate until solved

차별점 — 프레임워크 없이 ‘직접 구현’

항목	AI Agents From Scratch	LangChain / LlamaIndex
목표	원리 이해	빠른 프로덕션 적용
추상화	없음 (순수 코드)	높음
LLM	로컬 (node-llama-cpp)	클라우드·로컬 모두
언어	Node.js (Python 버전 별도)	Python
활용	학습·기초 쌓기	실제 서비스 개발

설치 및 실행

# Node.js 18+, 8GB RAM 이상 필요
git clone https://github.com/pguso/ai-agents-from-scratch.git
cd ai-agents-from-scratch
npm install

# models/ 폴더에 GGUF 모델 배치 후
node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

모델은 Hugging Face GGUF 허브에서 다운로드한다. 상세 지침은 저장소의 DOWNLOAD.md 참고.

누가 쓰면 좋은가

에이전트 프레임워크 입문 전 개발자: 블랙박스 없이 기초를 다지고 싶을 때
Node.js 백엔드 개발자: Python 없이 LLM·에이전트 실험 환경 구축
교육·강의 목적: 단계적 예제로 에이전트 패턴을 가르칠 때

라이선스 및 관련 문서

라이선스: 교육 목적 자유 사용·수정
관련 토픽: mini-coding-agent, local-slm, agent-skills

Like?

AI Sparkup