GitHub에는 AI Agent 프로젝트가 많고, 프레임워크는 더 많다. LangChain, AutoGen, CrewAI, LangGraph, Agno…… 이름だけでも 수십 개가 넘는다. 그런데 이 저장소들을 둘러보면 “Agent란 정확히 무엇이며, 왜这样的 구조로 설계되는가”를 설명하는 책은 거의 없다는 사실이 드러난다.
대부분의 콘텐츠는 블로그, 튜토리얼, README 형태로 흩어져 있다. Agent의 기초를 체계적으로 익히려면 논문을 읽거나 Medium의 링크를十几个 개씩 직접 조합해야 한다.
이博杰(GitHub: bojieli)는 다른 접근을 택했다. 10개 장으로 구성된 중국어 오픈소스 기술서 bojieli/ai-agent-book를 저술하고, 103개의 실행 가능한 실험과 14개 언어 번역을 더했다. 저장소는 Apache-2.0 라이선스를 사용하며 현재 40,004 stars를 기록했고, GitHub Trending Project of the Day에도 올랐다.
이것은 소프트웨어 프레임워크가 아니다. pip install로 설치할 수도 없다. 이 책이 해결하는 문제는 “흩어진 블로그와 프레임워크 README 사이에 파묻혀 Agent를 체계적으로 이해하고 싶은 사람에게 학습 경로를 제공하는 것”이다.
무엇을 해결하는가
책의 중심을 관통하는 공식은 다음 한 문장으로 정리된다.
Agent = LLM + Context + Tools이 공식을 중심으로 10개 장의 본문과 103개의 독립적인 실험이展開된다. 특정 프레임워크나 API를 판매하지도, 자금을 조달하지도 않는다.
콘텐츠는 네 가지 방식으로 제공된다.
- 온라인 열람:
bojieli.github.io/ai-agent-book - 오프라인 PDF / EPUB: release 페이지에서 다운로드
- GitHub 저장소에 있는 Markdown 원문
- 각 장의
code디렉터리에 있는 실험 코드
PDF/EPUB 링크는 항상 latest를 가리킨다. 저자가 push할 때마다 CI가 다시 컴파일하지만 URL은 바뀌지 않으므로 사용자는 항상 최신판을 받는다. GitHub Releases에서 자주 간과되는 활용법이다.
사용 방법
대표적인 이용 경로는 세 가지다.
경로 1: 처음부터 순서대로 읽기
온라인 사이트를 열고 왼쪽에서 장을 넘기며 오른쪽 위에서 언어를 바꾼다. 전체 본문 검색도 지원한다. 오프라인 환경에서는 PDF를 내려받아 Kindle에 넣어도 된다.
경로 2: 읽으면서 직접 실행하기
git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book
ls
# 你会看到 chapter1/ chapter2/ ... chapter10/ 这样的目录结构각 chapter 디렉터리에는 의존성 목록을 적은 README가 들어 있다. OPENAI_API_KEY 환경 변수를 설정하고 pip install을 마치면 python xxx.py 형태로 바로 실행할 수 있다.
경로 3: 팀 교육 자료로 활용하기
중국어 원서, 연계 실험, 다국어 버전을 한 세트로 사용하면 기술 책임자가 팀을 대상으로 Agent 기초 과정을 진행할 수 있다. 별도의 교육 자료를 주워 모으는 수고를 덜 수 있다.
가장 빠른 시작 방법은 저장소를 clone한 뒤 첫 번째 장 디렉터리로 이동하는 것이다. README에 따라 의존성을 설치하고 첫 번째 ReAct loop demo를 실행하면 된다.
어떻게 작동하는가: 구조
구조는 세 층으로 나뉜다.
콘텐츠 계층: Markdown 원고를 장별로 분리한다. 각 장은 독립적인 chapterN/ 디렉터리를 이루며 본문과 실험 코드가 대응한다.
빌드 계층: push가 GitHub Actions를触发해 PDF와 EPUB를 자동으로 컴파일하고 GitHub Releases에 게시한다. 다운로드 링크는 계속 latest를 가리킨다.
운영 계층:
- 온라인 열람 사이트는 GitHub Pages로 호스팅한다.
- 번역 브랜치는
docs/en,docs/es,docs/id등으로 구성하며 모두 14개 언어를 지원한다. - 커뮤니티 PR 과정은 번역자가 저장소를 fork하고, 자신의 언어로 번역한 뒤, PR을 제출하고, 저자가 merge하는 방식으로 진행된다.
2.0 버전에서는 장 구성을 다시 묶었다. 기존 제4장 “비동기 상호작용”과 제9장 “다중 모드 Agent”를 합쳐 새로운 제6장 “상호작용: 관찰 및 행동 공간의 확장”으로 만들었고, 기존 6/7/8장은 순번을 뒤로 미뤘다. 예전 독자는 처음 열었을 때 당황할 수 있지만 새 장 번호에 다시 적응해야 한다.
핵심 흐름을 한 문장으로 줄이면 다음과 같다. 저자가 중국어 주 브랜치를 작성하고, 커뮤니티가 fork해 번역하고, PR을 merge한 뒤, CI가 다국어 PDF를 자동 빌드해 release로 내보낸다.
이 과정 자체가 “오픈소스 기술서를 만드는 방법”을 보여주는 하나의 모범 사례다.
좋은 점과 아쉬운 점
좋은 점:
- 콘텐츠 자산이 탄탄하다. 40k stars와 GitHub Trending Project of the Day 등재가 보여주듯 대부분의 Agent 프레임워크보다 전파력이 강하다. 한 명의 저자가 이 정도 규모를 만든 배경에는 책의 체계성이 있다.
- 다국어 이용 장벽을 크게 낮췄다. release 링크가
latest로 고정되어 사용자는 항상 최신판을 받는다. 히브리어, 타밀어, 베트남어,希腊어처럼 상대적으로 uncommon한 언어까지 포함한 14개 언어를 지원해 전 세계 개발자에게 접근성을 제공한다. - 읽기와 실행의 폐쇄 루프를 만들었다. 실험과 본문을 일대일로 연결했기 때문에 이론을 읽은 직후 코드를 실행해 검증할 수 있다. 단순 독서보다 학습 경험이 낫다.
아쉬운 점:
- 소프트웨어 프레임워크가 아니다.
pip install ai-agent-book로 설치할 수 없고 production 환경에 직접 통합할 수도 없다. 실제 제품을 만들려면 LangGraph, Agno 같은 SDK를 사용해야 한다. - 개별 주제의 깊이는 제한된다. 실험 코드가 교육용에 치우쳐 있고 추상화가 적다. LangChain처럼高度로 추상화된 라이브러리와 비교하면 한 지점을 깊게 파고들지는 못한다. 책은 체계성을 유지해야 하므로 필연적인取舍가 필요하다.
- 번역 품질이 제각각이다. 14개 언어 번역은 커뮤니티 주도로 진행되며 저자는 중국어 원판만 관리한다. 영어, 스페인어, 인도네시아어 같은 인기 언어는 갱신이 빠르지만 소수 언어판은 몇 달씩 뒤처질 수 있다.
- 2.0에서 장 번호가 바뀌었다. 예전 판의 장 번호에 맞춰 작성한 독자 노트는 다시 정리해야 한다.
직접 실행해 본 결과
저장소는 네트워크 상태에 따라 약 2분 만에 clone할 수 있었다. 디렉터리 구조는 한눈에 파악하기 쉬웠다. 루트에는 책 원문 Markdown이 있고, 각 장의 하위 디렉터리에는 실험 코드가 들어 있다.
온라인 사이트인 bojieli.github.io는 로딩 속도가 괜찮았고 본문 전체 검색도 지원했다. 중국어 글꼴 렌더링이 깨끗했다. 중국어 PDF는 약 15MB였고, 표지는 깔끔했으며 코드 블록 강조도 정상적으로 표시됐다.
제2장(ReAct + Tool Use)의 실험 하나를 골라 실행했다. OPENAI_API_KEY가 필요했고 README대로 환경 변수를 설정하니 단일 추론 루프가 정상적으로 돌아갔다. 최소 실행 버전은大致 다음과 같은 모습이다.
# ai-agent-book 第二章典型实验:ReAct 循环 + 单工具调用
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
def get_weather(city: str) -> str:
return f"{city} 今天晴,25°C"
TOOLS = {
"get_weather": get_weather,
}
SYSTEM = """你可以调用工具。格式:
Action: <tool_name>
Action Input: <json>
Observation: <result>"""
def run_agent(question: str, max_steps: int = 5):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": question},
]
for step in range(max_steps):
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
).choices[0].message.content
print(f"Step {step}:\n{resp}\n")
if "Action:" in resp and "Action Input:" in resp:
obs = get_weather("北京")
messages += [
{"role": "assistant", "content": resp},
{"role": "user", "content": f"Observation: {obs}"},
]
else:
break
run_agent("北京今天天气怎么样?")실행을 마치면 Step 0에 Action: get_weather와 Action Input이 포함되고, Step 1에서 최종 답변이 나온다. ReAct loop의 기본骨架는 이 정도면 충분하다.
103개 실험을 모두 실행하지는 않았다. 장마다 3~5개씩 있으므로 전부 돌리면 주말이 꼬박 필요할 것으로 보인다.
전체적인 인상은 다음과 같다. 콘텐츠 품질은 40k stars에 걸맞으며, “교재 + 실험 매뉴얼”에 가깝고 SDK와는 거리가 멀다.
추천 대상
이 책이 잘 맞는 사람:
- Agent의 이론적 기초를 체계적으로 쌓고 싶은 엔지니어: 흩어진 블로그를 읽는 것보다 효율적이다.
- 팀을 대상으로 Agent를 교육할 기술 책임자: 중국어 책과 연계 실험만으로 내부 교재로 활용할 수 있다.
- 다국어 Agent 자료를 찾는 연구자나 학생: 14개 언어를 폭넓게 제공한다.
- “오픈소스 기술서를 만드는 법”을 배우고 싶은 콘텐츠 크리에이터: 콘텐츠 엔지니어링과 다국어 운영 과정이 하나의 모범 사례가 된다.
적합하지 않은 사람:
- 바로 production에 투입할 완성된 Agent 프레임워크가 필요한 사람: 이 책은 SDK가 아니다.
- 특정 demo 하나만 실행하고 싶은 사람: 103개 실험에는 일정程度的 학습 비용이 든다.
- LangChain처럼高度로 추상화된 코드를 기대하는 사람: 책의 코드는 교육용에 가깝고 추상화가 적다.
Agent 분야를 개발하는 사람이라면 이 책의 제2장과 제6장至少는 살펴볼 가치가 있다. 제2장은 ReAct + Tool Use의 최소实践을 다루고, 제6장은 “비동기”와 “다중 모드”를 함께 설명한다. 2.0 버전에서 정보 밀도가 가장 높은 장이다.