hello-agents 딥다이브
— Datawhale의 "Agent 원년" 교과서

1한줄 요약

2왜 지금 주목받는가

① "2025년 = Agent 원년"이라는 시점성

2024년이 "백모대전(百模大战)"의 해 — 즉 더 큰 모델을 만드는 경쟁의 해였다면, 2025년부터는 그 모델을 도구로 묶어 일을 시키는 에이전트가 본격 화두가 됐다. 이 책은 그 흐름에 딱 맞춰 등장했고, 27.5k 별을 쓸어담는 중. 별 증가 그래프가 거의 수직이다(레포 README의 Star History 그래프 참고).

② 이론파 자료가 부족했던 자리를 정확히 채운다

지난 1년 사이 에이전트 자료가 폭증했지만, 대부분이 "Dify로 챗봇 만들기" 같은 툴 사용법 위주였다. 원리·역사·내부 구조를 동시에 정리한 자료는 드물었다. hello-agents는 1장에서 에이전트의 정의·역사부터 시작해서, 12장에서 평가 방법론까지 다룬다 — 책 한 권의 완결성을 가진다.

③ "AI Native Agent" vs "워크플로우 Agent" 분리

이 책의 메시지는 명확하다: 에이전트는 두 종류다.

책의 90%는 두 번째 — 진짜 LLM이 핸들을 잡는 에이전트를 다룬다. 첫 번째도 5장에서 한 번 짚고 가지만, 이건 "전체 그림을 알기 위함"이지 메인이 아니다.

④ 자체 프레임워크 HelloAgents까지 제공

책의 7장에서는 OpenAI API만으로 자기 프레임워크를 만들게 한다. 이 프레임워크는 별도 레포 jjyaoao/HelloAgents로 1.5k 별을 따로 받고 있고, 지금은 v1.0.0 — ToolResponse 프로토콜, 회로 차단기(CircuitBreaker), 컨텍스트 엔지니어링, 세션 영속화, 서브에이전트 등 16개 프로덕션 기능까지 진화했다. 책으로 시작해서 실전 도구로 자란 살아있는 프로젝트.

⑤ 한국 입장에서: 중국어 → 한국어 번역해 공부할 가치

책 본문이 중국어라 진입 장벽이 있지만, 영문 README도 있고 코드와 다이어그램이 풍부해 번역기 + 코드 따라치기로 충분히 학습 가능하다. 영어 자료 위주인 한국 개발자에게는 오히려 중국 AI 커뮤니티의 사고 흐름을 엿볼 수 있는 보너스. (예: Coze, Dify가 중국 제품이라 5장에서 더 깊이 다뤄진다.)

3기술 스택 전체 지도

코어 언어 · 런타임

LLM 어댑터 (HelloAgents 프레임워크 기준)

책 7장에서 만드는 자체 프레임워크는 OpenAI 호환 인터페이스 1개를 표준으로 삼고, 모든 LLM 제공자를 그 형태로 흡수한다.

책에서 다루는 외부 프레임워크

"바퀴 만들기"가 메인이지만, 6장에서는 기존 바퀴들을 광범위하게 비교한다:

RAG · 메모리 · 임베딩 스택

8장에서 메모리 시스템을 다룰 때 등장하는 라이브러리들:

• 임베딩: OpenAI text-embedding-3-small/large, Qwen Embedding, BGE-M3 (중국 BAAI)
• 벡터 DB: Chroma, Milvus, FAISS — 책에서는 가벼운 Chroma로 시작
• 리랭커: BGE-Reranker, Cohere Rerank
• 긴 컨텍스트 압축: ObservationTruncator (자체 구현), 토큰 카운터로 자동 잘림

11장 Agentic-RL 훈련 스택

11장은 책에서 가장 무거운 챕터 — LLM을 직접 훈련시킨다.

13~15장 응용 사례 스택

4아키텍처 심화 분석

ReAct — 모든 에이전트 패턴의 출발점

4장에서 가장 먼저 배우는 패턴. "Reasoning + Acting"의 줄임말이다. 2022년 프린스턴-구글 논문에서 처음 제안됐고, 그 후 거의 모든 에이전트의 뼈대가 됐다.

코드로 보면 이렇게 단순한 무한 루프 + 종료 조건이다:

while not done:
    thought = llm.think(history)        # 1. 다음 행동 결정
    action  = llm.parse_action(thought) # 2. 도구 + 인자 추출
    obs     = tools[action.name](**action.args)  # 3. 도구 실행
    history.append({thought, action, obs})        # 4. 기록
    if "Final Answer" in thought:
        done = True

Plan-and-Solve — 큰 문제는 먼저 쪼개자

ReAct는 한 번에 한 걸음만 본다. 복잡한 문제(예: "여행 계획 짜줘")에서는 길을 잃기 쉽다. Plan-and-Solve는 "먼저 전체 계획을 세우고 → 단계별로 실행"하는 패턴이다.

전체 흐름:
1. Planner LLM:  "여행 계획"을 7단계로 쪼갠다
   ├─ 1. 여행 날짜 확정
   ├─ 2. 항공권 검색
   ├─ 3. 호텔 예약
   └─ ...
2. Executor LLM: 각 단계를 ReAct 루프로 실행
3. 모든 단계 완료 후 결과 종합

Reflection — 자기가 한 일을 되돌아본다

ReAct + Plan-and-Solve는 "앞으로 가는 힘"이지만, Reflection은 "뒤를 돌아보는 힘"이다. 한 사이클 끝나면 LLM이 "내가 한 일이 맞나? 더 나은 방법은 없었나?"를 스스로 검토한 뒤 다음 시도를 한다. 시행착오로 배우는 방식.

