English | 中문 | Tiếng Việt | தமிழ்

본 저장소는 《AI Agent 심층 이해: 설계 원리와 엔지니어링 실무 (Understanding AI Agents: Design Principles and Engineering Practice)》 도서의 오픈 소스 메인 저장소로, 도서 전체 본문과 부속 예제 코드를 포함하고 있습니다. 도서 전체 본문, 삽화 및 부속 실험 코드는 모두 오픈 소스로 공개되어 있으니, 실험을 직접 실행해 보시고 issue 및 PR을 남겨주시기 바랍니다.

도서 전체는 다양한 언어 버전을 제공합니다:

중문 PDF (원본): book/深入理解-AI-Agent-李博杰-v1.1.pdf

영문 PDF (커뮤니티 기여 번역, by @nsdevaraj): book-en/AI-Agents-in-Depth-Bojie-Li-v1.1.pdf

타밀어 PDF (커뮤니티 기여 번역, by @nsdevaraj): book-ta/AI-Agents-in-Depth-Bojie-Li-v1.1-ta.pdf

베트남어 PDF (커뮤니티 기여 번역, by @toanalien): book-vi/AI-Agents-in-Depth-Bojie-Li-v1.1-vi.pdf

중문 본문과 컴파일된 PDF는 book/ 디렉토리에 위치합니다.

목차; 영문, 타밀어 및 베트남어 번역은 커뮤니티 기여로 이루어졌으며, 각각 book-en/, book-ta/, book-vi/ 디렉토리에 위치하며 내용은 중문 원본보다 늦을 수 있습니다:

본문 소스 코드: book/introduction.md (서론), book/chapter1.md ~ book/chapter10.md (제1장~제10장), book/afterword.md (후기) -
직접 컴파일: pandoc, xelatex, ElegantBook 문서 클래스 및 관련 폰트를 설치한 후, cd book && bash build_pdf.sh를 실행하세요.

