AI 에이전트 구축은 마법이 아니라 엔지니어링입니다.

AI 에이전트를 구축하는 것은 마법이 아니라 엔지니어링입니다. 에이전트에 대한 글을 읽는 것을 멈추고, 직접 만들어 보세요.

이 저장소(repo)는 Claude Code, Claude Cowork, Codex, 그리고 GitHub Copilot과 같은 인기 있는 에이전트 뒤에 숨겨진 원리를 이해하고, 자신만의 에이전트를 구축하려는 엔지니어들을 위한 것입니다.

• 🔁
  전체 과정— 첫 LLM 호출부터 프로덕션 평가(eval) 하니스까지 - 🧱
  화려한 프레임워크는 없습니다— 단지 LLM API, 몇 가지 도구(tools), 그리고 루프(loop)만 필요합니다 - 🌱
  사전 AI/ML 경험이 필요하지 않습니다— Python 기본 지식과 호기심만 있으면 충분합니다.

💡 이번 주말에 하나를 구축해 보세요. 100개의 블로그 게시물을 읽는 것보다 에이전트를 더 잘 이해하게 될 것입니다.

이것이 유용하다고 생각되면, ⭐ 별점을 눌러주시면 저희가 올바른 방향으로 가고 있다는 것을 알 수 있습니다. 💬 토론에 참여하거나 🐛 이슈를 보고해 주세요— 여러분의 의견은 우리가 다음에 무엇을 구축할지 직접적으로 형태를 갖춥니다.

• 📦
  블랙박스 없이, 기본 원리부터. 사용자가 에이전트 루프, 도구 실행기(tool executor), 메모리 계층(memory layer), 평가 하니스(eval harness)를 처음부터 구축합니다—어떤 프레임워크도 소개되기 전에. 어떤 추상화가 숨기고 있는지 배우고, 그것에 의해 자신을 맡기기 전에 배웁니다. - ⚡
  한 명령어로 실행 가능합니다. uv run --directory <tutorial> python <script>.py

. conda 작업이나 Jupyter 커널 찾기는 필요 없습니다. - 🔬
우리는 프로덕션 에이전트를 분해합니다. Disassembling AI Agents Substack 시리즈는 Claude Code, GitHub Copilot, OpenCode를 리버스 엔지니어링(reverse-engineers) 합니다. 실제 에이전트가 어떻게 작동하는지 읽고, 여기서 그 조각들을 재구축해 보세요.

에이전트 숙련도는 새로운 데이터 구조 인터뷰입니다. 저희는 이를 기본 원리부터 가르칩니다—프레임워크를 소개하기 전에 스스로 루프, 도구 호출(tool calls), 메모리, 평가(evals)를 구축하게 됩니다. 마법은 없습니다. 블랙박스도 없습니다. 단지 발명된 순서대로의 기본 요소들만 있습니다.

Geoffrey Huntley
Ralph Wiggum의 창조자
|
여러분 중 실제로 화이트보드를 꺼내서 에이전트를 구축할 수 있는 사람이 얼마나 되나요? 추론 루프(inferencing loop)를 보여줄 수 있습니까?
만약 이것을 모른다면, 당신의 커리어는 위험에 처해 있습니다. 도구 호출(tool call)이란 무엇입니까? 그것이 무엇인지 모른다면, 그것이 무엇인지 배워야 하고 이 모든 기본적인 기초 지식들을 익혀야 합니다. 저는 후보자가 도구 호출이 무엇인지, 추론 루프가 어떻게 작동하는지 아는 경우를 선호합니다. 화이트보드를 꺼내서 — 예전에 우리가 '연결 리스트(linked list)를 보여줘', '이 자료 구조를 역순으로 만들어봐'라고 했던 것과 같은 방식으로 말이죠.
이것은 이제 기본 지식이 되었습니다. 왜냐하면 저희가 이런 내용을 답변할 수 있는 후보자들을 만나고 있기 때문입니다. |

모든 답은 이 리포지토리에 있습니다. 도구 호출이 무엇인지, 추론 루프가 어떻게 작동하는지, 컨텍스트(context)에 무엇이 담겨 있는지 — 여러분은 단순히 답을 읽는 것이 아니라, 01 - Foundations부터 시작하여 직접 손으로 구축하게 될 것입니다. 다음 인터뷰에서는 당신이 화이트보드에서 그 루프를 그리게 될 겁니다.

brew install uv # 또는: pipx install uv
git clone https://github.com/agenticloops-ai/agentic-ai-engineering.git
cd agentic-ai-engineering
...

