이 노트는 무엇인가
"AI 에이전트"라는 말은 흔하지만, 그 안이 어떻게 생겼는지 코드 수준에서 설명해 주는 자료는 드뭅니다. 이 노트는 7일짜리 실습 강의에서 실제로 작성하고 실행한 코드를 날짜순으로 따라가며, 에이전트가 어떤 부품으로 이루어지고 각 부품이 왜 필요한지를 설명합니다.
누가 읽으면 좋은가
파이썬은 쓸 줄 알지만 LLM 응용 개발은 처음인 사람. 강의를 들었지만 시간이 지나 흐름을 다시 잡고 싶은 사람.
무엇이 들어 있나
개념 설명, 핵심 코드 조각과 줄 단위 해설, 실습 파일 전체, 강의 중에 만든 흐름도와 단계별 플레이어, 날마다의 용어 정리.
무엇이 들어 있지 않나
실행 결과 화면. 모델의 답은 부를 때마다 달라지므로, 결과를 베껴 두는 대신 무엇이 나와야 정상인지를 설명했습니다.
하루치 페이지의 구성
- 이 날 배우는 것그날의 목표를 대여섯 줄로 먼저 보여 줍니다. 여기만 읽어도 전체 윤곽이 잡힙니다.
- 개념 → 코드 조각 → 함정개념을 설명하고, 그 개념이 드러나는 코드 몇 줄을 원본의 줄 번호 그대로 보여 준 뒤, 실수하기 쉬운 지점을 짚습니다.
- 파일 전체각 섹션 끝에 실습 파일 전체가 접힌 채로 들어 있습니다. 코드 조각 위의 파일 이름을 누르면 그 파일이 펼쳐집니다.
- 강의 중 만든 설명 자료수업을 따라가며 만든 흐름도와 플레이어가 해당 대목에 끼워져 있습니다. 화면을 떠나지 않고 바로 열어 볼 수 있습니다.
- 정리와 용어하루를 한 문장으로 줄이고, 스스로 답해 볼 질문과 그날 나온 용어를 모았습니다.
어느 화면에서든 / 를 누르면 위쪽 찾기 칸으로 갑니다. 용어, 섹션 제목, 파일 이름으로 찾을 수 있습니다. 모르는 말이 나오면 용어 사전을 먼저 보세요.
7일 지도
7일은 따로따로인 주제 일곱 개가 아니라, 첫날 만든 것 위에 하루에 한 층씩 얹는 구조입니다. 각 층은 바로 전날의 결과물이 못하는 일 하나를 해결합니다.
LLM 호출부터 체인까지
모델을 부른다는 것이 어떤 요청과 응답인지, 메시지·토큰·temperature가 무엇인지 확인하고 프롬프트·모델·파서를 파이프로 잇습니다.
만든 것 → 사내 문의 접수 체인 22일차 · RAG문서를 찾아 읽고 답하는 RAG
모델이 모르는 사내 규정을 알려 주는 법. 문서를 쪼개고, 숫자로 바꿔 저장하고, 질문과 가까운 조각을 찾아 함께 보여 줍니다.
만든 것 → 규정 질의응답 체인과 평가 세트 33일차 · LangGraph되돌아갈 줄 아는 그래프
한 방향으로만 흐르는 체인의 한계를 넘습니다. 상태, 노드, 조건부 엣지, 루프를 익히고 ReAct 에이전트를 그래프로 조립합니다.
만든 것 → ReAct 에이전트 그래프 44일차 · 도구·MCP도구를 쥐여 주기
모델이 잘 쓰는 도구의 조건, 실패를 다루는 법, 그리고 도구를 별도 서버로 떼어 표준 규격으로 연결하는 MCP를 다룹니다.
만든 것 → 사내 데이터 MCP 서버와 Agent 55일차 · 기억·승인·가드기억하고, 멈추고, 막아내기
대화를 저장해 이어 가고, 위험한 행동 앞에서 멈춰 사람의 승인을 받고, 나쁜 입력과 새어 나가는 출력을 걸러 냅니다.
만든 것 → 승인 절차와 가드레일을 갖춘 Agent 66일차 · 멀티 에이전트여럿이 나눠 일하기
도구가 많아져 헷갈리는 단일 Agent를 전문 Agent 여럿으로 쪼개고, 관리자(Supervisor)가 일을 나눠 주게 합니다.
만든 것 → RAG + MCP + Supervisor 종합 시나리오 77일차 · 평가·운영계획하고, 기억하고, 채점하기
먼저 계획을 세우고 실행하는 구조, 대화방을 넘어 남는 장기 기억, 실행 추적, 그리고 쌓아 온 평가 세트로 자동 채점합니다.
만든 것 → 14문항 자동 평가 파이프라인에이전트 한 장 해부도
7일 동안 만든 부품을 한 그림에 놓으면 이렇게 됩니다. 처음 읽을 때는 낯선 말투성이겠지만, 한 바퀴 읽고 돌아와서 다시 보면 칸마다 어느 날의 무엇인지 떠오를 것입니다.
| 부품 | 하는 일을 한 문장으로 | 배우는 날 |
|---|---|---|
| 모델 호출 | 메시지 목록을 보내고 메시지 하나를 받는, 상태 없는 함수 호출 | 1일차 |
| RAG | 질문과 관련된 문서 조각을 먼저 찾아서 질문과 함께 모델에게 보여 주기 | 2일차 |
| 그래프와 ReAct 루프 | "생각 → 도구 사용 → 결과 확인"을 끝날 때까지 되풀이하는 흐름을 상태와 노드로 그리기 | 3일차 |
| 도구와 MCP | 모델이 부를 수 있는 함수를 설계하고, 그 함수를 별도 서버로 떼어 표준 규격으로 연결하기 | 4일차 |
| 체크포인터와 승인 | 진행 상태를 저장해 대화를 이어 가고, 위험한 단계에서 멈춰 사람의 결정을 기다리기 | 5일차 |
| 가드레일 | 들어오는 나쁜 요청과 나가는 민감한 정보를 규칙과 모델 판정으로 걸러 내기 | 5일차 |
| Supervisor | 질문을 보고 어느 전문 Agent에게 맡길지 정하고 결과를 모아 답하기 | 6일차 |
| 추적과 평가 | 실행 과정을 기록하고, 정해 둔 문항으로 답의 품질을 자동으로 채점하기 | 7일차 |
7일 내내 쓰는 무대 설정
실습은 전부 하나의 가상 상황 위에서 진행됩니다. 사내 직원의 질문에 답하는 업무 어시스턴트를 만든다는 설정이고, 날이 갈수록 이 어시스턴트가 할 수 있는 일이 늘어납니다. 등장하는 인물과 수치는 모두 교육용으로 지어낸 더미 데이터입니다.
읽을거리: 사내 규정 문서 3종
연차 규정, 재택근무 규정, 출장 규정. 2일차에 이 문서들을 벡터 DB에 넣고, 6일차에는 문서 검색 담당 Agent의 도구가 됩니다.
leave_policy.md remote_work_policy.md travel_policy.md
조회할 것: 사내 데이터 3종
임직원, 자산(노트북·모니터·GPU 서버), 프로젝트. 4일차에 이 데이터를 돌려주는 MCP 서버를 만들고, 이후 계속 재사용합니다.
employees.json assets.json projects.json
"연차 이월은 며칠까지 되나요?" 같은 질문은 1일차의 모델은 지어내서 답하고, 2일차부터는 문서를 찾아 근거와 함께 답하며, 7일차에는 그 답이 맞는지 자동으로 채점됩니다. 같은 질문에 대한 답이 날마다 어떻게 좋아지는지가 곧 이 강의의 줄거리입니다. 그래서 평가 문항도 버리지 않고 날마다 이어 붙입니다(2일차 5문항 → 7일차 14문항).
쓰는 도구들
처음 보는 이름이 많겠지만 역할로 나누면 여섯 무리입니다. 전체 목록은 레포의 requirements.txt 에 있습니다.
| 역할 | 쓰는 것 | 한 줄 설명 | 처음 나오는 날 |
|---|---|---|---|
| 모델 | Claude (AWS Bedrock). 주로 Sonnet 4.5, 일부 파일은 Haiku 4.5 · Sonnet 4.6 | 글을 읽고 쓰는 본체. boto3 또는 langchain-aws 의 ChatBedrockConverse 로 부릅니다 | 1일차 |
| 조립 틀 | langchain, langgraph | 앞의 것은 부품과 체인, 뒤의 것은 분기와 반복이 있는 그래프를 담당합니다 | 1일차, 3일차 |
| 검색 | langchain-chroma, Bedrock 임베딩, rank-bm25, kiwipiepy | 문서를 숫자 벡터로 바꿔 저장하고 찾는 벡터 DB, 낱말 일치 검색, 한국어 형태소 분석 | 2일차 |
| 도구 연결 | fastmcp, mcp, langchain-mcp-adapters | MCP 서버를 만들고, 그 서버의 도구를 Agent에 붙입니다 | 4일차 |
| 기억 | langgraph-checkpoint-sqlite | 대화의 진행 상태를 SQLite 파일에 저장합니다 | 5일차 |
| 여러 Agent | langgraph-supervisor, langgraph-swarm | 관리자가 나눠 주는 구조와, Agent끼리 직접 넘기는 구조 | 6일차 |
코드를 직접 돌려 보려면
읽기만 해도 되도록 썼지만, 손으로 돌려 보면 훨씬 오래 남습니다. 준비는 네 단계입니다.
- 가상환경을 만들고 패키지를 설치한다레포 루트에서 실행합니다. 파이썬 3.10 이상이 필요합니다.
Windows PowerShell
1python -m venv .venv 2.venv\Scripts\activate 3python -m pip install -r requirements.txt
- .env 파일을 만든다
.env.example을.env로 복사하고 AWS 키를 채웁니다. Bedrock에서 Claude 모델을 쓸 수 있는 계정이어야 합니다..env는 git에 올라가지 않으므로 다른 PC로 옮길 때는 따로 가져가야 합니다. - 환경을 점검한다
Windows PowerShell
1python day1_practice\check_env.py 2python day1_practice\check_credentials.py
- 그날 폴더로 들어가서 실행한다대부분의 파일은 같은 폴더의 다른 파일을 import 하거나 상대 경로로 데이터를 읽으므로, 해당
dayN_practice폴더 안에서 실행하는 것이 안전합니다.
실행 중에 생기는 파일은 git에 올리지 않았습니다. 벡터 DB는 2일차에서 python vectorstore.py, 6일차에서 python build_chroma.py 로 다시 만들고, 7일차는 6일차의 chroma_db 폴더를 복사해 씁니다. 5~7일차 폴더의 더미 데이터 JSON이 없으면 python make_data.py 로 만듭니다. 자세한 준비 절차는 5·6·7일차 폴더의 README.txt 에 있습니다.
모델을 부르는 스크립트는 실행할 때마다 Bedrock 사용 요금이 발생합니다. 3일차의 chain_limit.py, hello_graph.py, branch_loop_graph.py 처럼 모델을 부르지 않는 파일도 있으니, 구조만 확인하고 싶을 때는 그런 파일부터 돌려 보세요.
이 사이트에 대하여
이 사이트는 서버 없이 열리는 정적 HTML이고, Cloudflare Pages에 올려 공유합니다. 레포를 받았다면 빌드한 뒤 dist/index.html 을 브라우저로 열어도 똑같이 보입니다. 글꼴(도현, 주아)은 인터넷에서 받아 오므로 오프라인에서는 기본 글꼴로 보입니다.
페이지에 실린 코드는 레포의 실습 파일을 빌드할 때 그대로 읽어 넣은 것입니다. 실습 코드나 원고(handbook/_src/*.html)를 고쳤다면 다시 빌드합니다. 줄 번호가 어긋났거나 빠진 파일, 없는 자리로 가는 링크가 있으면 이때 알려 줍니다.
1python -m pip install -r handbook/requirements.txt 2python handbook/build.py
고친 내용을 사이트에 반영하려면, 빌드한 뒤 Cloudflare에 로그인된 상태에서 dist/ 폴더를 그대로 올립니다.
1npm install 2npx wrangler login 3npm run deploy