bojieli/ai-agent-book 딥다이브
— 한 권으로 읽는 AI Agent 설계·엔지니어링 전서

1프로젝트 한 줄 요약

ai-agent-book은 한 권의 기술서와 그 책의 장(章)별 실습 코드를 함께 공개한 학습용 저장소다. 흔히 트렌딩에 오르는 "무슨무슨 프레임워크/툴"이 아니라, 읽고 따라 짜면서 배우는 교재에 가깝다. 저장소를 열면 세 덩어리가 보인다 — ① book/ 안의 책 전문(마크다운 10개 장 + 引言/后记)과 PDF, ② chapter1/~chapter9/의 실행 가능한 파이썬 예제, ③ 저자가 집필·코딩한 과정을 그대로 남긴 cursor-chats/ 로그 269개.

책의 핵심 주장은 시작부터 못 박혀 있다. "모델이 곧 에이전트다(模型即 Agent)" — 즉 요즘의 강력한 AI 에이전트는 복잡한 규칙 엔진이 아니라, 강력한 LLM에 알맞은 컨텍스트를 넣어 주고 쓸 도구를 쥐여 주면 스스로 판단하며 일을 해낸다는 관점이다. 그래서 책 전체를 관통하는 공식이 Agent = LLM + 컨텍스트 + 도구다. 나머지 모든 장은 이 세 항을 하나씩 깊이 파고든다 — 컨텍스트를 어떻게 채우고(2·3장), 도구를 어떻게 설계하고(4·5장), 이 조합을 어떻게 평가·훈련·진화시키는가(6·7·8장), 그리고 어떻게 멀티모달·멀티에이전트로 확장하는가(9·10장).

2왜 지금 주목받는가

2026년 GitHub 트렌딩은 사실상 "에이전트·스킬 백화점"이다. 끝없이 쏟아지는 Claude Code 스킬 팩, 코딩 CLI, MCP 서버 사이에서 ai-agent-book이 하루 만에 TrendShift Daily #5(모멘텀 659)로 올라온 이유는 결이 다르기 때문이다. 대부분이 "쓸 도구"를 내놓을 때, 이 저장소는 "왜·어떻게 도는지"를 한 권으로 설명하는 교재다. 특히 중화권 개발자 사이에서 "에이전트를 프레임워크 뒤에 숨기지 않고 원리로 이해하고 싶다"는 수요가 이 책을 밀어 올렸다.

주목 포인트 1 — "프레임워크 없이" 손으로 짜 보게 하는 교육 철학

가장 큰 차별점. 에이전트 입문 자료 대부분은 LangChain·LlamaIndex·AutoGen 같은 프레임워크로 "10줄이면 끝!"을 보여준다. 편하지만, 정작 "안에서 무슨 일이 벌어지는지"는 블랙박스로 남는다. 이 책의 1장 예제(chapter1/context/agent.py)는 정반대다 — OpenAI 호환 SDK로 모델을 부르고, 응답에서 도구 호출을 직접 파싱해 실행하고, 결과를 {"role":"tool"} 메시지로 되붙이는 에이전트 루프를 while 문 하나로 펼쳐 보인다. "에이전트가 마법이 아니라 반복문"이라는 깨달음을 주는 방식이다.

주목 포인트 2 — "설계 원리"만이 아니라 "엔지니어링 실전"까지

제목의 뒷부분 工程实践(엔지니어링 실전)이 허명이 아니다. 이 책은 개념 설명에서 그치지 않고, 실무에서 진짜 아픈 문제들을 코드로 다룬다 — KV Cache를 안 깨는 프롬프트 설계(2장), BM25·BGE-M3 임베딩·ANN(annoy/hnswlib)을 직접 붙인 RAG 파이프라인(3장), MCP 서버·비동기 이벤트 구동 에이전트(4장), Claude Code를 통째로 흉내 낸 코딩 에이전트(5장), 그리고 verl·DAPO로 돌리는 강화학습 후속훈련(7장)까지. "논문 요약"이 아니라 "돌아가는 코드"로 배운다.

주목 포인트 3 — 저자가 자기 에이전트로 쓴 "메타적인" 책

저장소에는 cursor-chats/ 폴더에 저자가 집필·코딩하며 나눈 대화 로그 269개가 통째로 들어 있다. 즉 "에이전트를 만드는 사람이, 에이전트(Cursor·Pine)와 협업해 쓴 에이전트 책"이라는 메타적 성격이 그대로 노출된다. 이 로그 자체가 "실무자가 AI와 어떻게 페어링해 대형 프로젝트를 굴리는가"의 생생한 사례집이 된다(단, 여기엔 저자의 로컬 경로 같은 사적 흔적도 남아 있다 — §11 주의).

3기술 스택 전체 지도

이 저장소의 "기술 스택"은 두 겹이다. 겉면은 책을 PDF로 굽는 조판 파이프라인이고, 알맹이는 각 장 예제가 쓰는 파이썬 AI 에이전트 스택이다. 후자가 진짜 학습 대상이다 — 파일 통계부터 보면 .py 494개, .md 673개(책 본문+장별 README), .json 26개, .yml/.yaml 62개, .sh 15개, .js 20개, .ts 3개. 압도적으로 파이썬 중심이되, 9장(실시간 음성)만 Node/Next.js가 섞인다.

