A반(교육 선행형) 1주차 라이브 세션 교안입니다.
세션은 멘토 시연 중심으로 진행하며, 수강생이 세션 중 직접 손을 움직이는 구간은 개인 repo 개설 실습뿐입니다.
시연 코드·지시 프롬프트·영상은 세션 후 전부 공개되어, 각자의 속도로 재현할 수 있습니다.
- 주제: AI 서비스 전주기 이해
- 세션 포커스: 과정 조망, 엔지니어링 사다리, 프로젝트 트랙 소개, 개인 repo 개설
- 산출물: 학습 목표 + 개인 repo
- 시연 저장소: week01-order-agent
- 운영 방식: 멘토 시연 → 코드·프롬프트 공개 → 영상 아카이브 (코드 따라 쓰기 없음)
이 자료를 내 컴퓨터에서 보기: 강의 사이트 저장소를 클론해 Docker로 띄우면 이 문서와 슬라이드를 로컬에서 볼 수 있고, 새 자료가 올라오면
git pull로 받아봅니다.git clone https://github.com/2026-ai-service-engineering-a/ai_service_engineering-track_a cd ai_service_engineering-track_a docker compose up --build # http://localhost:4321 접속 # 새 자료 받기: git pull 한 뒤 다시 docker compose up --build자세한 방법은 로컬에서 강의 자료 보기, Docker가 처음이라면 Docker와 Docker Compose, 처음이라면을 참고하세요.
1. 세션 목표
세션이 끝나면 다음을 얻게 됩니다.
- AI 서비스가 5개 레이어(Agents / AI Platform / Models / Data / AI Infrastructure) 위에서 어떻게 실행되는지에 대한 지도
- 엔지니어링 사다리(프롬프트 → 컨텍스트 → 하네스)가 14주 커리큘럼의 순서인 이유
- “이 시대에 에이전트를 만드는 방식”: AI 코딩 도구에 요구사항을 지시하고, 생성물을 검증·수정하는 사이클을 직접 목격
- 5개 프로젝트 트랙이 “같은 구조에서 무엇을 갈아끼우는가”의 차이라는 감각
- 개인 GitHub repo (학습 목표 작성 완료)
1주차 시연의 성격. 1주차 시연의 목적은 코드 이해가 아니라, “14주 뒤 내가 만들 것의 축소판”과 “그것을 만드는 방식”을 눈으로 확인하는 것입니다. 코드 한 줄 한 줄이 아니라 구조와 사이클이 남으면 성공입니다.
2. 오리엔테이션
2-1. 과정 목표
개인별 배포 가능한 오픈소스 기반 AI 데모 서비스 1개 완성
- 공개 데모 URL
- GitHub 포트폴리오 (README·아키텍처·라이선스 문서화)
- 최종 발표 (직무 전환 포인트 정리)
2-2. 14주 구조
- 1~9주: 공통 역량 구간 (템플릿 기반 실습, 전원 동일 산출물)
- 10~14주: 개인 프로젝트 구간 (기획 → MVP → 배포 → 문서화 → 발표)
flowchart TD
subgraph common["공통 역량 구간 (1~9주)"]
direction LR
W1["1주<br/>전주기 이해"] --> W2["2주<br/>개발환경"] --> W3["3주<br/>LLM·프롬프트"] --> W4["4주<br/>데이터·RAG"] --> W5["5주<br/>API·도구"] --> W6["6주<br/>루프·하네스"] --> W7["7주<br/>트랙 패턴"] --> W8["8주<br/>FastAPI"] --> W9["9주<br/>자유 UI"]
end
subgraph project["개인 프로젝트 구간 (10~14주)"]
direction LR
W10["10주<br/>기획"] --> W11["11주<br/>MVP"] --> W12["12주<br/>배포·평가"] --> W13["13주<br/>문서화·OSS"] --> W14["14주<br/>발표"]
end
common --> project매주 템플릿 형식의 실습이 제공됩니다. 3주차 LLM 호출, 4주차 RAG 검색, 6주차 에이전트, 8주차 API 서버 등 주차별 템플릿은 그대로 개인 프로젝트의 부품으로 재조립할 수 있고, 원한다면 템플릿과 별개로 자기 방식대로 프로젝트를 진행해도 됩니다. 템플릿은 출발점이지 제약이 아닙니다.
2-3. 운영 방식
- 라이브 세션 = 멘토 시연 + 코칭. 코드 따라 쓰기 없음
- 매주 시연 코드·지시 프롬프트·영상을 공개합니다. 각자의 속도로 재현하면 됩니다.
flowchart LR
subgraph live["라이브 세션 (매주)"]
D["멘토 시연<br/>빈 골격 → 동작하는 결과"]
end
subgraph assets["공개 자산 3종"]
C1["코드<br/>(v0.1 → v1.0 태그)"]
C2["지시 프롬프트<br/>(PROMPT.md)"]
C3["영상"]
end
D --> C1 & C2 & C3
C1 & C2 & C3 --> R["수강생 비동기 재현<br/>(각자 속도로)"]개인 프로젝트 계획은 백그라운드로 병행됩니다.
- 프로젝트는 10주차에 시작하는 것이 아닙니다. 1주차부터 각자 “무엇을 만들지”에 대한 계획 세우기가 백그라운드 과제로 깔립니다.
- 매주 실습·시연을 보며 “내 프로젝트라면 이 부품을 어떻게 쓸까”를 계속 생각해 보세요.
- 트랙 가결정(7주차) → 기획 확정(10주차)은 이 백그라운드 사고의 체크포인트일 뿐입니다.
flowchart TB
subgraph template["전면 — 템플릿 실습 (매주 제공)"]
direction LR
T1["1주<br/>주문 에이전트"] --> T3["3주<br/>LLM 호출"] --> T4["4주<br/>RAG 검색"] --> T6["6주<br/>에이전트"] --> T8["8주<br/>API 서버"] --> T9["9주~<br/>멘티 코드 리뷰<br/>또는 추가 템플릿"]
end
subgraph proj["백그라운드 — 개인 프로젝트 (10주차부터 전면으로)"]
direction LR
P1["1주~<br/>만들 것 구상"] --> P7["7주<br/>트랙 가결정"] --> P10["10주<br/>기획 확정"] --> P14["11~14주<br/>MVP → 배포 → 발표"]
end
template -. "부품 재사용 (선택) — 별도 진행도 가능" .-> proj- 점선의 의미: 템플릿 부품의 재사용은 선택입니다. 그대로 재조립해도 되고, 별도로 진행해도 됩니다.
- 두 레인은 10주차에 자리를 바꿉니다. 템플릿 실습이 배경으로 물러나고, 백그라운드에서 자라던 개인 프로젝트가 전면으로 나옵니다.
질문은 디스코드로 상시 열려 있습니다.
- 라이브 세션 사이의 질문은 디스코드에서 계속할 수 있습니다. 세션까지 기다릴 필요가 없습니다.
- 용도 예시
- 시연 재현 중 막히는 지점
- 개인 프로젝트 구상·트랙 선택 관련 논의
- 환경 문제 (devcontainer, 키 발급 등)
9주차부터 시연의 성격이 바뀔 수 있습니다.
- 멘티가 동의하는 경우: 멘티 코드를 기반으로 한 리뷰 형식으로 전환합니다. 실제 진행 중인 프로젝트 코드를 함께 보며 구조·개선점을 짚는 시간입니다.
- 코드·프로젝트 공개에 동의하지 않는 경우: 별도의 템플릿 에이전트를 추가로 만들어 시연을 제공합니다. 공개 자산(코드·프롬프트·영상) 파이프라인은 동일하게 유지됩니다.
- 어느 쪽이든 멘티의 선택이며, 공개는 권장 사항이지 요건이 아닙니다.
기타 안내:
- 시연·재현 전반에 걸친 AI 도구 활용 원칙 예고: “직접 판단한 부분과 AI가 보조한 부분을 구분한다.” 오늘 멘토가 그 구분을 시연으로 먼저 보여드립니다.
2-4. 운영 안내: 요일·저장소·모임
강의 요일·시간 (조율 예정)
- 모든 세션은 녹화본이 제공됩니다. 실시간 참석이 어려워도 학습에 지장이 없습니다.
- 현재 토요일로 잡혀 있으나, 다음 두 후보 중 하나로 조정을 제안합니다.
- 목요일 저녁
- 토요일 오후 2시
- 1주차에 수강생 의견을 들어 확정합니다.
GitHub 조직과 개인 저장소
- 조직
2026-ai-service-engineering-a는 멘토 코드를 공유하기 위한 공간입니다 (주차별 시연 레포) - 수강생 저장소는 개인 계정에 만드는 것을 권장합니다. 과정이 끝나도 포트폴리오로 개인이 가져가는 것이기 때문입니다.
- 조직 안에 만들어도 무방합니다. 강제 사항이 아닙니다.
- 개인 저장소에 대한 코칭도 가능합니다. 다만 프로젝트 제출의 경우 오픈소스가 되어야 하므로, 일부를 오픈소스로 분리해서 제작하거나, 아니면 별도의 내용을 오픈소스로 만들기를 권장합니다.
월 1회 오프라인 모임
- 강의 요일과 겹치지 않게 배치합니다.
- 강의가 평일이면 → 오프라인은 토요일
- 강의가 토요일이면 → 오프라인은 평일 저녁 (목요일 또는 금요일)
- 참석은 자유입니다. 불참해도 불이익이 없습니다.
3. 전주기 조망
같은 5레이어 다이어그램을 두 번 봅니다. 1차는 업계 일반 버전, 2차는 우리 과정 스택을 오버레이한 버전입니다. 이 그림이 이후 9주의 좌표계가 되며, 매주 브리핑 첫 슬라이드에서 “오늘은 이 칸”을 하이라이트합니다.
3-1. 일반 버전: 각 레이어의 책임
| 레이어 | 책임 | 대표 예시 |
|---|---|---|
| Agents | 제어 루프: 무엇을 할지 판단하고 도구를 부름 | self managed / vendor managed |
| AI Platform | 모델 접근·라우팅·인증·관측 | Vertex AI, AI Studio, MCP 서버 |
| Models | 실제 추론 | Gemini, Claude, GPT, Llama, DeepSeek |
| Data | 모델이 볼 재료 공급: retrieval, 스토리지 | BigQuery, S3, Drive, Slack |
| AI Infrastructure | 연산이 실제로 도는 곳 | GPU/CPU, GKE, Compute |
flowchart TB
U(["사용자"]) --> L1
subgraph stack["AI 서비스 스택"]
direction TB
L1["Agents<br/>제어 루프 · 판단 · 도구 호출"]
L2["AI Platform<br/>모델 접근 · 라우팅 · 인증 · 관측"]
L3["Models<br/>추론 (Gemini · Claude · GPT · Llama)"]
L4["Data<br/>retrieval · 스토리지 · 컨텍스트 재료"]
L5["AI Infrastructure<br/>GPU/CPU · 컨테이너 · 서빙 기반"]
L1 --> L2 --> L3 --> L4 --> L5
end3-2. 실행 흐름 트레이스: 요청 하나가 스택을 타고 내려갑니다
정적인 층 그림만으로는 “왜 다 필요한지”가 안 보입니다. 질문 하나가 실제로 어떻게 흐르는지 시퀀스로 트레이스합니다.
sequenceDiagram
actor U as 사용자
participant A as Agents<br/>(제어 루프)
participant P as AI Platform<br/>(중개)
participant M as Models<br/>(추론)
participant D as Data<br/>(재료)
U->>A: "참치김밥 두 줄 주세요"
A->>P: 모델 호출 요청
P->>M: 추론 (도구 스키마 포함)
M-->>A: "메뉴 검색 도구를 쓰겠다"
A->>D: 메뉴 데이터 조회
D-->>A: 참치김밥 4,500원
A->>P: 도구 결과를 담아 재호출
P->>M: 추론
M-->>A: 최종 응답 결정
A-->>U: 주문서 (json)
Note over A,D: 이 왕복 전체가 AI Infrastructure 위에서 돈다핵심 메시지: “에이전트는 모델이 아니라 이 스택 전체를 조립한 시스템입니다.” 모델은 한 층일 뿐이고, 우리가 배우는 것은 나머지 층을 조립하는 기술입니다.
3-3. 과정 스택 오버레이: 이 그림을 오픈소스로 짓습니다
같은 그림에 14주 동안 쓸 스택을 대응시킵니다.
flowchart TB
subgraph ours["우리 과정의 스택"]
direction TB
O1["Agents = LangGraph + 하네스<br/>← 우리가 직접 만드는 층"]
O2["AI Platform = LiteLLM<br/>← 매니지드 플랫폼을 오픈소스 추상화로 대체"]
O3["Models = Gemini / Claude / GPT / Ollama<br/>← 문자열 교체로 넘나듦"]
O4["Data = pandas → 청킹 → sentence-transformers → Chroma"]
O5["AI Infrastructure = Docker + Render/Railway<br/>← GPU 없음은 결함이 아니라 이 층의 의도된 선택"]
O1 --> O2 --> O3 --> O4 --> O5
end레이어별 부연:
- Agents가 본체입니다. 이 과정의 차별점은 이 층을 직접 설계·구현한다는 것입니다. 나머지 층은 오픈소스 부품을 고르고 조립합니다.
- LiteLLM이 Platform 역할: Vertex 같은 매니지드 플랫폼이 해주는 “여러 모델을 한 인터페이스로”를 오픈소스 라이브러리 하나로 얻습니다.
- Models는 갈아끼우는 소모품: 특정 모델에 종속되지 않는 것이 설계 원칙입니다 (프로바이더 독립)
- GPU 없음의 의미: 추론은 API로, 임베딩은 CPU로. Infrastructure 층에서 “빌리는 것”과 “직접 드는 것”을 구분하는 판단 자체가 엔지니어링입니다.
3-4. 주차별 좌표 예고
이 그림이 9주의 지도가 됩니다.
| 주차 | 채우는 칸 |
|---|---|
| 2주 | Infrastructure (devcontainer, 개발 환경) |
| 3주 | Platform + Models (LiteLLM, 프롬프트) |
| 4주 | Data (수집·정제 → 임베딩 → RAG) |
| 5~7주 | Agents (도구 → 루프·하네스 → 트랙별 패턴) |
| 8~9주 | Infrastructure 위쪽 (API·UI 서비스화) |
| 10~14주 | 전 층을 내 프로젝트로 |
4. 엔지니어링 사다리
전주기 조망이 수직 스택(구성 요소의 축)이라면, 사다리는 신뢰성의 축입니다. 두 축은 직교합니다. 같은 스택 위에서, 얼마나 신뢰성 있게 만드느냐의 단계가 사다리입니다. 1주차에서는 깊이가 아니라 “왜 이 순서로 배우는가”의 지도로 다룹니다. 별도 시연은 없고, 사다리의 실물은 바로 다음 라이브 빌드에서 확인합니다.
4-1. 3단 개념
flowchart BT
R1["1단 — 프롬프트 엔지니어링<br/>모델에 줄 지시를 설계한다<br/>'무엇을 시킬 것인가'"]
R2["2단 — 컨텍스트 엔지니어링<br/>모델이 무엇을 언제 보는가를 설계한다<br/>retrieval · 메모리 · 컨텍스트 조립"]
R3["3단 — 하네스 엔지니어링<br/>그걸 돌리는 기계 전체를 설계한다<br/>제어 루프 · 도구 · 가드레일 · 검증"]
R1 --> R2 --> R3- 1단만 있으면: 말은 잘 듣지만 아는 게 없는 모델입니다. 지어내기 시작합니다.
- 2단이 더해지면: 맞는 재료를 보고 답합니다. 그러나 매번 사람이 차려줘야 합니다.
- 3단이 더해지면: 스스로 재료를 찾고, 검증하고, 실패를 복구합니다. 이제 “시스템”입니다.
한 문장 요약: 프롬프트는 지시, 컨텍스트는 재료, 하네스는 기계.
4-2. 커리큘럼 매핑: 사다리가 곧 14주의 순서
flowchart LR
subgraph ladder["사다리"]
direction TB
P["프롬프트"]
C["컨텍스트"]
H["하네스"]
end
subgraph weeks["주차"]
direction TB
WP["3주차"]
WC["4~5주차"]
WH["6주차~프로젝트"]
end
P --> WP
C --> WC
H --> WH마무리 메시지: “이 과정은 모델을 만드는 법이 아니라, 모델 위에 이 사다리를 쌓는 법을 배웁니다.”
5. 라이브 빌드: 분식집 주문 에이전트
5-1. 무엇을 보여주는가
가상 분식집 “분식왕”의 주문 접수 AI 점원을, Claude Code에 지시 프롬프트를 주어 그 자리에서 완성합니다. 손 코딩 시연이 아닙니다. 보여주는 것은 코드 타이핑이 아니라 지시 → 생성 → 검증 → 수정의 사이클입니다.
flowchart LR
S1["지시<br/>요구사항을 프롬프트로 설계"] --> S2["생성<br/>Claude Code가 구현"]
S2 --> S3["검증<br/>실행하고 결과를 확인"]
S3 --> S4{"통과?"}
S4 -- 아니오 --> S5["수정 지시<br/>무엇이 어긋났는지 짚어줌"]
S5 --> S2
S4 -- 예 --> S6["출하<br/>v1.0 태그"]이 사이클이 콘텐츠의 본체입니다. 여기서 사람의 일은 요구사항 설계(지시)와 검증(판단) 두 가지이고, 이는 평가 기준의 “직접 판단한 부분과 AI 도구가 보조한 부분을 구분하여 설명” 원칙을 1주차부터 멘토가 시연으로 모델링하는 것이기도 합니다.
5-2. 예제 선정 이유
- 도메인 설명이 0초: 전 국민이 아는 분식집 주문
- 데이터가 레포에 그대로 들어갑니다. 외부 API·크롤링 불필요, Gemini 키 하나로 끝
- 에이전트다움이 잘 보입니다. 주문 하나가 메뉴 조회 → 재고 체크 → 합계 계산으로 풀리며, 모델이 도구를 골라 쓰는 루프가 시각적으로 드러납니다.
- 결과가 구조화 출력(주문서 json): “LLM이 채팅이 아니라 시스템 부품이 된다”는 메시지가 1주차에 박힙니다.
- 결과 검증이 쉽습니다. 합계 금액이 맞는지 누구나 암산으로 확인할 수 있습니다.
- 실패 케이스가 재밌습니다. “돈까스 되나요?”(메뉴에 없음), “김밥 100줄”(재고 부족)로 가드레일·검증을 자연스럽게 예고합니다.
5-3. 완성 시스템의 구조 (v1.0 목표)
flowchart TB
U(["손님"]) --> WEB
subgraph app["week01-order-agent"]
WEB["web/<br/>웹 주문 화면 (채팅형 UI)"]
WEB -->|"POST /order<br/>'참치김밥 두 줄이랑 라면 하나'"| API
API["FastAPI<br/>/order 엔드포인트"]
AG["agent/<br/>에이전트 루프<br/>(도구 호출 여부를 모델이 결정)"]
LLM["llm/<br/>LiteLLM 래퍼<br/>(MODEL 환경변수로 교체)"]
subgraph tools["tools/"]
T1["메뉴 검색"]
T2["재고 확인"]
T3["주문서 생성"]
end
subgraph data["data/"]
D1[("menu.json")]
D2[("stock.json")]
end
API --> AG
AG <--> LLM
AG --> T1 & T2 & T3
T1 --> D1
T2 --> D2
end
LLM <-->|"litellm.completion()"| G["Gemini API<br/>(Google AI Studio)"]
API -->|"주문서 json"| WEB이 그림을 전주기 조망과 연결하면:
- FastAPI + Docker(추후) = Infrastructure
- agent/ = Agents 층 (오늘 만드는 것의 핵심)
- llm/ (LiteLLM) = Platform 층
- Gemini = Models 층
- data/ + tools/ = Data 층
오늘 시연 안에 5레이어가 전부 등장합니다. 이것이 전주기 조망 직후에 시연을 배치한 이유입니다.
5-4. 에이전트 루프의 동작
이 흐름을 코드와 대조하며 읽어 보세요. 사다리 3단, 하네스의 씨앗입니다.
sequenceDiagram
participant API as FastAPI /order
participant AG as 에이전트 루프
participant M as 모델 (via LiteLLM)
participant T as 도구
API->>AG: "참치김밥 두 줄이랑 라면 하나, 라면은 치즈 추가"
loop 모델이 "이제 답하겠다"고 할 때까지
AG->>M: 대화 이력 + 도구 스키마
M-->>AG: 도구 호출 결정 (예: 메뉴 검색 "참치김밥")
AG->>T: 도구 실행
T-->>AG: 결과 (참치김밥 4,500원, 옵션 정보)
Note over AG: 결과를 대화 이력에 추가하고 재호출
end
M-->>AG: 최종 응답 (주문서)
AG-->>API: 주문서 json (항목·옵션·합계)여기서 두 가지를 짚어 둡니다.
- 도구를 부를지, 몇 번 부를지, 언제 멈출지를 코드가 아니라 모델이 결정합니다. 이것이 에이전트와 일반 API 호출의 차이입니다.
- 이 while 루프가 하네스의 씨앗입니다. 지금은 루프뿐이지만, 여기에 가드레일·검증·메모리가 붙으면 하네스 엔지니어링이 됩니다.
5-5. 저장소 설계: v0.1에서 v1.0으로
저장소: week01-order-agent는 조직 소유이고, template repository로 지정되어 있습니다. 시연 시작점은 v0.1 태그로 발행되어 있습니다.
매주 시연은 2026-ai-service-engineering-a 조직 아래 독립 레포로 만들고,
조직 프로필 README에 주차별 레포 인덱스 표를 유지합니다.
gitGraph
commit id: "v0.1 템플릿" tag: "v0.1"
commit id: "라이브: 에이전트 구현"
commit id: "라이브: 수정 반영"
commit id: "PROMPT.md 확정" tag: "v1.0"
commit id: "README 영상 링크 (세션 후)"v0.1: 시연 시작점 (사전 준비)
week01-order-agent (v0.1)
├── app/
│ └── main.py # FastAPI 목 — /order가 고정 문자열 반환
├── web/
│ └── index.html # 웹 주문 화면 (채팅형 UI, /order 호출)
├── data/
│ ├── menu.json # 메뉴 22개 (이름·가격·옵션)
│ └── stock.json # 재고 수량
├── .env.example # GEMINI_API_KEY, MODEL
├── pyproject.toml # litellm, fastapi 등 의존성 선언 완료 (uv)
├── Dockerfile
├── compose.yml # 기본 실행
├── compose.dev.yml # 개발 모드 — 소스 마운트 + 자동 리로드
├── PROMPT.md # 자리만 (빈 파일)
└── README.md # 프로젝트 목표, 실행 방법
- 목 응답 예:
{"message": "죄송합니다, 아직 점원이 없어요"}(실행은 되지만 “거짓말하는 API”) - 의존성이 미리 선언되어 있으므로 시연 중 설치 대기 시간이 없습니다.
- 웹 주문 화면에는 예시 버튼 3종(정상 주문 · 메뉴에 없는 항목 · 재고 초과)이 준비되어 있어, 리뷰 단계의 검증 케이스를 바로 누를 수 있습니다.
v1.0: 시연 종료점
week01-order-agent (v1.0)
├── app/
│ └── main.py # /order가 에이전트 루프 호출
├── agent/ # 에이전트 루프 ← Claude Code 구현
├── llm/ # LiteLLM 래퍼 ← Claude Code 구현
├── tools/ # 도구 3종 ← Claude Code 구현
├── web/ # (v0.1 그대로)
├── data/ # (v0.1 그대로)
├── PROMPT.md # 시연에서 사용한 지시 프롬프트 원문
└── README.md # 실행 방법 갱신 + 영상 링크 (세션 후)
Dockerfile·compose 파일은 v0.1 그대로 유지됩니다.
수강생 여정
flowchart LR
T["template: v0.1"] -->|"Use this template"| MY["내 레포"]
V["영상"] --> RE["재현 시도"]
PM["PROMPT.md"] --> RE
MY --> RE
RE -->|막히면| DIFF["v1.0과 diff"]
DIFF --> RE
RE --> DONE["동작 확인<br/>= 2주차 환경 구축 검증 과제"]- 시작·끝이 태그로 고정되어 있으므로, 영상 없이 코드만 보더라도
git diff v0.1 v1.0하나로 “시연에서 무엇이 만들어졌나”를 정확히 볼 수 있습니다. - 재현 시점은 2주차 환경 구축 이후입니다. 2주차 산출물 “동작하는 개발 환경”의 검증 과제로 연결됩니다.
5-6. 기술 원칙 (시연 코드에 반영)
- 모든 LLM 호출은 LiteLLM 경유. 프로바이더 SDK 직접 호출 금지
- 프로바이더는 Gemini (Google AI Studio 무료 티어)
- 모델 문자열은 환경변수
MODEL로 분리. 이 문자열만 바꾸면 Claude도 로컬 모델도 됩니다. 왜 중요한지는 3주차에서 다룹니다. - 모듈 분리:
llm/tools/agent/(단일 파일 금지) - FastAPI
/order엔드포인트로 노출 - 도구 3종
- 메뉴 검색: 이름·키워드로 메뉴 조회
- 재고 확인: 주문 수량 가능 여부
- 주문서 생성: 항목·옵션·합계를 담은 json 반환
5-7. 지시 프롬프트 골격
시연에서는 이 프롬프트를 PROMPT.md에 한 줄씩 타이핑하며 의도를 설명합니다. 프롬프트 자체가 교재입니다. 요구사항을 정의하는 능력이 곧 설계 능력이기 때문입니다.
분식집 주문 접수 에이전트를 만들어줘.
- 모든 LLM 호출은 LiteLLM 경유. 프로바이더 SDK 직접 호출 금지
- 모델은 환경변수 MODEL로 교체 가능하게 (기본값은 .env.example 참조)
- 도구 3개: 메뉴 검색(data/menu.json), 재고 확인(data/stock.json), 주문서 생성
- 에이전트 루프: 모델이 도구 호출 여부를 결정하고, 필요한 만큼 반복
- 주문서는 json으로: 항목 목록(메뉴·수량·옵션·단가), 합계 금액
- 메뉴에 없는 항목이나 재고 부족은 정중히 거절하고 대안 제시
- 기존 FastAPI의 /order 엔드포인트에 연결
- 모듈 분리: llm / tools / agent
- README에 실행 방법 갱신
줄별 의도:
- “LiteLLM 경유”: 아키텍처 제약을 요구사항 문장으로 박습니다. 안 쓰면 Claude Code는 가장 흔한 방식(SDK 직접 호출)으로 갑니다.
- “환경변수 MODEL”: 프로바이더 독립을 코드 구조로 강제합니다.
- “정중히 거절하고 대안 제시”: 실패 케이스를 요구사항에 미리 넣습니다. 가드레일의 씨앗입니다.
- “모듈 분리”: 지시하지 않으면 한 파일로 나옵니다. 구조는 시키는 사람의 책임입니다.
5-8. 시연 진행
0. 시연 환경 띄우기
시연은 개발 모드 컨테이너를 띄워 둔 채 진행합니다. 소스가 마운트되어
있어, 라이브 중 Claude Code가 생성하는 agent/·llm/·tools/가 재빌드 없이
바로 서버에 반영됩니다.
git clone https://github.com/2026-ai-service-engineering-a/week01-order-agent
cd week01-order-agent
cp .env.example .env # GEMINI_API_KEY 채우기 (v0.1 목은 키 없이도 동작)
docker compose -f compose.dev.yml up --build
1. v0.1 투어
-
웹 주문 화면(
http://localhost:8000)에 접속해 예시 버튼으로 주문 → 고정 응답 확인 -
curl로도 같은 것을 확인합니다:
curl -s -X POST http://localhost:8000/order \ -H "Content-Type: application/json" \ -d '{"message": "참치김밥 두 줄이랑 라면 하나, 라면은 치즈 추가"}' -
폴더 구조, menu.json·stock.json 열어서 보여주기
-
이 API는 지금 거짓말을 합니다. 세션에서는 이 자리에서 진짜로 만듭니다.
2. 지시 프롬프트 작성
- PROMPT.md에 직접 타이핑하며 각 줄의 의도 설명 (5-7 포인트)
3. Claude Code 실행 + 생성 관찰
- 만들어지는 파일을 따라가며 앞의 두 지도와 연결합니다.
- 지금 생긴 이 while 루프가 하네스 층입니다 (사다리 연결)
- 이
litellm.completion한 줄이 앞 그림의 Platform 레이어입니다 (전주기 연결)
- 개발 모드 컨테이너가 떠 있으므로 파일이 저장되는 즉시 서버에 반영됩니다 (별도 재시작 없음)
4. 리뷰 + 실행 + 수정 사이클
- 정상 케이스: 웹 화면에서 “참치김밥 두 줄이랑 라면 하나, 라면은 치즈 추가” → 주문서 json 확인, 합계 암산으로 검증
- 실패 케이스: “돈까스 되나요?”, “김밥 100줄” → 거절·대안 제시 확인 (예시 버튼으로 바로 재현 가능)
- 구현이 어긋나면 수정을 지시합니다. 검증하고 고치게 하는 모습 자체가 콘텐츠입니다.
- 리뷰 중 모델 문자열 환경변수를 짚고 프로바이더 독립을 예고합니다.
5. 마무리
- v1.0 태그 푸시
- 공개 자산 3종 안내: 코드 + PROMPT.md + 영상
- 남는 것은 코드가 아니라 사이클입니다. 지시하고, 검증하고, 고칩니다. 14주 동안 배우는 것은 이 사이클을 출하 가능한 품질로 돌리는 법입니다.
5-9. 재현할 때 유의할 점
LLM 코딩은 비결정적입니다. 같은 프롬프트를 같은 모델에 줘도 생성 결과가 매번 조금씩 다릅니다.
- 영상과 다른 결과가 나오는 것이 정상입니다. 파일 이름이나 함수 분해가 달라도 요구사항을 만족하면 성공입니다.
git diff v0.1 v1.0은 정답이 아니라 참고 구현입니다. - 에러나 어긋난 구현도 과정의 일부입니다. 무엇이 어긋났는지 짚어 수정을 지시하는 것이 이 시연의 본체이므로, 한 번에 안 나온다고 잘못된 것이 아닙니다.
- Gemini 무료 티어에는 rate limit이 있습니다. 연달아 재시도하다 막히면 잠시 기다렸다 다시 부르거나, 보조 키를 준비합니다.
6. 코드 구조 분석
시연 전후로 코드를 직접 읽을 때의 가이드입니다. 세 개의 태그가 발행되어 있습니다. 시작점 v0.1, 지시 프롬프트(PROMPT.md)를 실행해 완성한 참고 구현 v0.2, 그리고 메모리와 가드레일이 붙은 v1.0입니다. 태그 사이를 diff 하면 각 단계에서 무엇이 생겼는지가 그대로 보입니다.
git diff v0.1 v0.2 --stat # 에이전트가 붙으며 생긴 것
git diff v0.2 v1.0 --stat # 메모리·가드레일이 붙으며 생긴 것
6-1. v0.1 분석: 거짓말하는 API
flowchart TB
U(["손님"]) --> WEB["web/index.html<br/>채팅형 주문 화면"]
WEB -->|"POST /order<br/>(한 건씩 · 세션 없음)"| API["app/main.py — FastAPI<br/>/order · /settings"]
API -->|"고정 응답<br/>'죄송합니다, 아직 점원이 없어요'"| WEB
API <-.->|"⚙️ 설정 저장"| ENV[(".env<br/>GEMINI_API_KEY · MODEL")]
subgraph ghost["라이브에서 생성될 자리 — 아직 없음"]
AG["agent/"]
LL["llm/"]
TO["tools/"]
end
TO -.-> D1[("data/menu.json")]
TO -.-> D2[("data/stock.json")]
style ghost stroke-dasharray: 5 5
style AG stroke-dasharray: 5 5
style LL stroke-dasharray: 5 5
style TO stroke-dasharray: 5 5app/main.py: FastAPI 앱 하나가 전부입니다./order는 고정 문자열을 돌려주고,/settings(GET/PUT)는 웹 화면의 ⚙️ 설정을.env에 기록합니다. 웹 정적 파일은 API 라우트보다 뒤에 마운트해/order가 가려지지 않게 합니다.web/index.html: 채팅형 주문 화면. 입력 한 건마다{"message": …}하나를/order로 POST합니다. 서버에 세션·대화 이력이 없다는 점을 기억해 두세요. (6-2의 한계와 이어집니다)data/menu.json·stock.json: 도구가 읽을 재료. 메뉴 22개(이름·가격·옵션)와 재고 수량입니다.pyproject.toml·uv.lock: litellm·fastapi가 미리 선언되어 있어 시연 중 설치 대기가 없습니다.- 없는 것:
agent/·llm/·tools/. 라이브 빌드에서 생성될 자리입니다.
6-2. v0.2 분석: 에이전트가 붙은 구조
지시 프롬프트의 요구사항이 코드 구조로 어떻게 번역됐는지 보세요.
flowchart TB
WEB["web/<br/>주문 화면"] -->|"POST /order"| API["app/main.py"]
API --> RUN["agent/loop.py — run_agent<br/>MAX_TURNS = 8"]
RUN -->|"complete(messages, tools)"| LLM["llm/client.py<br/>LiteLLM 래퍼 · MODEL은 호출 시점에 로드"]
LLM <--> G["Gemini API"]
RUN -->|"execute(name, args)"| REG["tools/__init__.py<br/>스키마 + 구현 레지스트리<br/>실패 시 {error} 반환"]
REG --> M["search_menu"]
REG --> S["check_stock"]
REG --> O["create_order<br/>단가·합계는 코드가 계산"]
M --> D1[("menu.json")]
S --> D2[("stock.json")]
O --> D1
O --> D2
RUN -->|"주문서 json"| API
API --> WEBllm/client.py: LiteLLM 래퍼.complete(messages, tools)함수 하나뿐이고, 모델명은 호출 시점에 환경변수MODEL에서 읽습니다. 웹 ⚙️ 설정으로 바꾼 값이 재시작 없이 적용되는 이유입니다.tools/: 도구마다 스키마(OpenAI function 형식) + 순수 파이썬 구현의 쌍입니다.execute()레지스트리는 도구가 실패해도 예외 대신{"error": …}를 돌려줍니다. 에러를 모델에게 보여 주고 스스로 고치게 하는 패턴입니다.tools/order.py: 단가·합계는 모델이 아니라 코드가 메뉴판 기준으로 계산합니다. LLM은 항목을 고르고, 돈 계산은 결정적인 코드가 맡습니다. 주문서 json이라는 구조화 출력과 함께 “LLM은 채팅이 아니라 시스템 부품”이라는 원칙의 실물입니다.agent/loop.py: 시스템 프롬프트(메뉴를 지어내지 말 것, 주문 전 재고 확인 등)와 에이전트 루프.MAX_TURNS = 8상한으로 무한 루프를 막습니다. 루프·상한·역할 분리, 이것이 하네스의 씨앗입니다.
한계: 대화가 이어지지 않습니다. run_agent는 매 요청마다 시스템
프롬프트와 이번 메시지 하나로 새 대화를 시작합니다.
def run_agent(user_message: str) -> dict:
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message}, # 매 요청 새 대화 — 이전 기억 없음
]
for _ in range(MAX_TURNS):
response = complete(messages, tools=TOOL_SCHEMAS)
...
flowchart TB
subgraph req1["요청 1 — 새 대화"]
direction LR
U1["'참치김밥 두 줄 주세요'"] --> A1["에이전트 루프"] --> O1["주문서 ✓"]
end
subgraph req2["요청 2 — 또 새 대화 (요청 1을 모름)"]
direction LR
U2["'치즈도 추가해 주세요'"] --> A2["에이전트 루프"] --> O2["무엇에 추가…?"]
end
req1 ~~~ req2- 루프 안의 대화 이력은 한 요청 안의 도구 왕복용일 뿐입니다.
- 웹 화면이 채팅처럼 보여도 서버는 이전 주문을 기억하지 못합니다. 주문은 한 문장에 다 담아야 합니다.
- 결함이 아니라 의도된 중간 단계입니다. 이 한계가 바로 다음 버전에서 어떻게 해소되는지 6-3에서 봅니다.
6-3. v1.0 분석: 메모리와 가드레일이 붙은 구조
v0.2의 한계가 하나씩 기능이 됩니다. 사다리로 말하면: 세션 메모리는 2단 컨텍스트 엔지니어링의 첫걸음, 가드레일은 3단 하네스 엔지니어링의 첫걸음입니다.
flowchart TB
WEB["web/ 주문 화면<br/>session_id 왕복 · 메뉴판 표 렌더링"] -->|"POST /order<br/>(message + session_id)"| API["app/main.py"]
API <--> SES["agent/session.py — 세션 메모리<br/>TTL 30분 · 이력 상한 30개 · Lock"]
API --> RUN["agent/loop.py — run_agent(message, history)<br/>MAX_TURNS = 8 · 가드레일 2종"]
RUN <--> LLM["llm/client.py"]
LLM <--> G["Gemini API"]
RUN --> REG["tools/"]
REG --> ST["check_stock · create_order<br/>주문 확정 시 재고 차감"]
ST --> SEED[("data/stock.json<br/>시드 · 읽기 전용 · 커밋됨")]
ST --> STATE[("data/stock.state.json<br/>런타임 상태 · gitignore")]agent/session.py: 대화가 이어집니다. 서버가 손님별 이력(user/assistant만)을 보관하고, 응답에session_id를 실어 보내면 웹이 다음 요청에 되돌려 줍니다. 도구 왕복은 여전히 요청 안에서 쓰고 버립니다.- 인메모리 dict이지만 그냥 dict가 아닙니다. TTL 30분(만료), 이력 상한 30개(토큰 폭주 방지), threading.Lock(동시 요청)이 붙는 순간 “관리해야 할 상태”가 됩니다. 영속화·분산은 이후 주차 주제입니다.
agent/loop.py의 가드레일 2종: 결정적으로 처리할 수 있는 UX를 확률적 컴포넌트에만 맡기지 않습니다.- 메뉴판 가드레일: “메뉴판 보여주세요”인데 모델이 도구를 건너뛰어도, 키워드 판별로 메뉴판 표는 반드시 뜹니다.
- 빈 응답 가드레일: 보여줄 것도 없는데 빈 답이 오면 한 번 재지시합니다.
tools/stock.py: 주문 확정 시 재고를 실제로 차감합니다. 커밋된stock.json은 읽기 전용 시드로 두고, 차감된 상태는 gitignore된stock.state.json에 기록합니다. 시연을 반복해도 저장소가 더러워지지 않고, 상태 파일을 지우면 초기화됩니다. 읽기-수정-쓰기는 Lock으로 보호합니다.
보안 관점: 인젝션은 어디까지 막히나. “다른 질문을 하면 점원이 거절한다”가 지금 왜 되는지, 그리고 어디까지 믿을 수 있는지 구분해 둡니다.
flowchart TB
IN["손님 메시지<br/>(유일한 입력 채널 — 외부 문서·웹을 읽지 않음)"] --> L1["1차 — 역할 고정 시스템 프롬프트<br/>'분식왕 점원' · 확률적 방어, 뚫릴 수 있음"]
L1 --> L2["2차 — 좁은 행동 반경<br/>도구 3개뿐 · 파일·네트워크·코드 실행 없음"]
L2 --> L3["3차 — 결정적 코드 경계<br/>가격·합계·재고는 서버 코드가 계산"]- 1차 (확률적): 오프토픽 질문이 거절되는 건 역할 고정 시스템 프롬프트와 모델의 시스템 지시 우선 정렬 덕입니다. “주문 외 질문 거절” 규칙을 명시하지 않았는데도 모델이 점원 역할에서 추론합니다. 다만 이것은 부드러운 방어라서, 집요한 역할 탈취나 “이전 지시는 무시해” 류에 항상 버틴다는 보장은 없습니다.
- 2차 (구조적): 말로 뚫려도 행동이 좁습니다. 인젝션이 성공해 봐야 실행할 수 있는 건 메뉴 조회·재고 확인·주문서 생성뿐입니다.
- 3차 (결정적): “참치김밥 0원으로 해줘”는 통하지 않습니다. 단가·합계·재고는 모델의 출력이 아니라 서버 코드가 메뉴판 기준으로 계산하기 때문입니다.
- 요약: 말은 뚫릴 수 있어도, 피해가 나는 경로는 전부 결정적 코드 뒤에 있습니다. 출력 검증·본격 가드레일은 하네스 엔지니어링의 주제입니다. 4주차에 RAG가 붙으면 “문서에 심어 둔 지시”라는 새 인젝션 표면이 생기고, 6주차 하네스에서 그 간접 인젝션을 재현해 막습니다.
7. 프로젝트 트랙 소개
방금 만든 주문 에이전트를 좌표로 사용합니다. 5개 트랙은 결국 같은 구조에서 무엇을 갈아끼우는가의 차이입니다.
flowchart TB
subgraph core["오늘 본 구조 (불변)"]
A["에이전트 루프 + LiteLLM + FastAPI"]
end
subgraph swap["갈아끼우는 것 (트랙)"]
R["문서 기반 RAG<br/>메뉴판 → 문서<br/>주문 → 질의응답"]
AU["업무 자동화<br/>주문서 생성 → 보고서·요약 생성"]
DA["데이터 분석<br/>재고 조회 → 데이터 질의"]
RC["추천/분류<br/>메뉴 검색 → 매칭·분류"]
DT["개발자 도구<br/>메뉴 데이터 → GitHub API"]
end
A --> R & AU & DA & RC & DT| 트랙 | 갈아끼우는 것 | 예시 프로젝트 | 주요 스택 |
|---|---|---|---|
| 문서 기반 RAG | 메뉴판 → 문서, 주문 → 질의응답 | 정책/기술문서 Q&A, FAQ 챗봇 | LlamaIndex, Chroma, Qdrant |
| 업무 자동화 | 주문서 생성 → 보고서·요약 생성 | 회의록 요약, 이슈 분류 | LangGraph, n8n |
| 데이터 분석 | 재고 조회 → 데이터 질의 | CSV 자연어 질의, 리포트 생성 | pandas, DuckDB, Plotly |
| 추천/분류 | 메뉴 검색 → 매칭·분류 | 채용공고 매칭, 문의 분류 | scikit-learn, sentence-transformers |
| 개발자 도구 | 메뉴 데이터 → GitHub API | 코드리뷰 보조, 이슈 요약 | GitHub API, FastAPI |
- 트랙은 7주차 트랙별 실습에서 가결정하고, 10주차 기획에서 확정합니다. 지금은 “내 관심이 어느 쪽인지” 가늠만 하면 됩니다.
- 주차별 템플릿은 개인 프로젝트의 부품으로 재사용할 수 있습니다 (별도 진행도 가능, 템플릿은 출발점)
- 1주차부터 깔리는 프로젝트 계획 백그라운드 과제와 이어집니다. 매주 시연을 보며 “내 프로젝트라면 무엇을 갈아끼울까”를 생각해 보세요.
8. 개인 repo 개설 실습
세션 중 유일하게 수강생이 직접 손을 움직이는 구간입니다.
- GitHub 계정 준비 (기존 계정 활용 권장, 없으면 생성)
- 개인 실습·프로젝트용 public 레포 생성: 개인 계정에 생성을 권장합니다 (포트폴리오로 가져가는 것이므로. 조직 내 생성도 무방)
- README에 개인 학습 목표 3줄 작성: 산출물 “학습 목표 + 개인 repo”를 한 파일로 합칩니다.
- 예시 프레임: 현재 상태 / 14주 뒤 만들고 싶은 것 / 관심 트랙 후보
- Discord로 요청 시 멘토가 계정 문제·레포 설정을 지원합니다.
환경 미비(devcontainer 미설치 등) 상태로 참석해도 1주차 참여에 지장이 없습니다. 환경 구축은 2주차 주제입니다.
9. 마무리
- 2주차 예고: Python AI 개발환경 (devcontainer, uv/pip, GitHub 워크플로)
- 과제 안내
- 개인 repo 미완성 시 완성 (README 학습 목표 포함)
- 오늘 시연 재현은 지금 의무가 아닙니다. 2주차 환경 구축 후 확인 과제로 연결됩니다.
- 공개 자산 위치 안내:
2026-ai-service-engineering-a조직 + 영상 링크 - 디스코드 채널 안내: 질문·재현 막힘·프로젝트 구상 논의는 세션 사이에도 상시
- 강의 요일·오프라인 모임 일정 의견 수렴 결과 안내 (또는 디스코드 투표로 이관)