AI 서비스 엔지니어링: Track A
1주차 · AI 서비스 전주기 이해와 첫 에이전트
CodeCompose · 2026-07-24
이 자료, 내 컴퓨터에서 볼 수 있습니다
클론해서 띄우고, 새 자료는 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, 처음이라면” 참고
14주 구조
1~9주 공통 역량 → 10~14주 개인 프로젝트
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매주 템플릿 실습이 제공됩니다. 부품으로 재조립해도, 별개로 진행해도 됩니다. 템플릿은 출발점이지 제약이 아닙니다
운영 방식
라이브 세션 = 만드는 과정과 판단을 보는 시간
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/>(각자 속도로)"]라이브 세션 = 멘토 시연 + 코칭, 코드 따라 쓰기 없음
개인 프로젝트는 1주차부터 시작됩니다
백그라운드 과제: “무엇을 만들지” 계속 생각하기
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매주 시연을 보며 “내 프로젝트라면 이 부품을 어떻게 쓸까”. 트랙 가결정(7주차) → 기획 확정(10주차)은 체크포인트일 뿐, 두 레인은 10주차에 자리를 바꿉니다
AI 서비스 스택: 5레이어
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
end요청 하나가 스택을 타고 내려갑니다
”참치김밥 두 줄 주세요” 한 문장의 여정
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 위에서 돈다우리 과정의 스택
같은 그림을 오픈소스로 짓습니다
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완성 시스템의 구조 (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에이전트 루프
도구를 부를지, 몇 번 부를지, 언제 멈출지: 코드가 아니라 모델이 결정합니다
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 (항목·옵션·합계)이 while 루프가 하네스의 씨앗: 가드레일·검증·메모리가 붙으면 하네스 엔지니어링
v0.1에서 v1.0으로
- v0.1 (시작점): FastAPI 목 + 웹 주문 화면 + 메뉴·재고 데이터
{"message": "죄송합니다, 아직 점원이 없어요"}(거짓말하는 API) - 라이브: Claude Code가 agent/ · llm/ · tools/ 구현 → 리뷰·실행·수정
- v1.0 (완성): 동작하는 주문 에이전트 + PROMPT.md 원문
git diff v0.1 v1.0하나로 시연 전체를 볼 수 있습니다
시연 저장소: week01-order-agent (template repository)
저장소 구조 (v1.0)
화살표 부분이 라이브에서 생성됩니다 (나머지는 v0.1 그대로)
week01-order-agent
├── app/
│ └── main.py # /order가 에이전트 루프 호출
├── agent/ # 에이전트 루프 ← Claude Code 구현
├── llm/ # LiteLLM 래퍼 ← Claude Code 구현
├── tools/ # 도구 3종 ← Claude Code 구현
├── web/
│ └── index.html # 웹 주문 화면 (채팅형 UI)
├── data/
│ ├── menu.json # 메뉴 22개 (이름·가격·옵션)
│ └── stock.json # 재고 수량
├── Dockerfile · compose.yml · compose.dev.yml
├── PROMPT.md # 시연에서 사용한 지시 프롬프트 원문
└── README.md # 실행 방법 + 영상 링크 지시 프롬프트
이 프롬프트 자체가 교재: 요구사항을 정의하는 능력이 곧 설계 능력
분식집 주문 접수 에이전트를 만들어줘.
- 모든 LLM 호출은 LiteLLM 경유. 프로바이더 SDK 직접 호출 금지
- 모델은 환경변수 MODEL로 교체 가능하게
- 도구 3개: 메뉴 검색, 재고 확인, 주문서 생성
- 에이전트 루프: 모델이 도구 호출 여부를 결정하고, 필요한 만큼 반복
- 주문서는 json으로: 항목 목록(메뉴·수량·옵션·단가), 합계 금액
- 메뉴에 없는 항목이나 재고 부족은 정중히 거절하고 대안 제시
- 기존 FastAPI의 /order 엔드포인트에 연결
- 모듈 분리: llm / tools / agent 시연 진행
- 환경 띄우기:
docker compose -f compose.dev.yml up --build소스가 마운트되어 있어 생성되는 파일이 즉시 서버에 반영됩니다 - v0.1 투어: 웹 화면(localhost:8000)에서 주문 → “지금 이 API는 거짓말을 합니다”
- 지시 프롬프트 작성: 줄마다 의도를 설명하며 타이핑
- Claude Code 실행 + 생성 관찰: while 루프(하네스층), litellm.completion(Platform층) 내레이션
- 리뷰 + 실행 + 수정: 정상 주문은 합계 암산으로, “돈까스 되나요?”는 거절·대안으로 검증
- 마무리: v1.0 태그 푸시, 공개 자산 3종 안내
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")]
subgraph ghost["라이브에서 생성될 자리 — 아직 없음"]
AG["agent/"]
LL["llm/"]
TO["tools/"]
end
TO -.-> D1[("menu.json")]
TO -.-> D2[("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 5의존성은 미리 선언해 둡니다. 데이터는 준비됐지만 아직 아무도 읽지 않습니다
v0.2 읽기: 에이전트가 붙은 구조
요구사항이 코드 구조로 어떻게 번역됐는가
llm/client.py:complete()하나 · MODEL은 호출 시점에 읽음 (재시작 없이 교체)tools/: 도구마다 스키마 + 순수 구현 쌍 · 실패는 예외 대신{"error"}반환 → 에러를 모델에게 보여 주고 스스로 고치게tools/order.py: 단가·합계는 코드가 계산 · LLM은 항목만 고름agent/loop.py: 시스템 프롬프트(지어내기 금지) +MAX_TURNS = 8상한
루프 · 상한 · 역할 분리: 하네스의 씨앗
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 래퍼"]
LLM <--> G["Gemini API"]
RUN -->|"execute(name, args)"| REG["tools/<br/>스키마 + 구현 레지스트리"]
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 --> WEBv0.2의 한계: 대화가 이어지지 않습니다
def run_agent(user_message: str) -> dict:
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_message}, # 매 요청 새 대화
]- 루프 안의 대화 이력은 한 요청 안의 도구 왕복용일 뿐
- “참치김밥 두 줄” → “치즈도 추가해 주세요”: 무엇에 추가하는지 모릅니다
- 주문은 한 문장에 다 담아야 합니다
- 결함이 아니라 의도된 범위: 대화 메모리는 컨텍스트 엔지니어링(사다리 2단), 이후 주차의 주제
v1.0 읽기: 한계가 기능이 됩니다
세션 메모리 = 컨텍스트(2단)의 첫걸음 · 가드레일 = 하네스(3단)의 첫걸음
agent/session.py: 대화가 이어집니다 · session_id 왕복 TTL 30분 · 이력 상한 30개 · Lock: “그냥 dict”가 아니라 관리해야 할 상태- 가드레일 2종: 결정적으로 처리할 수 있는 UX를 확률에 맡기지 않음 메뉴판 요청이면 모델이 도구를 건너뛰어도 메뉴판 표가 뜸 · 빈 응답이면 재지시
tools/stock.py: 주문 확정 시 재고 차감 시드(stock.json, 커밋)와 런타임 상태(stock.state.json, gitignore) 분리
v1.0 모듈 구조
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[("stock.json<br/>시드 · 읽기 전용")]
ST --> STATE[("stock.state.json<br/>런타임 · gitignore")]인젝션은 어디까지 막히나
말은 뚫릴 수 있어도, 피해가 나는 경로는 전부 결정적 코드 뒤
flowchart TB
IN["손님 메시지<br/>(유일한 입력 채널)"] --> L1["1차 — 역할 고정 프롬프트<br/>확률적 방어 · 뚫릴 수 있음"]
L1 --> L2["2차 — 좁은 행동 반경<br/>도구 3개뿐 · 파일·네트워크·코드 실행 없음"]
L2 --> L3["3차 — 결정적 코드 경계<br/>가격·합계·재고는 서버가 계산"]“참치김밥 0원으로 해줘”가 통하지 않는 이유입니다. 본격 가드레일·검증, 그리고 RAG와 함께 생길 새 인젝션 표면은 이후 주차에서
갈아끼우기
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