알맹이 ① — LLM 연결 (raw SDK, no 프레임워크)

알맹이 ② — 메모리 · RAG (3장, 밑바닥 검색 스택)

알맹이 ③ — 도구 · 스크래핑 · 후속훈련 · 음성

4아키텍처 심화 분석 — 책의 뼈대와 코드의 뼈대

4-1. 책의 중심 해부도 — Agent = LLM + 컨텍스트 + 도구

이 책의 모든 장은 아래 한 장의 그림으로 요약된다. 사용자의 요청이 들어오면, 에이전트는 "컨텍스트를 조립 → 모델 호출 → 도구 실행 → 결과를 컨텍스트에 되먹임"을 반복하며 목표에 도달한다. 각 화살표 옆에 "그걸 다루는 장 번호"를 적어 두면, 책의 목차가 곧 이 루프의 부품 설명서임이 드러난다.

1장 예제로 보는 "루프의 알맹이" (chapter1/context/agent.py 요지)

# 프레임워크 없이, OpenAI 호환 SDK로 에이전트 루프를 직접 구현
messages = [system_prompt, user_message]

while iteration < max_iterations:          # ← 에이전트 루프 = while 하나
    resp = client.chat.completions.create(
        model=MODEL, messages=messages,
        tools=TOOLS, tool_choice="auto",   # 모델이 도구를 스스로 고르게
    )
    msg = resp.choices[0].message

    if msg.tool_calls:                     # ② 응답에 도구 호출이 있으면
        for call in msg.tool_calls:          # ③ 손으로 실행하고
            result = run_tool(call.function.name, call.function.arguments)
            messages.append({"role": "tool",      # 결과를 컨텍스트에 되먹임
                             "tool_call_id": call.id,
                             "content": result})
        continue                            # ① 다시 루프 위로

    if "FINAL ANSWER:" in (msg.content or ""):
        break                               # 끝 신호를 만나면 종료

딱 이게 전부다. 놀랍도록 단순한 이 골격 위에, 1장 예제는 한 발 더 나간다 — ContextMode라는 열거형(FULL / NO_HISTORY / NO_TOOL_CALLS / NO_TOOL_RESULTS)으로 "컨텍스트에서 무엇을 빼면 성능이 얼마나 떨어지는가"를 실험(ablation)하게 만든다. "대화 이력을 지우면?" "도구 실행 결과를 지우면?"을 직접 돌려 보며, 왜 컨텍스트 엔지니어링(2장)이 중요한지를 몸으로 깨닫게 하는 영리한 교보재다.

4-2. 코드의 뼈대 — "챕터 = 지식 계층"이라는 저장소 아키텍처

이 저장소는 소프트웨어 아키텍처라기보다 "난이도·주제별로 쌓아 올린 지식 계층"이다. 아래로 갈수록 앞 장의 개념 위에 새 층을 얹는다 — 1장의 에이전트 루프가 밑돌이고, 2·3장이 "입력(컨텍스트)"을, 4·5장이 "행동(도구)"을, 6·7·8장이 "품질·성장"을, 9·10장이 "확장"을 쌓는다.

4-3. 5장의 야심 — Claude Code를 통째로 재현한 코딩 에이전트

저장소에서 가장 완성도 높은 단일 예제는 5장 coding-agent다. 이건 사실상 Claude Code(터미널 코딩 에이전트)의 축소 재현판이다. anthropic SDK를 쓰고, tools/ 폴더에 16개의 도구 파일을 갖췄다 — 파일 읽기/쓰기/수정(read·write·edit·multi_edit), 탐색(glob·grep·ls), 실행(bash·bash_output·kill_bash), 웹(web_fetch·web_search), 그리고 서브에이전트(task)·할일관리(todo_write)·노트북편집·계획모드(exit_plan_mode)까지.

5디렉토리 · 챕터 구조 해부

저장소를 처음 열면 book/ 하나와 chapter1~chapter9, 그리고 cursor-chats/가 보인다. 규칙은 단순하다 — book/은 읽는 곳, chapterN/은 돌리는 곳. 각 챕터 폴더 안에는 그 장이 다루는 주제별로 독립 실습 프로젝트들이 들어 있고, 대부분 자체 requirements.txt와 README·env.example을 갖는다(저장소 전체 requirements.txt 35개). 아래가 챕터별 하위 프로젝트 지도다.

6학습 포인트

배울 것 1 — 에이전트 루프를 "프레임워크 없이" 짜 보는 경험

가장 값진 학습. 1장 context/agent.py를 열어 while 루프 하나로 에이전트가 완성되는 것을 직접 보고 나면, 이후 어떤 프레임워크(LangChain·AutoGen·CrewAI)를 써도 "아, 안에서 이 루프가 도는구나"가 보인다. 프레임워크는 편의지 마법이 아님을 아는 것 — 이게 초·중급을 가르는 분기점이다.

