1주차: AI 서비스 전주기 이해와 첫 에이전트

1주차 라이브 세션 상세 교안: 전주기 조망, 엔지니어링 사다리, 분식집 주문 에이전트 라이브 빌드, 프로젝트 트랙, 개인 repo 개설

슬라이드 1주차: AI 서비스 전주기 이해와 첫 에이전트

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
    end

3-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 5
  • app/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 --> WEB
  • llm/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 조직 + 영상 링크
  • 디스코드 채널 안내: 질문·재현 막힘·프로젝트 구상 논의는 세션 사이에도 상시
  • 강의 요일·오프라인 모임 일정 의견 수렴 결과 안내 (또는 디스코드 투표로 이관)