AI 서비스 엔지니어링: Track A
8주차 · 서비스 경계, 두 개의 문과 자동화
CodeCompose · 2026-09-11
오늘의 그림
flowchart LR
P(("사람")) --> U["ui :8501<br/>구경용 화면"]
U -->|"HTTP"| A["api :8000<br/>FastAPI"]
P -->|"HTTP · /docs"| A
AI(("다른 AI<br/>Claude · Codex · ChatGPT")) -->|"MCP"| M["mcp :8010<br/>FastMCP"]
E(("이벤트<br/>웹훅 · 정해진 시간")) -->|"트리거"| N["n8n :5678<br/>워크플로"]
N -->|"HTTP · MCP"| A
A --> C["core/<br/>6주차 여행 플래너"]
M --> C
C -->|"모델 호출"| G["litellm-proxy :4000<br/>게이트웨이"]
G --> L(("모델 제공자"))문이 셋이고 코어는 하나입니다.
저장소 기동
- 실행
git clone https://github.com/2026-ai-service-engineering-a/week08-service-lab.git
cd week08-service-lab
cp .env.sample .env
cp gateway/.env.sample gateway/.env
docker compose up --build -d
docker compose exec api pytest- 결과
20 passed, 2 warnings in 1.28s- 화면
:8501· API 문서:8000/docs· MCP:8010· n8n:5678· 게이트웨이:4000
키가 하나도 없어도 전부 돌아갑니다
가짜인 것은 모델뿐입니다
- 실행
curl -s localhost:8000/config- 결과
{"mode":"offline","model":"offline/scripted-planner","gateway":null,
"defaults":{"max_steps":6,"max_cost_usd":0.2}}- 도구는 진짜로 실행되고, 결과는 진짜로 되먹여지고, 예산도 진짜로 쌓입니다.
- 가짜인 부분은 무엇을 부를지 정하는 판단 하나입니다.
- 3장부터 7장까지는 이 상태 그대로 갑니다. 진짜 모델이 필요한 것은 8장뿐입니다.
AI 표시는 모델로 가는 마지막 단입니다
plan도plan_events도 결국 모델까지 이어집니다.- 그 둘은
run_iter에게 시킬 뿐이라 표시가 없습니다. run_iter도 진짜 끝은 아닙니다. 한 칸만 더 갑니다.
core/llm.py
core/config.py
core/errors.py
core/offline.py
core/react.py
이 저장소에서 litellm을 실제로 부르는 자리는 completion 하나입니다. 추출기가 찾아 표시하므로 손으로 붙인 것이 아닙니다.
경계를 그었다는 증거는 import 방향에 있습니다
flowchart TB
subgraph doors["문 · 이번 주에 다는 껍데기"]
A["api/main.py"]
M["mcp_server/server.py"]
end
subgraph core["core/ · 6주차에 만든 것"]
S["service.py<br/>plan() · plan_events()"]
R["react.py · tools.py · harness.py"]
end
A -->|"import"| S
M -->|"import"| S
S --> R
core -.->|"import 하지 않는다"| doors
linkStyle 3 stroke-dasharray:5 5,opacity:0.45코어가 문을 알기 시작하면 문을 하나 더 달 때마다 코어를 고쳐야 합니다.
스키마 하나가 네 곳에서 쓰인다
| 쓰이는 곳 | 어디서 | 무엇을 하나 |
|---|---|---|
| 요청 검증 | api/schemas.py | 계약을 어긴 요청을 422로 막는다 |
| 도구 스키마 | core/tools.py | 모델에게 도구를 설명한다 |
| MCP 도구 명세 | mcp_server/server.py | 다른 AI에게 도구를 설명한다 |
| OpenAPI 문서 | /docs | 사람에게 계약을 설명한다 |
flowchart LR
P["pydantic 모델 하나<br/>BudgetArgs · PlanRequest"]
P --> A["요청 검증<br/>422로 막는다"]
P --> B["도구 스키마<br/>모델에게 설명"]
P --> C["MCP 도구 명세<br/>다른 AI에게 설명"]
P --> D["OpenAPI /docs<br/>사람에게 설명"]계약이 없으면 무슨 일이 생기는가
같은 일을 하는 엔드포인트 둘에 잘못된 요청 다섯 개
- 실행
docker compose exec api python examples/01_no_validation.py- 결과
요청 /naive (계약 없음) /checked (계약 있음)
--------------------------------------------------------------------------------
정상 200 {'length': 9, 'steps': 6 200
빈 질문 200 {'length': 0, 'steps': 6 422 string_too_short
질문 없음 200 {'length': 0, 'steps': 3 422 missing
스텝 9999 200 {'length': 3, 'steps': 9 422 less_than_equal
질문이 소설 한 권 200 {'length': 100000, 'step 422 string_too_long왼쪽은 전부 200입니다. 10만 자짜리 질문이 핸들러 안까지 들어갑니다.
번역표
flowchart LR
subgraph core["core/ · HTTP를 모른다"]
U["UpstreamError"]
T["UpstreamTimeout"]
B["예산 초과"]
end
subgraph door["api/errors.py · 번역표"]
U --> S1["502 Bad Gateway"]
T --> S2["504 Gateway Timeout"]
B --> S3["200 + stopped_by: budget"]
end
S1 --> L["요청 로그 한 줄<br/>request_id 포함"]
S2 --> L
S3 --> L5초 만에 재현합니다
랩 전용 스위치입니다. 실제 서비스에는 두지 않습니다
- 실행
curl -s -w "\nstatus=%{http_code}\n" -X POST "localhost:8000/plan?simulate=upstream" \
-H 'content-type: application/json' -d '{"question":"오사카 2박"}'- 결과
{"error":"UpstreamError","detail":"모의 상류 장애: 모델 제공자가 500을 돌려줬다",
"request_id":"0acf2c7a8dbd"}
status=502simulate=timeout이면 504가 옵니다.
그래프를 얹으면 상태가 생깁니다
# app/agent/graph.py · 그래프는 프로세스가 뜰 때 한 번만 만든다
checkpointer = PostgresSaver(pool)
checkpointer.setup()
graph = build_graph().compile(checkpointer=checkpointer)
# app/main.py · 요청마다 어느 대화인지를 끼운다
def _config(mode: str, thread_id: str) -> dict:
return {"configurable": {"thread_id": f"{mode}:{thread_id}"}}week07-support-agent의 코드가 이미 답을 갖고 있습니다.
상태는 프로세스가 아니라 DB에 삽니다
flowchart TB
subgraph proc["서버 프로세스 · 뜰 때 한 번"]
G["compile된 그래프"]
end
R1["요청 A<br/>thread_id=alice"] --> G
R2["요청 B<br/>thread_id=bob"] --> G
G <-->|"checkpointer"| DB[("PostgreSQL<br/>대화 상태")]
G -.->|"재시작해도"| DB- 뜰 때 한 번 compile한다. 요청마다 만들면 연결과 스키마 준비를 매번 다시 합니다
- 상태는 DB에 산다. 파이썬 딕셔너리에 담으면 재시작과 다중 워커에서 깨집니다
- thread_id는 요청이 가져온다. 모델이 정하게 두지 않습니다
조심할 곳 둘
async def event_source():
iterator = service.plan_events(...)
try:
# ① 동기 제너레이터를 async 안에서 그냥 돌리면 이벤트 루프가 멈춘다
async for event in iterate_in_threadpool(iterator):
yield {"event": event["event"], "data": json.dumps(event, ensure_ascii=False)}
except Exception as e:
# ② 헤더가 이미 나간 뒤에는 상태 코드로 실패를 알릴 수 없다
yield {"event": "error", "data": json.dumps({"error": type(e).__name__})} 스트림이 시작되면 상태 코드는 이미 200입니다
def test_stream_reports_failure_as_an_event_not_a_status(client):
with client.stream("POST", "/plan/stream", params={"simulate": "upstream"}, ...) as r:
assert r.status_code == 200 # 200으로 시작해 버렸다
...
assert kinds[-1] == "error"- 그 뒤에 상류가 죽어도 502로 고칠 방법이 없습니다. 실패도 이벤트로 보냅니다.
- 프록시가 스트림을 모았다가 한 번에 주는 사고도 흔합니다.
Cache-Control: no-cache와X-Accel-Buffering: no를 함께 보냅니다.
달라지는 것은 데코레이터에 무엇을 붙이느냐뿐입니다
mcp = FastMCP("travel-planner", host="0.0.0.0", port=8010)
@mcp.tool()
def plan_trip(question: str, max_steps: int = 6) -> dict:
"""여행 요청 한 줄로 일정과 예산을 세운다. 안에서 에이전트 루프가 돈다."""
result = service.plan(question, max_steps=max_steps)
return {"answer": result.answer, "stopped_by": result.stopped_by, ...} 붙는 쪽은 이렇게 만납니다
왕복 세 종류가 전부입니다
sequenceDiagram
autonumber
participant C as 붙는 쪽<br/>Claude Code · Inspector
participant S as 우리 MCP 서버<br/>travel-planner
C->>S: initialize · protocolVersion · clientInfo
S-->>C: serverInfo · capabilities
C->>S: notifications/initialized
Note over C,S: 여기까지가 악수. 마지막 것에는 답이 없다
C->>S: tools/list
S-->>C: 도구 넷 · 이름 · 설명 · inputSchema
Note over C: 모델이 이 목록만 읽고 무엇을 부를지 고른다
C->>S: tools/call · name · arguments
S-->>C: content[0].text직접 눌러 보기: 코드가 무엇이 되는가
돌고 있는 컨테이너에 붙어 받아 적은 실측입니다
우리가 쓴 것 — 파이썬
붙는 쪽이 받는 것 — tools/list 응답
세 칩을 눌러 보세요. 함수 이름이 도구 이름이 되고, docstring이 통째로 설명이 되고, 타입 힌트와 기본값이 inputSchema가 됩니다.
프로그램: 파이썬 클라이언트
6주차 예제 02 · 04와 같은 코드입니다. 방향만 뒤집혔습니다
- 실행
docker compose exec api python clients/py_client.py- 결과
[http] 이미 떠 있는 서버에 접속한다: http://mcp:8010/mcp
=== 프로토콜로 받은 도구 4개 ===
plan_trip: 여행 요청 한 줄로 일정과 예산을 세운다. …
search_places: 도시의 관광지·식당·카페를 검색한다. …
=== 에이전트를 통째로 부르기: plan_trip ===
거친 도구: ['search_places', 'calc_budget']
답: [각본 대역] 교토 1박 2일, 3명 일정입니다. 명령이 직접 알려 줍니다
- 등록할 때 나온 말
Added HTTP MCP server travel-planner with URL: http://localhost:8010/mcp to local config
File modified: /Users/…/.claude.json [project: /Users/…/week08-service-lab]- 확인
claude mcp list- 결과
travel-planner: http://localhost:8010/mcp (HTTP) - ✔ ConnectedDesktop에 붙이려면 clients/claude_desktop.json 견본을 씁니다. 그쪽은 stdio입니다.
워크플로를 불러옵니다
docker compose exec n8n n8n import:workflow --separate --input=/workflows
docker compose exec n8n n8n publish:workflow --id=week08webhook001
docker compose exec n8n n8n publish:workflow --id=week08mcpsrv0001
docker compose restart n8n불러오기만으로는 트리거가 살지 않습니다. n8n 2.x는 초안과 발행판이 따로라 발행해야 웹훅 주소가 생깁니다. 화면에서는 오른쪽 위 토글이 같은 일을 합니다.
불러 봅니다
- 실행
curl -s -X POST http://localhost:5678/webhook/travel \
-H 'content-type: application/json' \
-d '{"question": "교토 2박 3일 4명 고급 여행"}'- 결과
{"answer":"[각본 대역] 교토 2박 3일, 4명 일정입니다. …
예산 합계는 2,980,000원입니다 (숙박 500,000 · 식비 1,080,000 · 항공 1,400,000).",
"stopped_by":"final",
"usage":{"llm_calls":3,"prompt_tokens":3420,"completion_tokens":460,"total_tokens":3880}} 우리 파이썬 클라이언트로 붙어 봅니다
- 실행
docker compose exec -e MCP_URL=http://n8n:5678/mcp/travel-tools \
api python clients/py_client.py- 결과
n8n이 내어놓은 도구: [('plan_trip', ['question'])]
호출 결과: [{"answer":"[각본 대역] 오사카 2박 3일, 2명 일정입니다. …MCP Server Trigger는 typeVersion 2.1부터 streamable HTTP입니다. 1.x는 SSE라
/mcp/<path>/sse로 붙어야 합니다.
LiteLLM이 서버로 섭니다
model_list:
- model_name: travel-demo # 키가 없어도 도는 시연용
litellm_params:
model: openai/gpt-4o-mini
api_key: "not-needed"
mock_response: "게이트웨이의 모의 응답입니다. 진짜 모델을 부르지 않았습니다."
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY # 이 키로만 가상키를 발급한다5주차에 배운 litellm이 이번에는 라이브러리가 아니라 서버입니다.
가상키로는 키를 찍어낼 수 없습니다
- 실행
# ② 방금 받은 가상키로 또 발급을 시도하면
curl -s -X POST localhost:4000/key/generate \
-H 'Authorization: Bearer sk-X2YZqszic5CYcfVl5IbXlA' \
-H 'content-type: application/json' -d '{"models":["travel-demo"]}'- 결과
401 Only proxy admin can be used to generate, delete, update info
for new keys/users/teams. Route=/key/generate. Your role=unknown.그 권한이 마스터 키에만 있다는 것이 이 구조의 전부입니다.
상한을 아주 낮게 걸고 소진시켜 봅니다
- 실행
docker compose exec api python examples/04_virtual_key.py- 결과
발급된 가상키: sk-gLmQhi_JX… (진짜 프로바이더 키는 게이트웨이만 안다)
허용 모델: ['travel-demo'] · 상한: $2e-05
호출 1: 200 게이트웨이의 모의 응답입니다.
호출 2: 200 게이트웨이의 모의 응답입니다.
호출 3: 429 Budget has been exceeded! Current cost: 2.6e-05, Max budget: 2e-05
호출 4: 429 Budget has been exceeded! …
호출 5: 429 Budget has been exceeded! … compose 파일이 그렇게 되어 있습니다
api:
environment: # 앱이 쥐는 것은 이게 전부다
LLM_MODE: ${LLM_MODE:-auto}
GATEWAY_URL: ${GATEWAY_URL:-}
GATEWAY_KEY: ${GATEWAY_KEY:-}
GATEWAY_MODEL: ${GATEWAY_MODEL:-}
litellm-proxy:
env_file: gateway/.env # 진짜 키와 마스터 키는 여기에만 있다LITELLM_MASTER_KEY는 이 목록에 없습니다. 8장 1절의 표가 compose 파일로
나타난 것입니다.