도표는 book/gen_*_figs.py에 의해 생성되어 book/images/에 저장되며, 레이아웃 세부 사항은 book/preamble.tex 및 book/*.lua를 참조하십시오.

도서 전체는 핵심 공식인 **Agent = LLM + 컨텍스트 (Context) + 도구 (Tool)**를 중심으로 전개되며, 10장의 내용은 다음과 같습니다:

제 1 장 · Agent 기초 지식: "모델이 곧 Agent이다"라는 새로운 패러다임에서 출발하여, Agent = LLM + 컨텍스트 + 도구라는 핵심 공식을 구축하고, 모델 이외의 모든 엔지니어링 능력이 진정한 경쟁력임을 나타내는 Harness 엔지니어링을 소개합니다.
제 2 장 · 컨텍스트 엔지니어링 (Context Engineering): 컨텍스트는 Agent의 능력 상한선을 결정합니다. 대규모 언어 모델 (LLM) API의 컨텍스트 구조, KV Cache 친화적 설계, 프롬프트 엔지니어링 (Prompt Engineering), 동적 프롬프트와 Agent Skills, 상태 표시줄 메타 정보, 그리고 컨텍스트 압축 전략을 심도 있게 다룹니다.
제 3 장 · 사용자 메모리 및 지식 베이스: Agent가 세션을 넘어 사용자를 기억하고 외부 지식에 접속하게 합니다. 사용자 메모리 시스템, RAG (Retrieval-Augmented Generation) 기초 파이프라인, 그리고 평면 텍스트를 넘어선 지식 조직 및 검색 (구조화된 인덱스, 지식 그래프 등)을 다룹니다.
제 4 장 · 도구 (Tools): 도구는 Agent의 양손입니다. 도구의 분류와 일반적인 설계 원칙, MCP 프로토콜과 도구 선택의 과제, 인지/실행/협업의 세 가지 유형의 도구, 그리고 이벤트 기반의 비동기 Agent를 설명합니다.
제 5 장 · 코딩 Agent (Coding Agent) 및 코드 생성: 코드는 "새로운 도구를 창조할 수 있는 도구"이며, 범용 Agent의 메타 능력입니다. 프로덕션급 Coding Agent를 예로 들어, 이 가장 강력한 범용 도구의 완전한 구현을 보여줍니다.
제 6 장 · Agent의 평가: Agent의 성능을 비교 가능한 신호로 만듭니다. 평가 환경, 데이터셋 설계, 지표 체계부터 통계적 유의성, 관측 가능성 (Observability), 평가 기반 선정, 프로덕션급 내부 평가 및 시뮬레이션 환경까지 다룹니다.
제 7 장 · 모델 사후 학습 (Post-training): 사전 학습 (Pre-training), SFT (Supervised Fine-Tuning), RL (Reinforcement Learning)의 3단계 전경을 다룹니다. 언제 SFT를 선택하고 언제 RL을 선택할지, RLHF, 알고리즘 비교, 데이터와 환경, 그리고 모델이 도구 호출을 배우고 샘플 효율성을 높이기 위한 최첨단 탐색을 다룹니다.
제 8 장 · Agent의 자기 진화: 가중치를 변경하지 않고도 성장할 수 있습니다. 경험으로부터의 학습, 능동적 도구 발견에서부터 "도구 사용자에서 도구 창조자로"까지의 세 가지 학습 패러다임을 통해 Agent가 "똑똑함"을 넘어 "숙련됨"으로 나아가는 과정을 다룹니다.
제 9 장 · 멀티모달 (Multimodal) 및 실시간 상호작용: 인지와 행동을 텍스트에서 음성, GUI 및 물리 세계로 확장합니다. 음성 3가지 패러다임 (Cascaded/End-to-End Multimodal/Full-duplex), 스트리밍 음성 인지 및 합성, Computer Use 및 로봇 조작을 다룹니다.
제 10 장 · 멀티 Agent 협업 (Multi-Agent Collaboration): 집단의 지능은 개별 지능보다 높을 수 있습니다. 멀티 Agent 분류 프레임워크, 단일 Agent보다 실제로 우월한 경우, 공유 및 비공유 컨텍스트 협업, 실패 모드, 그리고 창발적인 "Agent 사회"를 다룹니다.

모든 프로젝트는 **장(Chapter)**별로 조직되어 도서의 10장과 일대일로 대응하며, 기초 개념부터 고급 기술까지의 완전한 학습 경로를 제공합니다. 디렉토리 구조는 chapterN/프로젝트명/입니다.

제5, 8, 9, 10장의 대다수 실험은 독립적으로 실행 가능한 부속 데모(demo)를 제공하며, 실제 LLM API와 연동하여 검증을 마쳤습니다.

부속 프로젝트는 세 가지 유형으로 나뉩니다. 아래 아이콘을 참조하여 각 프로젝트의 "즉시 실행 가능(out-of-the-box)" 정도를 확인하세요.

• ✅
  독립 실행 가능: 본 저장소에 완전한 코드가 포함되어 있으며, API Key(문서 끝부분 참조)를 설정하면 바로 실행할 수 있습니다. - 📖
  재현 가이드: 프로젝트 자체가 상세한 재현 문서이며, 의존성 해결을 위해 직접 git clone해야 하는 외부 저장소(훈련 프레임워크, 평가 벤치마크 등)가 필요합니다. 아래 <외부 저장소 획득> 섹션을 참조하세요. - 🚧
  설계 문서: 현재 아키텍처 및 구현 방안에 대한 설계 문서만 포함되어 있으며, 실행 가능한 코드는 아직 보완 중입니다.

다음 프로젝트들은 ✅ 독립 실행 가능이 아니므로, 본 저장소를 클론할 때 주의하시기 바랍니다:

제6, 7, 9, 10장의 일부 실험은 평가 벤치마크, 훈련 프레임워크, 로봇 플랫폼 등 외부 저장소(용량 및 저작권 문제로 본 저장소에 포함되지 않음)에 의존합니다. 정보 과부하를 방지하기 위해, 전체 클론 명령, 상위(upstream) 주소 및 본서에서 검증된 커밋 정보는 문서 끝부분의 <부록 · 외부 저장소 획득>을 참조하세요. 먼저 앞선 장들의 독립 실행 가능한 프로젝트부터 시작하는 것을 권장하며, 훈련 / 평가 / 로봇 클래스 실험의 재현이 필요할 때 문서 끝의 안내에 따라 빠르게 획득하시기 바랍니다.

chapter1/learning-from-experience/

전통적인 강화학습 (RL, Q-learning)과 LLM 기반의 인-컨텍스트 학습 (In-context Learning)을 비교하며, Shunyu Yao의 "The Second Half" 블로그 포스트에 담긴 핵심 통찰을 재현합니다. 보물찾기 게임을 통해 LLM이 어떻게 250~400배의 샘플 효율성 (sample efficiency)으로 전통적인 RL을 능가하는지 보여줍니다.

핵심 개념: 강화학습 (RL), 인-컨텍스트 학습 (In-context Learning), 샘플 효율성 (sample efficiency), 사전 지식 (prior knowledge)

chapter1/web-search-agent/

기초적인 딥 서치 (deep search) 능력을 갖추어, 다회차 검색과 정보 통합이 가능한 에이전트 (Agent)를 구현합니다.

핵심 개념: 웹 검색 (web search), 모델 네이티브 에이전트 (model-native Agent)

chapter1/search-codegen/

기초적인 딥 서치 능력과 코드 샌드박스 (code sandbox) 능력을 갖춘 에이전트를 구축하여, 웹 검색 및 코드 실행 등의 도구를 종합적으로 활용해 복잡한 분석을 수행합니다.

핵심 개념: 웹 검색 (web search), 코드 생성 (code generation), 모델 네이티브 에이전트 (model-native Agent)

chapter1/context/

체계적인 어블레이션 연구 (ablation study)를 통해 에이전트 컨텍스트의 각 구성 요소가 갖는 중요성을 보여줍니다. 다양한 LLM 제공업체 (SiliconFlow Qwen, ByteDance Doubao, Moonshot AI Kimi)를 지원하며, 서로 다른 컨텍스트 모드를 설정하여 에이전트의 행동 변화를 관찰합니다.

핵심 개념: 컨텍스트 관리 (context management), 도구 호출 (tool calling), ReAct 루프 (ReAct loop), 어블레이션 연구 (ablation study)

chapter2/local_llm_serving/

크로스 플랫폼 로컬 LLM 배포 솔루션으로, 최적의 백엔드 (vLLM 또는 Ollama)를 자동으로 선택합니다. 0.6B 규모의 작은 모델이라도 우수한 시스템 설계를 통해 뛰어난 도구 호출 능력을 구현할 수 있음을 보여줍니다. 스트리밍 응답을 지원하여 사고 과정을 실시간으로 표시합니다.

핵심 개념: 모델 배포 (model deployment), 채팅 템플릿 (Chat Template), 스트리밍 처리 (streaming processing), 도구 호출 (tool calling)

chapter2/attention_visualization/

LLM의 전체 입출력 토큰 (token) 시퀀스와 어텐션 가중치 (attention weight) 분포를 시각화하여, 모델이 컨텍스트를 처리하고 추론하며 도구를 호출하는 방식을 깊이 있게 이해합니다.

핵심 개념: 어텐션 메커니즘 (attention mechanism), 토큰 분석 (token analysis), 추론 과정 시각화 (reasoning process visualization)

chapter2/kv-cache/

다양한 컨텍스트 관리 모드가 KV 캐시 (KV Cache)에 미치는 영향을 탐구하고, 흔히 발생하는 오류 패턴이 어떻게 캐시 효율성을 저해하는지 시연합니다. 실험을 통해 올바른 컨텍스트 설계가 어떻게 지연 시간 (latency)과 비용을 크게 낮추는지 보여줍니다.

핵심 개념: KV 캐시 (KV Cache), 컨텍스트 최적화 (context optimization), 성능 튜닝 (performance tuning)

chapter2/context-compression/

요약, 핵심 정보 추출, 의미론적 압축 (semantic compression) 등을 포함한 다양한 컨텍스트 압축 전략을 구현하고 비교합니다. 에이전트의 능력을 유지하면서 토큰 사용량을 줄입니다.

핵심 개념: 컨텍스트 압축 (context compression), 토큰 최적화 (token optimization), 정보 밀도 (information density)

chapter2/prompt-engineering/

Tau-Bench 프레임워크를 확장하여, 체계적인 어블레이션 연구를 통해 다양한 프롬프트 엔지니어링 (prompt engineering) 요소가 에이전트 성능에 미치는 영향을 정량화합니다. 말투(tone), 지시문 구성, 도구 설명 등의 요소가 작업 완료율에 어떻게 영향을 미치는지 보여줍니다.

핵심 개념 (Core Concepts): 프롬프트 엔지니어링 (Prompt Engineering), 어블레이션 연구 (Ablation Study), 성능 벤치마킹 (Performance Benchmarking)

chapter2/system-hint/

시스템 힌트 (System Hint)가 에이전트 (Agent) 행동에 미치는 영향을 연구하며, 시스템 힌트 최적화를 통해 성능을 향상시키는 방법을 탐구합니다.

핵심 개념 (Core Concepts): 시스템 힌트 (System Hint), 행동 유도 (Behavior Guidance), 프롬프트 최적화 (Prompt Optimization)

chapter2/log-sanitization/

디버깅 정보를 유지하면서도 민감한 데이터를 보호하는 지능형 로그 비식별화 (Log Sanitization) 시스템을 구현합니다.

핵심 개념 (Core Concepts): 개인정보 보호 (Privacy Protection), 로그 처리 (Log Processing), 데이터 보안 (Data Security)

chapter2/prompt-injection/

3가지 공격 시나리오(직접 주입, 간접 주입, 메모리 주입) × 4가지 방어 구성(방어 없음, 프롬프트 강화, 출처 마킹, 조합 방어)의 대조 실험을 구성합니다. 결정론적 규칙을 사용하여 공격 성공률을 통계화함으로써, 계층적으로 방어를 중첩했을 때 주입 성공률이 어떻게 현저히 감소하는지 직관적으로 보여줍니다.

핵심 개념 (Core Concepts): 프롬프트 주입 (Prompt Injection), 간접 주입 (Indirect Injection), 데이터와 지시문 분리 (Separation of Data and Instructions), 런타임 검증 (Runtime Validation)

chapter2/agent-skills-ppt/

에이전트 스킬 (Agent Skills)의 「점진적 공개 (Progressive Disclosure)」 개념을 재현합니다. 에이전트가 시작될 때는 얇은 스킬 목록만 보고 있다가, 작업에 pptx 스킬이 필요함을 식별한 후에야 전체 프로세스, 세부 문서 및 번들 스크립트를 단계적으로 로드하여 최종적으로 python-pptx를 사용하여 실제 .pptx 파일을 생성합니다.

핵심 개념 (Core Concepts): 에이전트 스킬 (Agent Skills), 점진적 공개 (Progressive Disclosure), 온디맨드 로딩 (On-demand Loading), 도구 오케스트레이션 (Tool Orchestration)

chapter3/user-memory/

장기 사용자 메모리 (Long-term User Memory) 시스템을 구축하여 에이전트가 사용자의 선호도와 과거 상호작용을 기억하고 개인화된 서비스를 제공할 수 있도록 합니다.

핵심 개념 (Core Concepts): 장기 기억 (Long-term Memory), 개인화 (Personalization), 사용자 모델링 (User Modeling)

chapter3/mem0/ 및 chapter3/memobase/

mem0와 Memobase라는 두 가지 오픈소스 메모리 프레임워크를 사용하여 각각 사용자 메모리 버전을 구현합니다. 이는 실험 3-2 「메모리 전략 비교」의 대조 구현으로 사용되며, 서로 다른 메모리 방안의 추출 형태와 답변 품질을 수평적으로 비교하기 용이하게 합니다.

핵심 개념 (Core Concepts): 메모리 프레임워크 (Memory Framework), mem0, Memobase, 방안 비교 (Solution Comparison)

chapter3/user-memory-evaluation/

다양한 테스트 시나리오와 평가 지표를 포함하여 사용자 메모리 시스템의 정확성, 관련성 및 유효성을 체계적으로 평가합니다.

핵심 개념 (Core Concepts): 평가 프레임워크 (Evaluation Framework), 테스트 케이스 (Test Case), 성능 측정 (Performance Metrics)

chapter3/dense-embedding/

벡터 유사도 검색 서비스를 구축하고, ANNOY(트 기반)와 HNSW(그래프 기반) 두 가지 근사 최근접 이웃 (ANN) 인덱스 알고리즘을 비교 연구합니다. 다양한 인덱스 전략이 성능, 메모리 점유율 및 업데이트 능력 측면에서 어떤 트레이드오프 (Trade-off)를 갖는지 보여줍니다.

핵심 개념 (Core Concepts): 밀집 임베딩 (Dense Embedding), 벡터 검색 (Vector Retrieval), ANN 알고리즘 (ANN Algorithm), 시맨틱 검색 (Semantic Search)

chapter3/sparse-embedding/

BM25 알고리즘 기반의 희소 벡터 검색 엔진을 처음부터 구현합니다. 풍부한 로그와 시각화 인터페이스를 통해 검색 엔진의 내부 작동 메커니즘을 보여주며, 단어 빈도 가중치 계산과 역색인 (Inverted Index) 원리를 이해합니다.

핵심 개념 (Core Concepts): 희소 임베딩 (Sparse Embedding), BM25, TF-IDF, 완전 일치 (Exact Match)

chapter3/retrieval-pipeline/

밀집 검색 (Dense Retrieval), 희소 검색 (Sparse Retrieval), 신경 재정렬 (Neural Re-ranking)을 결합한 완전한 검색 파이프라인 (Retrieval Pipeline)을 구축합니다. 정교하게 설계된 테스트 케이스를 통해 다양한 시나리오에서 하이브리드 검색 (Hybrid Retrieval)이 갖는 상호 보완적 효과를 체계적으로 보여줍니다.

핵심 개념 (Core Concepts): 하이브리드 검색 (Hybrid Retrieval), 신경 재정렬 (Neural Re-ranking), 크로스 인코더 (Cross-encoder), 검색 융합 (Retrieval Fusion)

chapter3/multimodal-agent/

세 가지 멀티모달 처리 전략인 네이티브 멀티모달 처리 (Native Multimodal Processing), 텍스트 추출 (Extraction to Text), 도구 기반 분석 (Tool-based Analysis)을 비교합니다. 통합 프레임워크 하에서의 어블레이션 연구 (Ablation Study)를 통해 서로 다른 기술 경로가 충실도 (Fidelity), 비용 및 유연성 측면에서 어떤 트레이드오프를 갖는지 밝힙니다.

핵심 개념 (Core Concepts): 멀티모달 (Multimodal), 시각적 이해 (Visual Understanding), OCR, 엔드 투 엔드 처리 (End-to-end Processing)

chapter3/structured-index/

RAPTOR (Recursive Abstract Tree)와 GraphRAG (Knowledge Graph)라는 두 가지 첨단 인덱스 전략을 구현하고 비교합니다. 인덱스 기술 매뉴얼을 통해 지식의 내재적 계층과 연관성을 반영하는 구조화된 인덱스를 구축하는 방법을 시연합니다.

핵심 개념 (Core Concepts): RAPTOR, GraphRAG, 계층적 요약 (Hierarchical Summarization), 지식 그래프 (Knowledge Graph)

chapter3/agentic-rag/

전통적인 Non-Agentic RAG와 Agentic RAG의 성능 차이를 비교합니다. 에이전트가 ReAct 패턴을 통해 어떻게 반복적인 정보 검색을 주도하며, 복잡한 법률 질의응답을 처리할 때 답변 품질을 현저히 높이는지 보여줍니다.

핵심 개념 (Core Concepts): Agentic RAG, ReAct 루프 (ReAct Loop), 반복 검색 (Iterative Retrieval), 능동적 탐색 (Active Exploration)

chapter3/agentic-rag-for-user-memory/

Agentic RAG 프레임워크를 사용자 대화 기록 관리에 적용하여, 다회차 반복 검색 능력을 통해 세션 간 메모리 검색을 처리하고 기초적인 회상 및 다중 세션 검색 능력을 구현합니다.

핵심 개념 (Core Concepts): 사용자 메모리 (User Memory), 대화 기록 인덱싱 (Conversation History Indexing), 세션 간 검색 (Cross-session Retrieval)

chapter3/contextual-retrieval/

Anthropic이 제안한 문맥 인식 검색 (Contextual Retrieval) 기술을 구현합니다. 텍스트 청크(Chunk)에 핵심 문맥을 포함하는 접두사 요약(Prefix Summary)을 생성함으로써, 기존 분할 방식의 문맥 손실 문제를 해결하고 검색 실패율을 49-67% 감소시킵니다.

핵심 개념: 문맥 강화 (Context Augmentation), 접두사 생성 (Prefix Generation), 의미론적 앵커링 (Semantic Anchoring), 검색 최적화 (Retrieval Optimization)

chapter3/contextual-retrieval-for-user-memory/

문맥 인식 검색 기술을 사용자 기억 구축에 적용합니다. Advanced JSON Cards와 문맥 인식 RAG를 결합하여 이중 계층 기억 구조를 형성함으로써, 더 높은 수준의 능동적 서비스 능력을 구현합니다.

핵심 개념: 이중 계층 기억 (Dual-layer Memory), 구조화된 사실 (Structured Facts), 문맥 검색 (Contextual Retrieval), 능동적 서비스 (Proactive Service)

chapter3/structured-knowledge-extraction/

사법 판례를 예로 들어 「상향식 요인 발견 (Bottom-up Factor Discovery) → 사건 프로토타입 클러스터링 (Clustering Case Prototypes) → 대화형 제안 에이전트 (Conversational Suggestion Agent)」로 이어지는 3단계 파이프라인을 실행합니다. 경직된 필드를 미리 설정하지 않고, LLM이 방대한 사례로부터 요인을 자율적으로 발견하여 모듈형 스키마(핵심 요인 + 죄명 확장 요인)로 귀납합니다. 이후 사건을 여러 프로토타입으로 클러스터링하고 각 프로토타입의 요인 중요도를 계산합니다. 에이전트는 새로운 사건에 대해 가장 유사한 프로토타입을 매칭하고, 중요도에 따라 누락된 정보를 질문하며 근거 있는 제안을 제공합니다 (법적 면책 조항 포함).

핵심 개념: 상향식 지식 발견 (Bottom-up Knowledge Discovery), 모듈형 요인 (Modular Factors), 클러스터링 프로토타입 (Clustering Prototypes), 설명 가능한 의사결정 (Explainable Decision-making)

chapter4/perception-tools/

웹 검색, 멀티모달 이해 (Multimodal Understanding), 파일 시스템 조작, 공공 데이터 소스 접근 능력을 제공하는 포괄적인 인지 도구 세트를 구축합니다. 대부분의 기능은 무료로 개방된 API (DuckDuckGo, Open-Meteo, Yahoo Finance, OpenStreetMap 등)를 기반으로 하며, API 키 없이도 사용할 수 있습니다.

핵심 개념: MCP 프로토콜, 멀티모달 분석 (Multimodal Parsing), 공공 데이터 소스 (Public Data Sources), 문서 이해 (Document Understanding), 지리 정보 서비스 (Geospatial Services)

chapter4/execution-tools/

파일 조작, 코드 인터프리터 (Code Interpreter), 가상 터미널, 외부 시스템 통합을 포함하여 보안 메커니즘을 갖춘 실행 도구 세트를 구현합니다. LLM의 2차 승인 메커니즘을 통해 위험한 동작을 방지하고, 복잡한 출력을 자동으로 요약하며, 코드의 구문 검증을 수행합니다.

핵심 개념: MCP 프로토콜, 실행 보안 (Execution Security), LLM 승인 (LLM Approval), 결과 요약 (Result Summarization), 자동 검증 (Automatic Verification)

chapter4/collaboration-tools/

브라우저 자동화 (browser-use 프레임워크), 인간 참여형 (Human-in-the-Loop, HITL), 다채널 알림 (Email, Telegram, Slack, Discord) 및 타이머 관리를 포함한 포괄적인 협업 능력을 제공합니다. 민감한 작업에 대한 관리자 승인 및 예약된 작업 스케줄링을 지원합니다.

핵심 개념: MCP 프로토콜, 브라우저 자동화 (Browser Automation), HITL 모드, 다채널 알림 (Multi-channel Notification), 예약 작업 (Scheduled Tasks)

chapter4/agent-with-event-trigger/

FastAPI를 기반으로 구축된 현대적인 이벤트 드리븐 (Event-driven) 에이전트로, 기본적으로 앞선 세 가지 MCP 서버의 모든 도구를 통합합니다. 네이티브 비동기 아키텍처를 채택하여 명확한 MCP 도구 로딩을 구현하며, HTTP API를 통해 다양한 소스의 이벤트 (Web, 즉시 메시지, GitHub, 타이머 등)를 수신합니다. 자동 API 문서 (Swagger UI) 및 백엔드 모니터링 기능을 제공합니다.

핵심 개념: FastAPI, 네이티브 비동기 (Native Asynchronous), MCP 통합 (MCP Integration), 이벤트 드리븐 (Event-driven), 자동 API 문서 (Automatic API Documentation), 도구 오케스트레이션 (Tool Orchestration)

chapter4/active-tool-selection/

지능형 도구 선택 메커니즘을 구현하여, 에이전트가 사전에 정의된 도구 세트를 수동적으로 받아들이는 대신 작업 요구 사항에 따라 가장 적합한 도구 조합을 능동적으로 선택할 수 있도록 합니다.

핵심 개념: 도구 선택 (Tool Selection), 동적 도구 로딩 (Dynamic Tool Loading), 작업 분석 (Task Analysis)

chapter4/async-agent/

asyncio 단일 스레드를 기반으로 구현된 이벤트 드리븐 비동기 에이전트 프레임워크 (Flux)의 핵심입니다: 인박스 (Inbox) 이벤트 큐는 긴급도에 따라 할당 (중단/즉시/대기)되며, 비동기 도구의 병렬 실행, 실행 중인 현재 턴 (Turn)의 중단, 그리고 시뮬레이션된 장기 작업에 대한 취소 및 상태 조회를 지원합니다. 의사결정은 실제 LLM (Function Calling)에 의해 수행됩니다.

핵심 개념: 비동기 프로그래밍 (Asynchronous Programming), 이벤트 큐 (Event Queue), 중단 메커니즘 (Interruption Mechanism), 병렬 도구 취소 (Parallel Tool Cancellation), 비차단 I/O (Non-blocking I/O)

또한,

chapter4/docker-compose.yml

및 chapter4/DOCKER_DEPLOYMENT.md는

위의 MCP 도구 서버를 컨테이너화하여 배포하기 위한 참조 방안을 제공합니다.

chapter5/coding-agent/

Claude를 기반으로 구축된 프로덕션급 AI 코딩 어시스턴트로, 커맨드라인 의존성 없이 모든 도구를 순수 Python으로 구현합니다. 파일 조작, 검색, Shell 조작 및 프로젝트 관리를 아우르는 17개의 완전 구현된 도구를 포함합니다. 특히 ripgrep의 기능과 완전히 호환되는 순수 Python 기반의 Grep 도구를 특별히 구현했습니다.

핵심 특성:

• 순수 Python 구현, 명령줄(CLI) 의존성 없음, Mac 사용자에게 특히 적합
• 완전한 도구 세트: 파일 읽기/쓰기/편집, 순수 Python 정규표현식 검색, 디렉토리 목록, Shell 세션 관리
• 시스템 프롬프트 (System Prompt) 기술: 타임스탬프, 도구 호출 횟수, TODO 리스트 관리, 상세 에러 메시지
• 지속 가능한 Shell 환경, 자동 Lint 검사, 스트리밍 응답 (Streaming Response) 지원
• 여러 LLM 제공업체 (Anthropic, OpenAI, OpenRouter) 지원

핵심 개념: 코드 생성, 파일 편집, 순수 Python 도구, 시스템 프롬프트, Lint 검사, 다중 제공업체 지원

chapter5/code-for-math/

동일한 모델이 동일한 경시대회 수학 문제 세트에 대해 「순수 사고 사슬 (Chain of Thought, CoT)」과 「코드 보조」 두 가지 모드를 비교하도록 합니다. 후자는 문제를 Python (sympy/numpy/scipy)으로 형식화하고, 함수 호출 (Function Calling)을 통해 서브프로세스 샌드박스에서 실행하여, 실수하기 쉬운 암산 대신 정밀한 계산을 사용하여 정확도가 현저히 높습니다.

핵심 개념: 코드 인터프리터 (Code Interpreter), 기호 계산 (Symbolic Computation), 사고 사슬 비교, 도구 강화 추론

chapter5/code-for-logic/

「기사와 악당 (Knights and Knaves)」 논리 퍼즐을 제약 충족 문제 (Constraint Satisfaction Problem, CSP)로 변환합니다: Agent는 python-constraint를 사용하여 변수와 이중 조건 제약을 정의하고 해결사 (Solver)를 호출하여, 순수 자연어 추론과 코드 보조 두 가지 모드가 일련의 K&K 퍼즐에 대해 가지는 정확도를 비교합니다.

핵심 개념: 제약 해결, CSP 모델링, 형식화된 추론, 코드 보조

chapter5/small-model-codified-rules/

$\tau$-bench 항공 고객 서비스 시나리오를 기반으로 한 대조 실험: 복잡한 비즈니스 정책 (환불 규칙)을 자연어 프롬프트에서 코드/도구로 옮긴 후, 소형 모델의 작업 성공률과 정책 일관성이 크게 향상되었습니다. 도구 내 코드 검증은 모델의 잘못된 인식을 실시간으로 차단할 수 있습니다.

핵심 개념: 코드화된 비즈니스 규칙, 정책 실행, 도구 내 검증, 소형 모델 신뢰성

chapter5/paper-to-ppt/

「PPT 만들기」를 코드 생성 문제로 재구성합니다: 제안자 (Proposer)가 Slidev (Markdown+HTML) 코드를 작성하면, 검토자 (Reviewer)가 각 페이지를 실제로 PNG로 렌더링하고 Vision LLM을 사용하여 레이아웃 문제를 점검하며, 구조화된 피드백에 따라 반복적으로 수정합니다. 이 이중 Agent 분업을 통해 컨텍스트 피크 (Context Peak)를 현저히 낮출 수 있습니다.

핵심 개념: 코드 생성, Slidev, 제안자-검토자, 시각적 품질 제어

chapter5/paper-to-video/

「논문 $\rightarrow$ PPT」를 기반으로 각 슬라이드에 대한 구어체 해설 스크립트를 생성하고, TTS를 호출하여 음성을 합성한 뒤, ffmpeg를 사용하여 각 페이지의 스크린샷과 오디오를 페이지별로 동기화하여 내레이션이 포함된 설명 영상을 합성합니다.

핵심 개념: 멀티미디어 생성, 해설 스크립트 생성, TTS, ffmpeg 오디오-비디오 동기화

chapter5/video-edit/

사용자가 다중 장면 영상과 자연어 요구사항을 제공하면, Agent는 「2단계 Vision 위치 파악」(먼저 거칠게, 그다음 세밀하게 프레임을 추출하여 이미지를 읽음)을 통해 목표 장면의 시간 경계를 결정합니다. 클립을 잘라낸 후에는 Reviewer가 완성본의 핵심 프레임을 추출하여 확인하며, 부적합할 경우 반복 수행합니다.

핵심 개념: 비디오 편집, Vision 위치 파악, Coarse-to-Fine (거칠게에서 세밀하게), 제안자-검토자

chapter5/adaptive-log-parser/

자기 진화가 가능한 로그 파싱 시스템: 해석할 수 없는 새로운 형식을 만났을 때 에러를 내는 대신, 실패 샘플과 에러 메시지를 코드 생성 Agent에게 전달하여 parse 함수를 생성하게 합니다. 자동 테스트를 통과하면 핫 업데이트 (Hot Update)를 통해 파싱 엔진에 등록되며, 전 과정에 사람의 개입이 필요 없습니다.

핵심 개념: 시스템 어댑터로서의 코드, 자가 치유 루프 (Self-healing Loop), 코드 핫 업데이트, 자동 테스트

chapter5/log-diagnosis/

진단 Agent가 운영 로그, 아키텍처 문서 및 PRD를 읽고, 문제와 근본 원인을 자동으로 파악하며, 구조화된 보고서와 회귀 테스트 케이스를 생성합니다. 리플레이 프레임워크를 통해 실제로 실행하여 검증하고, MCP를 통해 (mock) GitHub와 연동하여 Issue를 생성합니다.

핵심 개념: 트레이스 진단, 근본 원인 파악, 회귀 테스트 생성, 리플레이 검증

chapter5/dynamic-form/

정보가 불완전한 요청을 받았을 때, Agent는 하나씩 되묻는 대신 계층적 논리를 포함한 자가 포함(Self-contained) HTML 양식을 동적으로 생성하여 사용자가 한 번에 보완할 수 있게 합니다. 프런트엔드는 양식을 JSON으로 요약하여 Agent에게 다시 전달하여 작업을 계속합니다.

핵심 개념: 코드 생성, 의도 명확화, 동적 양식, 계층적 논리

chapter5/erp-agent/

중국어 자연어 질의를 SQL로 변환하여 데이터베이스에서 실행하고 결과 테이블을 직접 제시합니다. 핵심은 Artifact (제물/산출물) 패턴입니다: LLM은 SQL 산출물만 생성하고 직접 데이터를 옮기지 않으므로, 토큰을 절약하면서 계산 오류를 방지할 수 있으며 수만 행의 결과도 순식간에 응답할 수 있습니다.

핵심 개념: NL2SQL, Artifact 패턴, 데이터베이스 실행, 비용 및 정확성

chapter5/conversational-ui/

사용자가 자연어로 UI 커스텀 요구사항(색상/글꼴/문구/레이아웃)을 제시하면, Agent가 스스로 위치를 파악하여 React 프론트엔드 소스 코드를 수정합니다. Vite의 Hot Module Replacement (HMR)를 활용하여 변경 사항을 즉시 적용하며, 다회차 반복 커스텀을 지원합니다.

핵심 개념: 코드 수정, 프론트엔드 커스텀, Hot Module Replacement (HMR), 다회차 반복

chapter6/terminal-bench/

Terminal-Bench는 실제 터미널 환경에서 AI Agent의 성능을 테스트하는 벤치마크입니다. 코드 컴파일부터 모델 학습, 서버 설정에 이르기까지 Agent가 실제 엔드 투 엔드 (End-to-End) 작업을 어떻게 처리하는지 평가합니다. 약 100개의 태스크를 포함하는 데이터셋과 실행 프레임워크를 포함하며, 다양한 Agent 구현을 지원합니다.

핵심 개념: 터미널 자동화, 태스크 평가, Docker 샌드박스, 벤치마크

chapter6/SWE-bench/

SWE-bench는 대규모 언어 모델 (LLM)이 실제 GitHub 이슈를 해결하는 능력을 평가하는 벤치마크입니다. 코드베이스와 문제 설명이 주어지면, 모델은 문제를 해결할 수 있는 패치 (Patch)를 생성해야 합니다. SWE-bench, SWE-bench Lite, SWE-bench Verified, SWE-bench Multimodal 등 여러 버전이 있습니다.

핵심 개념: 코드 수정, GitHub 이슈, 패치 생성, Docker 평가

chapter6/GAIA/

GAIA는 차세대 LLM(도구 강화, 효율적인 프롬프팅, 검색 액세스 등의 능력을 갖춘 LLM)을 평가하는 것을 목표로 합니다. 다양한 수준의 도구 사용과 자율성을 요구하는 450개 이상의 비사소한 (Non-trivial) 문제들을 포함하며, 정답은 명확하고 모호하지 않습니다. 3가지 난이도 단계로 나뉩니다.

핵심 개념: 도구 사용, 다단계 추론, 자율성 평가

chapter6/OSWorld/

파일 관리, 애플리케이션 조작, 시스템 설정을 포함하여 완전한 운영체제 환경에서 복잡한 작업을 수행하는 Agent의 능력을 평가합니다.

핵심 개념: 운영체제 자동화, 다중 애플리케이션 협업, 시스템 레벨 태스크

chapter6/android_world/

(📖 외부 저장소, 《외부 저장소 가져오기》 참조)

애플리케이션 탐색, UI 상호작용, 태스크 완료 능력을 포함하여 Android 모바일 환경에서의 Agent 성능을 평가합니다.

핵심 개념: 모바일 자동화, Android UI, 애플리케이션 상호작용

chapter6/android-world/

(하이픈 명명) 벤치마크 코드가 아니라, T3A Agent가 android_world에서 실패한 사례를 분석한 본서의 분석 노트(t3a*.md)이며, 읽기 자료로 참고할 수 있습니다.

chapter6/tau2-bench/

계산, 검색, 데이터 처리 등의 시나리오를 포함하여 Agent가 도구를 사용하여 복잡한 추론을 수행하는 능력을 평가하는 데 집중합니다.

핵심 개념: 도구 강화 추론, 다단계 태스크, 도구 조합

chapter6/elo-leaderboard/

ELO 레이팅 시스템을 기반으로 한 Agent 성능 리더보드를 구현하며, 대결 비교를 통해 서로 다른 Agent의 상대적 능력을 평가합니다.

핵심 개념: ELO 레이팅, 상대적 평가, 리더보드 시스템

chapter6/model-benchmark/

여러 OpenAI 호환 LLM API 제공업체에 대해 횡단적 벤치마크를 수행합니다. 스트리밍 인터페이스를 사용하여 첫 번째 토큰 지연 시간 (Time To First Token, TTFT)을 정밀하게 측정하고, 동시성 환경에서 엔드 투 엔드 (End-to-End) 지연 시간 분위수 (p50/p95), 처리량 (Throughput), 성공률을 측정합니다. 명령어 한 줄로 다차원 비교표를 생성하며, 이는 모델 선정(Selection)이 단순히 리더보드만 보는 것이 아니라 다차원적인 트레이드오프 (Trade-off)임을 보여줍니다.

핵심 개념: TTFT, 지연 시간 분위수, 처리량, 동시성 부하 테스트, 모델 선정

chapter6/agent-cost-analysis/

전형적인 다회차 Agent 태스크(고객 서비스 환불)에 대해 전체 경로 비용 분석을 수행합니다. 자체 구축한 경량 트레이싱 (Tracing)을 사용하여 매 LLM 호출의 입력/출력/캐시 토큰, 지연 시간 및 비용을 기록하고, "어느 단계가 가장 비싼지"를 집계합니다. 그 다음 A/B 테스트를 통해 KV-cache 친화적 설계와 컨텍스트 압축 (Context Compression)이 가져오는 실제 절감 효과를 정량화합니다.

핵심 개념: 관측 가능성 (Observability), 비용 분석, 프롬프트 캐싱 (Prompt Caching), A/B 비교

chapter6/tts-quality-eval/

다양한 TTS 설정(서로 다른 모델/음성/속도)을 사용하여 동일한 도전적인 텍스트 세트를 합성한 후, 멀티모달 LLM-as-a-Judge를 사용하여 루브릭 (Rubric)에 따라 각 차원(명확성/자연스러움 등)별로 점수를 매기고, 재현 가능한 설정 비교표로 요약합니다.

핵심 개념: LLM-as-a-Judge, 루브릭 (Rubric) 평가, TTS 평가, 다차원 비교

본 장은 지도 미세 조정 (Supervised Fine-Tuning, SFT)과 강화학습 (Reinforcement Learning, RL)의 다양한 기술 및 응용 시나리오를 다루는 여러 모델 사후 학습 (Post-training) 프로젝트를 포함합니다.

chapter7/AdaptThink/

및 chapter7/AdaptThink-original/

추론 모델이 문제 난이도에 따라 추론 모드 (Thinking vs NoThinking)를 적응적으로 선택하도록 학습시킵니다. 제약 최적화 (Constrained Optimization)와 중요도 샘플링 (Importance Sampling)을 통해 추론 비용을 대폭 절감(45-69%)하는 동시에 정확도를 향상시킵니다. DeepSeek-R1-Distill-Qwen 모델을 기반으로 하며, DAPO 알고리즘을 사용하여 학습되었습니다.

핵심 개념 (Core Concepts): 적응형 추론 (Adaptive Reasoning), 추론 비용 최적화 (Inference Cost Optimization), 제약 최적화 (Constraint Optimization), 중요도 샘플링 (Importance Sampling)

chapter7/retool/

다회차 대화 (Multi-turn Dialogue)와 코드 샌드박스 (Code Sandbox)를 사용하여 대규모 언어 모델 (LLM)의 수학적 추론 능력을 향상시킵니다. SFT (Supervised Fine-Tuning)와 RL (Reinforcement Learning)의 2단계 학습을 통해, 모델이 코드 실행 환경을 사용하여 수학 문제 풀이를 보조하도록 학습시킵니다. Qwen2.5-32B-Instruct를 기반으로 하며, AIME 2024 데이터셋에서 DAPO 알고리즘과 SandboxFusion 샌드박스를 사용하여 학습되었습니다.

핵심 개념 (Core Concepts): 도구 사용 (Tool Use), 코드 실행 (Code Execution), 수학적 추론 (Mathematical Reasoning), 다회차 대화 (Multi-turn Dialogue), DAPO 알고리즘

chapter7/AWorld/

및 chapter7/AWorld-train/

AWorld 프레임워크를 기반으로 Embodied Agent (구체화된 에이전트)를 학습시켜, 에이전트가 가상 환경에서 복잡한 작업을 수행하고 경험으로부터 학습할 수 있도록 합니다.

핵심 개념 (Core Concepts): Embodied AI (구체화된 지능), 환경 상호작용 (Environment Interaction), 경험 학습 (Experience Learning)

chapter7/SFTvsRL/

다양한 작업에서 지도 미세 조정 (SFT)과 강화 학습 (RL)의 효과를 체계적으로 비교하고, 두 방법의 장단점 및 적용 시나리오를 분석합니다.

핵심 개념 (Core Concepts): SFT vs RL, 학습 방법 비교, 성능 분석

chapter7/verl/

verl은 대규모 언어 모델의 RLHF (Reinforcement Learning from Human Feedback) 학습을 위해 특별히 설계된 효율적인 강화 학습 프레임워크로, PPO, GRPO, DAPO 등 다양한 알고리즘을 지원합니다.

핵심 개념 (Core Concepts): RLHF, PPO, 분산 학습 (Distributed Training), 효율적 최적화 (Efficient Optimization)

chapter7/Intuitor/

모델의 직관적 추론 (Intuitive Reasoning) 능력을 학습시켜, 모델이 상세한 사고 사슬 (Chain of Thought) 없이도 빠르게 합리적인 판단을 내릴 수 있도록 합니다.

핵심 개념 (Core Concepts): 직관적 추론 (Intuitive Reasoning), 빠른 의사결정 (Fast Decision Making), 사고 사슬 (CoT) 최적화

chapter7/MultilingualReasoning/

다양한 언어 환경에서의 추론 능력을 학습시켜 교차 언어 작업 (Cross-lingual Tasks)의 성능을 향상시킵니다.

핵심 개념 (Core Concepts): 다국어 (Multilingual), 교차 언어 추론 (Cross-lingual Reasoning), 언어 일반화 (Language Generalization)

chapter7/SpatialReasoning/