그게 전부입니다. 모든 튜토리얼은 자체적으로 완결성이 있고(self-contained) 반복 가능하며(idempotent) — 어디서든 시작할 수 있습니다. 전체 설정 세부 정보는 SETUP.md를 참고하세요. 아니면 Codespaces에서 열어 로컬 설정을 완전히 건너뛸 수도 있습니다.

여러분의 첫 단계 — 단일 API 호출부터 완전 자율 에이전트 루프까지. 내부적으로 실제로 무슨 일이 일어나고 있는지 이해하기 위해 모든 것을 처음부터 구축하십시오.

간단한 LLM 호출(Simple LLM Call)— 토큰 추적을 포함한 첫 번째 API 호출
프롬프트 엔지니어링(Prompt Engineering)— 모델 행동 안내
채팅(Chat)— 메시지 기록이 있는 대화형 채팅
도구 사용(Tool Use)— 함수 호출 활성화
에이전트 루프(Agent Loop)— 자율적인 도구 사용 에이전트
코드베이스 네비게이터(Codebase Navigator)— RAG, 도구, 메모리를 갖춘 증강된 LLM

장난감 데모와 실제 에이전트를 구분하는 아키텍처 패턴. Anthropic의

프롬프트 체이닝 (Prompt Chaining)— 순차적 다단계 파이프라인 라우팅 (Routing)— 입력 분류 및 전문 핸들러로 분배 병렬화 (Parallelization)— 팬-아웃/팬-인, 병렬 도구 호출 오케스트레이터-워커 (Orchestrator-Workers)— 동적 작업 분해 평가자-최적화기 (Evaluator-Optimizer)— 자체 비판 및 반복적 개선 휴먼 인 더 루프 (Human in the Loop)— 승인 게이트, 에스컬레이션, 피드백 콘텐츠 라이터 (Content Writer)— 모든 에이전트 워크플로우 패턴을 구성하는 완전한 에이전트

프로토타입 단계를 벗어나는 순간 마주하게 될 실제 엔지니어링 문제들입니다. 컨텍스트(Context), 비용(Cost), 메모리(Memory), 멀티모달리티(Multimodality), 안전성(Safety) 등— 튜토리얼 하나하나를 거치며 해결해 나갑니다.

구조화된 출력 (Structured Output)— JSON 모드, 스키마, 제약형 생성 스트리밍 (Streaming)— SSE, 토큰별 출력, 스트리밍 도구 호출 컨텍스트 엔지니어링 (Context Engineering)— 윈도우 전략, 요약, 도구 컨텍스트 비용 최적화 (Cost Optimization)— 프롬프트 캐싱, 모델 라우팅 메모리 (Memory)— 단기, 장기, 메모리 검사 RAG 기법 (RAG Techniques)— 하이브리드 검색, 에이전트 기반 검색 멀티모달 (Multimodal)— 비전, 이미지 생성, 오디오 가드레일 (Guardrails)— 입력/출력 필터링, 안전 패턴

에이전트는 비결정적(non-deterministic)입니다. 따라서 테스트를 위해서는 다른 사고방식이 필요합니다. 배포하기 전에 품질을 측정하고, 회귀 현상을 포착하며, 신뢰도를 구축해야 합니다.

에이전트 단위 테스트 (Unit Testing Agents)— LLM 목킹, 결정론적 테스트 평가 (Evals)— 정확도, 품질, 회귀 벤치마크 추적 및 디버깅 (Tracing & Debugging)— 개발 중 관측 가능성(Observability) 확보 레드팀 및 안전성 (Red Teaming & Safety)— 적대적 테스트, 가드레일 벤치마킹 (Benchmarking)— 모델, 프롬프트, 아키텍처의 정면 비교 평가 프레임워크 (Eval Frameworks)— Promptfoo, Braintrust, Langfuse 통합 평가 하네스 (Eval Harness)— 모든 기술을 결합한 완전한 평가 파이프라인

단순 에이전트 루프를 가져와서 활용해 보세요. 스킬(Skills), 훅(Hooks), 샌드박싱(Sandboxing), MCP, 서브에이전트(Subagents), 압축(Compaction) 등— 하나의 제어 표면(control surface)을 거치며— 단순한 루프를 실제적이고 확장 가능한 에이전트로 바꿀 수 있습니다.

