프레임워크없이만드는AI에이전트입문

AI 에이전트, 안에서는 무슨 일이 일어나고 있을까요?

Claude Code나 Codex 같은 코딩 에이전트에게 "테스트 좀 고쳐 줘"라고 하면, 알아서 파일을 열고 테스트를 돌리고 코드를 고칩니다. 그런데 막상 직접 만들어 보려고 하면 어디서부터 시작해야 할지 막막하죠. 프레임워크 예제를 따라 하면 돌아는 가는데, 왜 도는지는 잘 안 보입니다. 모델이 같은 파일을 열 번 읽거나, 비용이 예상보다 몇 배 나오거나, 하지 말아야 할 파일을 덮어쓸 때 어디를 고쳐야 할지 모르게 되고요.

이 강의는 그 안쪽을 직접 만들어 보는 강의입니다. 결론부터 말하면, 에이전트의 뼈대는 while 문 하나입니다. 모델에게 묻고, 모델이 도구를 써 달라고 하면 실행해서 결과를 돌려주고, 다시 묻는 것. 우리는 이 루프에서 출발해 한 편에 부품 하나씩 붙여 갑니다.

마지막에 이런 걸 만듭니다

8편에서 완성하는 에이전트는 실패하는 테스트가 있는 작은 프로젝트를 받으면, 테스트를 돌리고 → 실패 메시지와 코드를 읽고 → 고칠 내용을 diff로 보여 주며 허락을 받고 → 다시 테스트해서 통과할 때까지 루프를 돕니다. 아래는 실제 녹화 화면이에요. 모델을 다섯 번 불렀고, 실제로 청구된 돈은 $0.00056이었습니다.

7편에서는 같은 루프를 FastAPI 서버에 올려 브라우저에서 질문하고, 모델이 한 회차를 끝낼 때마다 진행 상황이 한 줄씩 실시간으로 올라오는 화면을 만듭니다. 루프는 그대로 두고 바깥 껍데기만 바꾸는 거죠.

왜 프레임워크 없이 만드나요?

프레임워크가 나쁘다는 이야기는 아닙니다. 다만 처음 배울 때는 프레임워크가 감춰 주는 부분이 바로 우리가 알아야 할 부분이에요. 모델이 도구를 "직접" 실행하는 게 아니라 요청서(tool_calls)를 쓸 뿐이라는 것, 대화 기록을 매번 통째로 다시 보내서 입력 토큰이 계속 늘어난다는 것, 같은 질문에도 결과가 매번 다르다는 것. 이런 건 코드를 한 줄씩 직접 써 봐야 몸에 붙습니다.

그래서 이 강의는 OpenAI SDK와 Python 표준 라이브러리로 에이전트를 만듭니다. 웹 화면(7편)과 연습용 가짜 서버(3편)에만 FastAPI를 씁니다. 모델은 OpenRouter를 거쳐 DeepSeek·GLM 같은 저렴한 모델을 부르고, 코드에서 MODEL 한 줄만 바꾸면 다른 모델로도 돌릴 수 있어요. 구조를 알고 나면 어떤 프레임워크 문서를 봐도 "아, 이게 그 루프구나" 하고 읽힐 겁니다.

강의 특징

1. 매 편 실제로 돌린 화면과 실제 청구액을 보여 줍니다. 영상 속 터미널과 브라우저는 모두 실제 OpenRouter 호출을 녹화한 것입니다. 비용도 가격표로 계산한 추정치가 아니라 응답에 들어 있는 실제 청구액(usage.cost)으로 봅니다. 제작 중에 같은 모델인데도 실제 청구액이 가격표 계산의 약 3배가 나온 일이 있었는데, 3편에서 그 원인과 막는 법을 그대로 다룹니다.

2. 본편마다 과제와 과제 해설 영상이 따로 있습니다. 1~8편 본편 끝에 과제가 세 개씩 나오고, 바로 다음 수업이 그 과제를 푸는 해설 영상입니다. 먼저 혼자 풀어 보고, 막히면 해설을 보세요. 해설 영상은 원래 코드와 바뀐 코드를 diff로 비교하고 실제로 실행까지 해 봅니다.

3. 글 튜토리얼 PDF와 공개 코드 저장소가 함께 있습니다. 영상에서 지나간 명령과 예상 출력은 편마다 있는 글 튜토리얼에 단계별로 다시 정리되어 있습니다. 코드는 편마다 독립 폴더라서 어느 편부터 봐도 실행됩니다.

4. 실패를 일부러 만들어 봅니다. 무한 반복, 깨진 JSON, 없는 도구 호출, API 오류(429·500)를 API 키 없이 재현하는 연습용 가짜 서버를 3편에서 제공합니다. 안전장치가 정말 작동하는지 눈으로 확인하는 거죠.

무엇을 배우나요? (섹션별)

섹션 0. 오리엔테이션 — 무엇을 만들지, 에이전트 부품 8가지(모델·도구·루프·실패/비용·기억·승인·평가·화면), 필요한 기초 지식(Python·터미널·API·LLM 토큰)을 훑고, 점검 스크립트로 실습 준비를 끝냅니다.

섹션 1. 에이전트의 뼈대: 루프와 도구 — 1편에서 도구가 없는 모델 → 요청서를 쓰는 모델 → 요청을 실행하는 루프 순서로 첫 에이전트를 만듭니다. 2편에서는 도구가 늘어날 때 쓰는 도구 등록표 패턴을 만들고, 나쁜 설명과 좋은 설명이 모델의 행동을 어떻게 바꾸는지 같은 질문으로 비교합니다.

