pguso/ai-agents-from-scratch

Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.

이 프로젝트는 무엇인가요?

pguso/ai-agents-from-scratch는 인기 있는 에이전트 프레임워크를 전혀 사용하지 않고 AI 에이전트를 처음부터 구축하는 방법을 가르치는 실습형 튜토리얼 저장소입니다. 대신 node-llama-cpp라는 라이브러리를 통해 자신의 컴퓨터에서 실행되는 로컬 언어 모델(LLM)을 사용합니다.

핵심 아이디어는 "만들면서 배우기"입니다. 원시 LLM 호출로 시작하여 기능(도구, 메모리, 추론 패턴)을 점차 추가하여 현대 에이전트 프레임워크가 하는 일을 재현합니다. 이를 통해 왜 그 프레임워크가 그러한 설계 선택을 하는지 이해하게 됩니다.

무엇을 배우게 되나요?

README에 따르면 다음을 이해하게 됩니다:

LLM이 기본 수준에서 어떻게 작동하는지
에이전트가 실제로 무엇인지(LLM + 도구 + 패턴)
서로 다른 에이전트 아키텍처가 어떻게 작동하는지
프레임워크가 특정 설계 선택을 하는 이유

핵심 정의

README는 AI 에이전트에 대한 간단한 공식을 제공합니다:

AI 에이전트 = LLM + 시스템 프롬프트 + 도구 + 메모리 + 추론 패턴

LLM = "뇌"(언어 모델)
시스템 프롬프트 = "정체성"(행동을 형성하는 지침)
도구 = "손"(모델이 호출할 수 있는 함수)
메모리 = "상태"(영구 정보)
추론 패턴 = "전략"(단계별로 생각하는 방법)

학습 경로(15개 예제, 순서대로)

각 예제는 이전 예제를 기반으로 합니다. README는 다음과 같이 나열합니다:

소개 — 로컬 LLM 로드 및 실행; 기본 프롬프트/응답 주기.
OpenAI 소개 (선택 사항) — GPT-4와 같은 호스팅 LLM 호출; 온도, 토큰 사용량, 비용 대 제어, 데이터 프라이버시에 대해 배웁니다.
번역 — 시스템 프롬프트를 사용하여 에이전트의 동작을 전문화하고 출력 형식을 제어합니다.
생각 — 논리적 추론을 위해 LLM을 구성; 순수 LLM 추론의 한계와 외부 도구를 사용해야 할 때를 배웁니다.
배치 — 성능을 위해 여러 요청을 병렬로 처리합니다.
코딩 — 실시간으로 토큰 단위로 응답을 스트리밍; 토큰 예산을 관리합니다.
간단한 에이전트 — 큰 단계: 함수 호출. LLM에 사용 여부를 결정할 수 있는 도구를 제공합니다. README는 이를 "텍스트 생성이 에이전시가 되는 곳"이라고 부릅니다.
메모리가 있는 간단한 에이전트 — 세션 간에 사실과 선호도를 유지; 장기 메모리 관리.
ReAct 에이전트 — 추론 → 행동 → 관찰 루프: 자기 수정을 통한 반복적 문제 해결. README는 이를 "현대 에이전트 프레임워크의 기초"라고 부릅니다.
AoT 에이전트(생각의 원자) — 작업을 종속성이 있는 원자적 계획 단계로 분해하고, 구조화된 JSON으로 출력하며, 결정적으로 실행합니다.
오류 처리 — LLM + 도구 시스템을 탄력적으로 만듭니다: 유형화된 오류, 시간 초과, 백오프가 있는 재시도, 우아한 폴백.
생각의 나무 — 여러 후보 다음 행동을 생성하고, 분기를 순위화하고 가지치기(빔 서치), 승리 경로를 검증합니다.
생각의 그래프 — 추론을 DAG(방향성 비순환 그래프)로 모델링: 병렬 소스 추출 → 병합 규칙 → 최종 초안. 생성 전에 충돌을 해결합니다.
생각의 사슬 — 고위험 결정을 명시적이고 감사 가능한 추론 단계로 분할(예: 정책 적용 전 사실만 추출).
도구 라우팅(임베딩) — 도구 설명에 대한 임베딩을 사전 계산하고, 사용자 메시지를 유사도로 점수화하고, 상위 k개 도구만 모델에 전달하여 컨텍스트를 절약합니다.

예제 구조

각 예제 폴더에는 세 개의 파일이 포함됩니다:

<name>.js — 작동하는 코드
CODE.md — 단계별 코드 설명(줄별 분석)
CONCEPT.md — 높은 수준의 개념, 아키텍처 패턴, 실제 응용, 간단한 다이어그램

README는 완전한 이해를 위해 두 파일을 모두 읽을 것을 권장합니다.

실행 요구 사항

Node.js 18+
최소 8GB RAM(16GB 권장)
모델 다운로드 및 ./models/ 폴더에 배치(자세한 내용은 DOWNLOAD.md)

npm install로 설치한 후 다음과 같이 예제를 실행합니다:

node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

동반 웹사이트

https://agentsfromscratch.com에 해당 사이트가 있습니다. 이는 저장소의 대체가 아니라, 왜 각 예제가 존재하는지 설명하고 학습 경로를 시각화하는 개념적 동반자입니다. 권장 워크플로: 코드 실행 및 연구에는 GitHub를 사용하고, 정신 모델 및 설명에는 웹사이트를 사용합니다. README는 다음과 같이 말합니다: "사이트를 지도로, 이 저장소를 지형으로 생각하세요."

헬퍼 유틸리티

PromptDebugger(helper/prompt-debugger.js)가 있어 LLM이 정확히 무엇을 보는지(시스템 프롬프트, 함수 정의, 대화 기록, 컨텍스트 상태) 표시합니다. 디버깅에 유용합니다.

참조된 추가 리소스

node-llama-cpp — 로컬 추론에 사용되는 라이브러리
Hugging Face — GGUF 모델용 모델 허브
GGUF 형식 — 로컬 추론용 양자화 모델

라이선스 및 기여

README는 이를 교육 리소스라고 명시합니다: "학습을 위해 필요에 따라 사용 및 수정하세요." 기여를 환영합니다: 문서 개선, 새로운 예제 패턴, 버그 수정, 또는 구축한 것을 공유.

저자

이 저장소는 pguso(Patric Gutersohn)가 만들었으며, AI 워크플로, 컨텍스트 엔지니어링, RAG, 로컬/프로덕션 LLM 프로젝트에 대한 프리랜스/계약 작업을 제공합니다(연락처: pguso@gmx.de).

결론: 프레임워크를 사용하기 전에 AI 에이전트의 내부에서 실제로 일어나는 일을 진정으로 이해하고 싶다면, 이 저장소는 자신의 머신에서 한 번에 하나의 기능씩 직접 구축하는 과정을 안내합니다.