스킬(Skills) — 파일 시스템 에이전트 스킬, 점진적 공개(progressive disclosure)
훅 및 라이프사이클(Hooks & Lifecycle) — 도구 사용 전/후 및 중지 이벤트 가로채기
샌드박싱(Sandboxing) — 리소스 제한을 통해 에이전트 실행 코드 격리
MCP 통합(MCP Integration) — MCP 서버에서 도구 검색, 자체 도구 게시
서브에이전트 및 위임(Subagents & Delegation) — 격리된 컨텍스트를 가진 자식 루프 생성
컨텍스트 압축(Context Compaction) — 장기 실행 루프의 기록 압축
확장 가능한 에이전트(Extensible Agent) — 훅 + 샌드박스 + MCP + 서브에이전트 + 압축 결합

하나의 에이전트를 아홉 가지 구현으로 만듭니다. 각 프레임워크로 동일한 시스템을 구축하고 직접 트레이드오프를 비교해 보세요.

No Framework — 순수 SDK 기준선
LangGraph — 그래프 기반 오케스트레이션
Pydantic AI — 타입 안전 에이전트
Google ADK — Google의 에이전트 개발 키트
AWS Strands — AWS 에이전트 SDK
CrewAI — 역할 기반 다중 에이전트 협업
AutoGen — 다중 에이전트 대화
LlamaIndex — 데이터 중심 에이전트
Semantic Kernel — Microsoft AI 오케스트레이션

"내 노트북에서 작동하는 것"과 "대규모로 안정적으로 실행되는 것" 사이의 격차. 원칙, 배포, 모니터링, 비용 제어, 보안.

12-Factor Agents — 프로덕션급 에이전트를 위한 원칙
배포 전략(Deployment Strategies) — 컨테이너, 서버리스, 확장성
모니터링 및 관측 가능성(Monitoring & Observability) — 운영 환경에서의 메트릭, 로깅, 추적
비용 최적화(Cost Optimization) — 토큰 예산, 캐싱, 모델 라우팅
보안 및 가드레일(Security & Guardrails) — 인증, 샌드박싱, 주입 방어
오류 처리 및 복원력(Error Handling & Resilience) — 재시도, 폴백, 우아한 저하

튜토리얼은 기초부터 고급 개념까지 진행하는 모듈(modules) (01-foundations, 02-effective-agents)로 구성되어 있습니다. 각 모듈에는 이전 학습 내용을 기반으로 하는 번호가 매겨진 **튜토리얼(tutorials)**이 포함되어 있습니다. 각 튜토리얼 폴더 안에서는 다음을 찾을 수 있습니다:

Python 스크립트 - 핵심 개념을 시연하는 독립적이고 실행 가능한 예제
README.md - 상세한 설명, 코드 워크스루, 학습 목표

개별 스크립트를 독립적으로 탐색하거나 시작부터 끝까지 전체 학습 경로를 따라갈 수 있습니다. 각 모듈은 해당 모듈의 모든 개념을 하나의 프로덕션 스타일 에이전트에 결합하는 프로젝트로 마무리됩니다.

튜토리얼은 여러분에게 '만드는 방법'을 가르쳐줍니다. 저희 Substack에서는 먼저 정신적 모델(mental model)을 제공합니다. 이는 에이전트가 실제로 어떻게 작동하는지에 대한 기초적인 입문 자료이며, 매일 사용하는 실제 프로덕션 에이전트를 분해 분석(teardowns)하여 보여줍니다. 게시글을 읽고, 튜토리얼을 열어보세요. 패턴을 재구축하세요.

에이전트 작동 원리: 마법 뒤의 패턴들 - 첫 번째 원칙부터 핵심 에이전트 루프를 다룹니다. 네 가지 패턴 레벨(one-shot → single-tool → ReAct → planning), 행동 설계로서 시스템 프롬프트의 역할, 그리고 아우터 루프(outer loop)로서의 Ralph Mode에 대해 알아봅니다. 리포지토리를 열어보기 전에 이 글을 읽는 것을 추천합니다. $
ightarrow$ 01-foundations

만약 이 프로젝트가 유용하다고 생각되신다면, 저희를 후원하는 것을 고려해 주세요:

모듈을 찾을 수 없나요? 레슨 디렉토리에서 uv sync를 실행하세요.

API 오류 또는 인증 실패인가요? 어떤 예제를 실행하느냐에 따라 Anthropic, OpenAI 또는 둘 다의 API 키가 필요합니다. 자세한 내용은 SETUP.md를 참고하세요.

이 프로젝트는 MIT 라이선스 하에 배포되며, 자세한 내용은 LICENSE 파일을 확인해 주세요.