섹션 2. 실패·비용과 기억 — 3편에서 루프가 망가지는 대표적인 경우를 하나씩 만들고 최대 회차·비용 상한·반복 감지·재시도로 막습니다. 4편에서는 계속 커지는 대화 기록을 줄이고 요약하고, 세션을 저장했다가 이어 가고, 메모 도구로 장기 기억을 붙입니다.

섹션 3. 사람 승인과 평가 — 5편에서 위험한 도구는 실행 전에 diff를 보여 주고 사람에게 묻게 만듭니다. 거절도 결과로 모델에게 돌려줘요. 6편에서는 "잘 된다"를 숫자로 잽니다. 평가 세트를 만들어 여러 번 돌리고 통과율·평균 비용·평균 호출 수를 내서 두 모델을 비교합니다.

섹션 4. 웹 화면과 종합 프로젝트 — 7편에서 루프를 함수로 분리해 FastAPI와 SSE로 브라우저에 실시간 로그를 띄웁니다. 8편에서는 1~7편의 부품을 한 파일에 모아 실패하는 테스트를 고치는 미니 코딩 에이전트를 완성하고, 버그 3종을 고치는지 평가까지 돌립니다. 마지막에 Claude Code·Codex 같은 실제 코딩 에이전트와 구조를 나란히 비교해 봅니다.

이런 분께 추천해요

• check_circlePython 기초는 알지만 AI API로 무언가를 만들어 본 적은 없는 개발자
• check_circle프레임워크로 에이전트를 만들어 봤는데, 그 안에서 무슨 일이 일어나는지 궁금한 분
• check_circle코딩 에이전트를 매일 쓰면서 "이게 어떻게 돌아가지?"가 궁금했던 분
• check_circle사내 자동화용 작은 에이전트를 직접 만들고 비용과 실패를 스스로 통제하고 싶은 분

이런 분께는 맞지 않을 수 있어요

• check_circlePython을 처음 배우는 분. 함수·dict·반복문은 안다고 가정하고 진행합니다(0편에서 짧게 다시 훑기는 합니다)
• check_circleLangChain·LangGraph 같은 특정 프레임워크 사용법을 배우고 싶은 분
• check_circle모델 학습·파인튜닝이나 RAG(벡터 검색)를 배우고 싶은 분. 이 강의는 이미 있는 모델을 도구와 루프로 엮는 쪽만 다룹니다
• check_circle배포·운영까지 다루는 실서비스 강의를 찾는 분. 7·8편 서버는 교육용으로 내 컴퓨터(127.0.0.1)에서만 엽니다

무엇을 받나요?

• check_circle영상 17개, 약 2시간 40분: 본편 9개(0~8편, 1시간 43분) + 과제 해설 8개(약 1시간)
• check_circle글 튜토리얼·과제 풀이 PDF 18개와 부록 PDF 2개(파이썬 기초 문법 정리, 에이전트 기초 개념 정리), 모두 20개 228쪽
• check_circle공개 GitHub 저장소의 예제 코드와 과제 풀이 코드: https://github.com/dante01yoon/agent-from-scratch
• check_circle3편 연습용 가짜 서버(API 키 없이 실패 상황 재현), 8편 버그를 심어 둔 샘플 프로젝트와 평가 스크립트

수강 전 참고 사항

• check_circle환경: Python 3.10 이상, uv, OpenRouter API 키(크레딧 충전 필요). macOS·Linux에서 녹화·검증했고, Windows는 WSL(Ubuntu)을 권합니다. 5편 명령 실행 도구가 ls, cat, grep 같은 Unix 명령을 쓰기 때문이에요.
• check_circle비용: 강의를 따라 한 번씩 실행하면 편당 1센트 안팎이었습니다(2026-10-04 실제 청구액). 예를 들어 1편 실습 파일 세 개를 한 번씩 돌리는 데 $0.0007이 들었습니다.
• check_circle모델과 가격은 바뀝니다: 영상의 모델 ID·가격은 2026-10-04 OpenRouter 기준입니다. 실습 전에 OpenRouter 모델 목록에서 다시 확인하세요. 실행할 때마다 호출 수와 비용이 조금씩 다른 건 정상입니다.
• check_circle자막: 영상 아래쪽에 자막이 이미 들어가 있습니다.
• check_circle배경 음악은 없습니다. 코드와 설명에 집중할 수 있게 뺐습니다.

예상 질문 Q&A

Q. API 비용이 많이 들까 봐 걱정돼요. 따라 하는 실습은 편당 1센트 안팎이었습니다. 3편에서 회차·비용 상한을 거는 법을 배우니, 실험을 크게 늘리기 전에 3편까지 먼저 보세요.

Q. 강의 속 모델이 없어지거나 가격이 바뀌면요? .env의 MODEL 한 줄만 바꾸면 도구 호출을 지원하는 다른 모델로 돌릴 수 있습니다. 6편에서 만드는 평가 스크립트로 새 모델이 기존만큼 잘하는지 숫자로 확인할 수도 있어요.

Q. 중간 편부터 들어도 되나요? 네. 코드가 편마다 독립 폴더라 어느 편부터 실행해도 됩니다. 다만 1편의 루프 구조는 모든 편의 바탕이라 1편은 꼭 보길 권합니다.

수강 기한

결제일로부터 12개월 동안 들을 수 있습니다. 미리보기(0편·1편)는 로그인하면 결제 전에도 볼 수 있습니다.

※ 명확한 음성 전달을 위해, 제작·검토를 마친 대본을 지식공유자 본인 목소리 기반의 음성 합성(TTS)으로 읽었습니다.