배울 것 2 — 컨텍스트 ablation으로 "무엇이 성능을 만드는가" 실측

ContextMode(FULL/NO_HISTORY/NO_TOOL_CALLS/NO_TOOL_RESULTS)로 컨텍스트의 각 부분을 하나씩 빼며 성능을 재는 실험. "대화 이력을 지우면 얼마나 멍청해지나?" "도구 결과만 남기면?"을 손으로 돌려 본다. 이건 곧 컨텍스트 엔지니어링의 과학적 방법론 — 감이 아니라 측정으로 프롬프트를 다듬는 습관을 심어 준다.

배울 것 3 — RAG를 "밑바닥부터" — BM25·임베딩·ANN을 손으로

3장은 RAG를 Chroma.from_documents() 한 줄로 넘기지 않는다. BM25(희소 검색)를 직접 구현하고, BGE-M3 임베딩(밀집 검색)을 FastAPI 서비스로 띄우고, annoy vs hnswlib를 나란히 비교한다. "왜 하이브리드 검색을 쓰는가", "ANN이 정확도를 얼마나 희생하는가"를 코드로 체득 — RAG를 진지하게 다뤄야 하는 사람에게 특히 값지다.

배울 것 4 — MCP 서버를 내 손으로 만드는 법

4장 perception-tools는 공식 FastMCP로 @mcp.tool(...) 데코레이터를 붙여 MCP 서버를 직접 구현한다. MCP를 "쓰기만" 해 본 사람이 "만들어" 보는 단계로 넘어가는 다리다. 게다가 예제 도구들이 키 없이 되는 무료 API(DuckDuckGo·Open-Meteo·OpenStreetMap)라 돈 없이도 끝까지 돌려볼 수 있다.

배울 것 5 — 상용 코딩 에이전트의 내부를 열어 보기

5장 coding-agent의 16개 도구를 읽으면, Claude Code·Codex 같은 상용 도구가 "read·edit·bash·grep·task(서브에이전트)" 같은 기본 도구들의 조합임이 드러난다. 특히 순수 파이썬 grep 구현은 "외부 CLI 의존 없이 코드 탐색을 어떻게 짜는가"의 좋은 예. §인덱스의 다른 코딩 CLI 딥다이브(grok-build 등)와 비교하면 학습이 배가된다.

배울 것 6 — 에이전트의 "그 다음" — 평가·RL·자기진화까지

대부분의 입문서가 "에이전트 만들기"에서 끝날 때, 이 책은 6~8장에서 "만든 다음"을 다룬다 — 어떻게 평가(Elo 리더보드·android-world)하고, verl·DAPO로 후속훈련(RL)하고, 경험을 프롬프트로 증류해 자기진화시키는가. 에이전트를 제품 수준으로 운영하려는 사람에게 이 뒷부분이 진짜 차별점이다.

7시스템 · 실행 요구사항

이 저장소는 무거운 GPU를 요구하지 않는다(7장 RL 일부 제외). 대부분은 노트북에서 파이썬과 API 키만 있으면 돌아간다. 목적에 따라 세 경로로 나뉜다.

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

먼저 저장소를 받고 1장 실습 환경을 준비한다.

# 저장소 클론 (PDF가 커서 blob 필터를 걸면 빠름)
git clone --depth 1 --filter=blob:limit=1m \
  https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book/chapter1/context

pip install -r requirements.txt
cp env.example .env        # .env에 SILICONFLOW_API_KEY 등 키 하나 입력

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

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/bojieli/ai-agent-book (책 《深入理解 AI Agent：设计原理与工程实践》 · 李博杰 著)
· TrendShift 카드: trendshift.io/repositories/83370 (Daily #5 · #AI agent · #Programming examples)
· 책 PDF: 저장소 book/深入理解-AI-Agent-李博杰-v1.0.pdf (13.3MB, 중국어)

저장소 안에서 먼저 열 곳
· chapter1/context/agent.py — 프레임워크 없는 에이전트 루프 + ContextMode ablation(§4-1)
· chapter4/perception-tools/ — FastMCP로 만든 MCP 서버(§6 배울 것 4)
· chapter5/coding-agent/tools/ — 코딩 에이전트 도구 16종 + 순수 파이썬 grep
· chapter3/ — RAG 밑바닥 구현 12종(BM25·BGE-M3·annoy/hnswlib)
· book/*.md — 책 본문 10장(중국어), book/build_pdf.sh — PDF 빌드

곁들여 학습(표준·외부)
· MCP 공식: modelcontextprotocol.io — 4장의 손구현 ↔ 업계 표준 잇기
· OpenAI / Anthropic tool use 문서 — 1장 도구 호출의 표준 형식
· verl · DAPO — 7장 강화학습 후속훈련(외부 대형 레포)
· §인덱스의 다른 코딩 에이전트·RAG 딥다이브와 비교 학습(cat-learning · cat-coding-cli · cat-data-rag)