HelloAgents 프로덕션 프레임워크 — 16개 핵심 능력

책의 7장에서 시작한 자체 프레임워크가 jjyaoao/HelloAgents v1.0.0까지 진화하면서 다음 16개를 갖췄다. 이 모든 게 OpenAI API + Python 표준 라이브러리만으로 구현돼 있다.

5디렉토리 구조 해부

hello-agents (메인 교재 레포)

HelloAgents (jjyaoao/HelloAgents, 별도 레포)

6학습 포인트 (기술별)

① ReAct 직접 구현 (4장)

LangChain의 create_react_agent()를 호출하는 건 누구나 한다. 하지만 그 안에서 무슨 일이 벌어지는지 아는 사람은 적다. 이 책은 약 100줄짜리 ReAct를 처음부터 짜게 시킨다. 한 번 손으로 짜본 사람은 LangGraph 그래프를 봐도 곧바로 매핑할 수 있다.

실습 아이디어: 자기 도메인용 ReAct를 만들어보기. 예) 주가 데이터 조회 도구 + 계산 도구 + 검색 도구를 묶어 "워런 버핏 스타일 분석" 에이전트.

② 컨텍스트 엔지니어링 (9장)

LLM의 컨텍스트 윈도우가 길어졌어도, 긴 = 비싸다 + 느리다 + 헷갈린다. 9장은 이걸 다룬다:

• 대화 이력의 어떤 부분을 잘라낼 것인가 (sliding window vs recency vs LLM 요약)
• 도구 결과(observation)가 너무 길 때 어떻게 자를 것인가
• 시스템 프롬프트 최적화 — 토큰 절약 + 효과 유지
• "카드 게임" 비유: 매 턴 손에 든 카드를 어떻게 정리할 것인가

실습 아이디어: 1만 토큰을 받아야 답할 수 있는 질문을, 500 토큰 컨텍스트만으로 풀어내기. 보조 검색 + 요약을 어떻게 짜야 할까?

③ 메모리 시스템 (8장)

에이전트가 "어제 사용자가 한 말"을 기억하려면 메모리가 필요하다. 책은 3종을 다룬다:

실습 아이디어: 텔레그램 봇 + Chroma로 개인용 일기 비서 만들기. 매일 일기 던지면 임베딩 저장하고, "작년 봄에 뭐 했지?"라고 물으면 검색해서 답한다.

④ MCP·A2A·ANP 프로토콜 (10장)

2024~2025년 사이 에이전트 통신 프로토콜이 폭증했다. 책은 3개를 비교한다:

실습 아이디어: 자기 MCP 서버 만들어서 Claude Desktop에 연결하기. 책 README의 Extra05-Agent Skills와 MCP 대비 해독 부록까지 읽으면 Skills와의 차이까지 잡힌다.

⑤ Agentic-RL (11장)

지금까지는 "프롬프트로 LLM을 조종"하는 길이었다면, 11장은 모델 자체를 학습시켜서 에이전트로 만든다. SFT → DPO → GRPO로 이어지는 정통 RL 파이프라인. DeepSeek-R1과 같은 결을 따른다.

실습 아이디어: Qwen2.5-0.5B 같은 작은 모델을 가져다 LLaMA-Factory로 SFT, 그 후 GRPO로 도구 사용을 강화 학습. 노트북 GPU 한 장으로도 된다.

⑥ 사이버 타운 — Generative Agents 재현 (15장)

2023년 Stanford-Google이 발표한 Smallville 논문(25명의 LLM 캐릭터가 자율적으로 마을에서 사는 시뮬레이션)을 다시 만든다. 프런트엔드는 Godot 4.5 2D 픽셀 게임 엔진, 백엔드는 FastAPI(Python). 메모리 + 계획 + 반성 + 환경 인지 — 책의 모든 기술이 한 번에 모인다. 졸업작품 같은 챕터.

7시스템 요구사항

최소 (대부분의 챕터)

• Python 3.10+ — uv 또는 conda 가상환경 권장
• OpenAI 호환 API 키 1개 — DeepSeek(저렴), 무료 LLM 라우터(tashfeenahmed/freellmapi), 또는 Ollama 로컬
• 로컬 16GB RAM, 디스크 20GB
• Jupyter Notebook (VS Code 또는 Cursor 등 IDE 호환)

권장 (8장 RAG, 14장 딥리서치)

• 32GB RAM — 벡터 DB Chroma + 임베딩 모델 동시 구동
• SSD 500GB — 데이터 + 벡터 인덱스
• 인터넷 — 검색 도구(Tavily, Serper, Bing API 등)

필요 (11장 Agentic-RL 훈련)

• NVIDIA GPU 16GB 이상 — RTX 4070 Ti / 4090 / A100
• CUDA 12.x + PyTorch 2.x
• WSL2 (Windows) 또는 Linux 추천
• 또는 클라우드 GPU 임대: AutoDL, Lambda Labs, RunPod — 시간당 1~3달러

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• 📚 메인 레포: github.com/datawhalechina/hello-agents
• 🌐 온라인 책: datawhalechina.github.io/hello-agents
• 🤖 HelloAgents 프레임워크: github.com/jjyaoao/HelloAgents
• 📥 PDF 다운로드: GitHub Releases
• 🐹 Go 포팅: HelloAgents-go
• 📡 ReAct 논문: arxiv.org/abs/2210.03629
• 🧠 Generative Agents 논문(Stanford): arxiv.org/abs/2304.03442
• 🪙 MCP 공식 문서: modelcontextprotocol.io
• 🇨🇳 Datawhale 메인: github.com/datawhalechina