라이브 세션의 상세 교안입니다. 이번 주는 이론 1시간과 실습 1시간으로 나뉩니다.
문서에 실린 실행 결과는 전부week08-service-lab을 2026-09-10에 실제로 돌린 실측입니다. API 키 없이 재현됩니다.
- 교재: week08-service-lab
- 형태: compose 실습 랩.
api(8000) ·ui(8501) ·mcp(8010) ·n8n(5678) ·litellm-proxy(4000) ·db - 앞선 주: 7주차에서 루프 여럿을 엮은 멀티 에이전트 구조를 해부했습니다.
1. 세션 목표
7주 동안 만든 것은 전부 터미널에서 돌았습니다. python -m agent.main을
치는 사람이 있어야 움직였고, 그 사람은 언제나 우리였습니다. 이번 주에
그것이 끝납니다.
한 문장으로: 내가 만든 AI 기능을, 남이 부를 수 있게 만든다.
- 경계: 내 기능과 바깥 세상 사이에 계약을 하나 세웁니다. 이 계약이 8주차의 전부입니다.
- 두 개의 앞문: 사람이 부르는 HTTP가 앞문 ①, 다른 AI가 부르는 MCP가 앞문 ②입니다. 둘은 같은 코어를 봅니다.
- 세 번째 문: 두 개의 앞문과 달리 누가 부르지 않아도 열립니다. 웹훅이 오거나 특정 시간이 되면 이벤트가 우리를 부릅니다.
- 뒷문: 앱이 진짜 키를 모르게 합니다. 키와 상한은 게이트웨이가 쥡니다.
오늘 새로 배우는 것은 사실상 둘뿐입니다. 서비스 경계와 자동화. 나머지 시간은 이미 배운 것들을 제자리에 놓는 일입니다.
| 층 | 배운 곳 | 오늘의 자리 |
|---|---|---|
| Pydantic | 3주차 | 요청 검증 = 도구 스키마 = MCP 도구 명세 |
| 헤드리스 API·SSE | 3주차 | 그대로 다시 씁니다. 새로 배우지 않습니다 |
| LiteLLM | 5주차 | 라이브러리였던 것이 이번 주에는 서버로 섭니다 |
| 도구 | 5주차 | 데코레이터 한 줄로 MCP 도구가 됩니다 |
| 루프·하네스 | 6주차 | 요청 하나가 루프 한 번. 트레이스가 화면이 됩니다 |
| MCP 클라이언트 | 6주차 | 6장 5절에서 미뤄 둔 내어주기를 오늘 합니다 |
| LangGraph 그래프 | 7주차 | 서버에 얹을 때 무엇이 달라지는지 봅니다 |
2. 브리핑: 터미널에서 세상으로
2-1. 이번 주의 진행 방식
앞의 두 시간을 이렇게 나눕니다.
| 무엇을 | 어디를 읽나 | |
|---|---|---|
| 이론 60분 | 경계·앞문·자동화·키 | 3~8장 |
| 실습 60분 | 랩을 직접 돌립니다 | 4~8장의 실행 블록 |
이 교안은 세션에서 말하는 것보다 깁니다. 4·5·6장은 10주차부터 자기 프로젝트를 만들 때 다시 펴 보는 장입니다. 그때 필요한 절차를 빠짐없이 적어 두었습니다.
2-2. 오늘의 그림
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(("모델 제공자"))문이 셋이고 코어는 하나입니다. 그림에서 core/로 들어가는 화살표가 여럿인
것이 이번 주의 전부입니다. 문은 껍데기고, 껍데기는 얼마든지 더 달 수
있습니다.
뒤쪽에 문이 하나 더 있습니다. 게이트웨이는 우리가 모델을 부르는 문이고, 앞의 셋과 반대 방향입니다.
core/를 봅니다. 게이트웨이만 방향이 반대로,
코어가 모델을 부를 때 지나갑니다.
- 부르는 쪽
- 필요한 것
상자를 눌러 보세요. 문마다 부르는 쪽과 필요한 것이 다르지만, 네 상자가
가리키는 코드는 전부 core/service.py의 함수 둘입니다.
2-3. 게이트웨이는 왜 있나
그림의 오른쪽 끝을 보면 우리 코드와 모델 제공자 사이에 litellm-proxy :4000이
한 칸 끼어 있습니다. 앱이 하나뿐이라면 이 칸은 없어도 됩니다. FastAPI가
프로바이더를 직접 부르면 그만이고, 그게 더 단순합니다.
문제는 앱이 하나로 끝나지 않는다는 데 있습니다. 이번 주만 해도 우리 코어를 부르는 곳이 셋이고, 여기에 배치 잡이나 동료의 실험 노트북이 붙기 시작하면 같은 일이 벌어집니다. 진짜 키가 복사됩니다.
flowchart LR
A1["api"] -->|"진짜 키"| P(("모델 제공자"))
A2["배치 잡"] -->|"진짜 키 (복사본)"| P
A3["n8n"] -->|"진짜 키 (복사본)"| P
A4["동료의 노트북"] -->|"진짜 키 (복사본)"| P이 상태에서 키 하나가 새면 전부 폐기해야 합니다. 누가 얼마를 썼는지도 알 수 없고, 어느 하나에만 상한을 걸 방법도 없습니다. 게이트웨이는 이 그림을 이렇게 바꿉니다.
flowchart LR
B1["api"] -->|"가상키 A"| G["게이트웨이<br/>litellm-proxy :4000"]
B2["배치 잡"] -->|"가상키 B · 상한 $5"| G
B3["n8n"] -->|"가상키 C"| G
B4["동료의 노트북"] -->|"가상키 D · 상한 $1"| G
G -->|"진짜 키 하나"| P(("모델 제공자"))- 키가 새면 그 가상키 하나만 폐기합니다.
- 상한을 사람마다, 앱마다 다르게 겁니다. 앱을 고치지 않고 발급 시점에 정합니다.
- 누가 얼마 썼는지가 한 장부에 쌓입니다.
직접 늘려 보고, 사고도 한 번 내 보세요. 두 배치가 무엇을 맞바꾼 것인지는 사고가 났을 때 드러납니다.
대가는 분명합니다. 장애점이 하나 늘어납니다. 게이트웨이가 죽으면 그것을 쓰는 앱이 전부 모델을 못 부릅니다. 그래서 실제 운영에서는 게이트웨이를 이중화하거나, 게이트웨이가 죽으면 직접 호출로 떨어지는 폴백을 둡니다. 5주차의 폴백 체인과 같은 생각입니다. 우리 랩은 컨테이너 하나로 두었습니다.
판단은 단순합니다. 앱이 하나면 직접 호출이 맞습니다. 10~14주차 개인 프로젝트는 대개 그쪽입니다. 게이트웨이는 부르는 곳이 둘 이상이 되거나 키를 남에게 나눠줘야 할 때부터 값을 합니다. 자세한 것은 8장에서 다룹니다.
litellm이라는 이름이 두 번 나오는 것이 헷갈리기 쉽습니다. 5주차에 배운 것은 라이브러리이고,:4000에 뜬litellm-proxy는 같은 프로젝트의 프록시 서버입니다. compose 서비스 이름도 그래서litellm-proxy입니다. 앱은 여전히 라이브러리로 호출하고, 그 호출이 향하는 주소만 프록시로 바뀝니다.
2-4. 저장소 기동
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 # api · ui · mcp · n8n · litellm-proxy · db
docker compose exec api pytest
- 화면:
http://localhost:8501 - API 문서:
http://localhost:8000/docs
20 passed, 2 warnings in 1.28s
키가 하나도 없어도 전부 돌아갑니다. 키가 없으면 core/offline.py의 각본
대역이 모델을 대신합니다. 7주차 저장소들은 키 환경변수의 진위값을 검사해서
“더미 키라도 채워야 테스트가 도는” 함정이 있었는데, 이번에는 그 함정을
만들지 않았습니다.
가짜인 것은 모델뿐입니다. 도구는 진짜로 실행되고, 결과는 진짜로 되먹여지고, 예산도 진짜로 쌓입니다. 화면에서 가짜인 부분은 무엇을 부를지 정하는 판단 하나입니다.
curl -s localhost:8000/config
{"mode":"offline","model":"offline/scripted-planner","gateway":null,
"defaults":{"max_steps":6,"max_cost_usd":0.2}}
게이트웨이를 켜면 mode가 live로 바뀝니다. 코드는 한 줄도 바뀌지 않습니다.
3장부터 7장까지는 이 상태 그대로 진행합니다. 검증도, 에러도, 스트리밍도, MCP도, n8n도 각본 대역으로 전부 확인됩니다. 진짜 모델이 필요한 것은 8장 하나뿐입니다.
지금 당장 진짜 모델로 보고 싶다면 8장 3절의
네 단계를 먼저 하고 오세요. 게이트웨이를 띄우고, 화면에서 가상키를 발급하고,
.env에 넣고, 앱만 다시 만드는 것입니다. 급하지 않다면 순서대로 읽는 편이
낫습니다. 왜 그렇게 하는지를 8장이 설명하기 때문입니다.
이 랩의 앱에는 프로바이더 키를 넣을 자리가 없습니다. .env를 열어 보면
GEMINI_API_KEY 같은 줄이 아예 없습니다. 앱이 모델을 직접 부르지 않기
때문이고, 진짜 키는 gateway/.env에만 있습니다. 8장에서 왜 이렇게 나눴는지
봅니다.
3. 경계 정하기
3-1. 진입 함수 하나로 좁힌다
문을 달기 전에 할 일이 하나 있습니다. 내 기능이 무엇인지 함수 하나로 말하는 것입니다. 이 일이 8주차 작업의 8할이고, 나머지는 거의 기계적입니다.
core/service.py에 함수는 둘뿐입니다.
def plan(question: str, *, max_steps=6, max_cost_usd=0.20) -> PlanResult
def plan_events(question: str, ...) -> Iterator[dict]
앞의 것은 답 하나를 돌려주고, 뒤의 것은 같은 일을 하면서 스텝마다 이벤트를 내놓습니다. 문이 몇 개가 되든 부르는 것은 이 둘입니다.
core/service.py
core/harness.py
core/react.py
api/main.py
mcp_server/server.py
카드를 누르면 파라미터와 리턴이 펼쳐지고, 그 심볼이 닿는 곳으로 화살표가 그려집니다. plan을 눌러 보세요.
오른쪽 위의 AI 표시는 그 지도에서 모델로 가는 마지막 단이라는 뜻입니다.
위 지도에서는 run_iter 하나에 붙어 있습니다. plan도 plan_events도 결국
모델까지 이어지지만, 그 둘은 run_iter에게 시킬 뿐이라 표시가 없습니다.
run_iter도 진짜 끝은 아닙니다. 한 칸만 더 가면 이 저장소에서 litellm을
실제로 부르는 한 곳이 나옵니다.
core/llm.py
core/config.py
core/errors.py
core/offline.py
core/react.py
이 저장소에서 모델로 나가는 유일한 자리가 AI 표시가 붙은 completion입니다. 눌러 보면 게이트웨이 주소와 가상키를 어디서 읽는지, 각본 대역으로는 언제 갈라지는지가 보입니다.
표시는 손으로 붙인 것이 아닙니다. 추출기가 litellm 호출을 찾아 그 자리를
표시하고, 지도마다 거기로 이어지는 마지막 단을 계산합니다. 나중에 누가 다른
곳에서 모델을 부르면 표시가 하나 더 생깁니다. 표시가 둘이 되는 순간이
경계가 새는 순간입니다.
경계를 그었다는 증거는 import 방향에 있습니다.
core/는 fastapi도 mcp도 import하지 않습니다.api/와mcp_server/는core만 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이 방향이 뒤집히면 이번 주에 가르치려는 것이 사라집니다. 코어가 문을 알기 시작하면 문을 하나 더 달 때마다 코어를 고쳐야 하기 때문입니다.
3-2. 스트리밍과 동기 응답이 갈라지면 안 된다
plan()은 plan_events()를 끝까지 소비할 뿐입니다.
def plan(question, **kwargs) -> PlanResult:
for event in plan_events(question, **kwargs):
... # 이벤트를 모아 결과 하나로 조립한다
둘이 각자 다른 코드를 돌면 그 순간부터 둘 중 하나는 거짓말을 시작합니다. 스트림에는 보이는데 응답에는 없는 스텝, 응답에는 있는데 스트림에는 안 흐른 경고 같은 것들이 생깁니다. 그래서 테스트가 둘의 답이 같은지를 봅니다.
def test_events_and_result_agree():
events = list(service.plan_events("오사카 2박 3일 2명"))
result = service.plan("오사카 2박 3일 2명")
assert events[-1]["answer"] == result.answer
3-3. 스키마 하나가 네 곳에서 쓰인다
3주차부터 pydantic 모델을 써 왔습니다. 5주차에는 도구 스키마를 그것으로 만들었고, 6주차에는 MCP가 보내온 스키마가 같은 모양이라는 것을 봤습니다. 이번 주에 그 셋이 한자리에 모입니다.
| 쓰이는 곳 | 어디서 | 무엇을 하나 |
|---|---|---|
| 요청 검증 | 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/>사람에게 설명"]넷 다 같은 스키마를 다른 쪽에서 본 것입니다. 그래서 8주차에 스키마를 새로
쓸 일이 거의 없습니다. core/tools.py는 6주차 파일 그대로이고, 한 줄도
고치지 않았습니다.
4. 앞문 ①: HTTP 서버 만들기
4-1. 3주차에서 이미 한 것
이 장의 절반은 복습입니다. 3주차 식단 플래너에서 이미 했습니다.
- 헤드리스 구조: UI와 API가 다른 컨테이너이고, 대화는 HTTP뿐입니다. “UI를 Streamlit에서 Next.js로 갈아끼워도 API는 한 줄도 안 바뀝니다”
- 입출구의 타입 보증: 입구는
PlanRequest, 출구는 instructor - SSE 진행 이벤트:
POST /plan/stream으로 파이프라인 진행을 흘렸고, 서버에 작업 상태를 저장하지 않았습니다. - 관측: 응답에
llm_calls를 실어 호출별 입출력·토큰·비용을 열어 봤습니다.
그러니 4장에서 진짜 새로운 것만 짚습니다. 에러 처리·그래프 배치·동시성 셋입니다.
4-2. 검증: 계약이 없으면 무슨 일이 생기는가
같은 일을 하는 엔드포인트 둘을 나란히 놓고 잘못된 요청 다섯 개를 던집니다.
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입니다. 빈 질문도, 스텝 9999도, 10만 자짜리 질문도 통과해서 핸들러 안까지 들어갑니다. 그리고 거기서 터지거나, 더 나쁘게는 터지지 않고 모델에게 10만 자를 보냅니다.
flowchart LR
Q(["요청"]) --> V{"pydantic<br/>계약 검사"}
V -->|"어긋남"| E["422<br/>핸들러에 닿지 못한다"]
V -->|"통과"| H["핸들러"]
H --> C["core.service.plan()"]오른쪽 핸들러에는 방어 코드가 한 줄도 없습니다. 그럴 필요가 없기 때문입니다.
class PlanRequest(BaseModel):
question: str = Field(min_length=2, max_length=500)
max_steps: int = Field(default=6, ge=1, le=12)
max_cost_usd: float = Field(default=0.20, gt=0, le=5.0)
max_steps에 상한이 있는 것을 봐 두세요. 6주차에서 스텝 한도는 성능
손잡이가 아니라 보험이라고 했습니다. 그 보험을 사용자가 마음대로 9999로
올릴 수 있으면 보험이 아닙니다.
4-3. 에러: 500이 아니라는 것이 중요하다
모델 제공자가 죽었을 때 500을 돌려주면 사용자도 우리도 원인을 잘못 짚습니다. 500은 “우리 코드가 깨졌다”는 뜻이기 때문입니다.
코어는 무엇이 실패했는지만 말하고, 그것이 몇 번인지는 문이 정합니다.
# core/errors.py — 코어는 HTTP를 모른다
class UpstreamError(CoreError): ... # 모델 쪽이 실패했다
class UpstreamTimeout(CoreError): ... # 제때 답하지 않았다
# api/errors.py — 문이 번역한다
STATUS = {UpstreamTimeout: 504, UpstreamError: 502}
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 --> Lcore/errors.py
api/errors.py
UpstreamError를 눌러 보세요. 상속 화살표가 CoreError로 올라갑니다. 코어의 예외 셋과 문의 번역표가 이 그림의 전부입니다.
랩에는 실패를 5초 만에 재현하는 스위치가 있습니다. 실제 서비스에는 이런 인자를 두지 않습니다.
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=502
simulate=timeout이면 504가 옵니다. 응답에 request_id가 실려 있는 것도
봐 두세요. 사고가 났을 때 사용자가 들고 오는 것은 이 열두 글자 하나입니다.
서버 로그에 같은 값이 남습니다.
2026-09-10 07:41:02 INFO POST /plan -> 502 12ms request_id=0acf2c7a8dbd
6주차의 트레이스가 “한 줄이 한 이벤트”였다면, 여기서는 한 줄이 한 요청입니다.
4-4. 그래프를 얹을 때 달라지는 것: 상태
우리 랩의 코어는 6주차의 손 루프입니다. 요청 하나가 루프 한 번이고, 끝나면 아무것도 남지 않습니다. 무상태입니다.
7주차의 그래프를 얹으면 이야기가 달라집니다. week07-support-agent의
코드가 이미 답을 갖고 있습니다.
# 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}"}}
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는 요청이 가져온다. 7주차 교안에서 “고객 신원은 화면의 선택에서 와서 상태에 실린다”고 한 것과 같은 원칙입니다. 모델이 정하게 두지 않습니다.
7주차에는 그래프만 보고 이 층을 지나쳤습니다. 서비스가 되는 순간 이 층이 전부입니다.
4-5. 동시성: async def 한 줄의 대가
우리 랩에는 일부러 잘못 만든 문이 하나 있습니다. /plan은 def이고
/plan/blocking은 async def입니다. 안에서 부르는 코드는 똑같습니다.
docker compose exec api python examples/02_blocking_worker.py
/plan 1건 → 1.22s (한 요청의 원래 시간)
/plan 5건 동시 → 1.21s def → 워커 스레드로 나간다
/plan/blocking 5건 동시 → 6.06s async def → 줄을 선다
같은 코어, 같은 일. 차이는 5.0배.
def · 5건과 async def · 5건을 번갈아 재생해 보세요. 같은 코어가 같은 일을 하는데 벽시계만 다섯 배 차이가 납니다.
FastAPI는 동기 핸들러(def)를 워커 스레드로 보냅니다. 그래서 한 요청이 오래
걸려도 이벤트 루프는 다른 요청을 계속 받습니다. async def 안에서 동기
호출을 하면 이벤트 루프가 그 자리에 묶이고, 서버는 죽지 않은 채로 한 사람만
상대합니다.
혼동하기 쉬운 지점이라 정리해 둡니다.
| 핸들러 | 안에서 하는 일 | 결과 |
|---|---|---|
def | 동기 호출 (우리 코어) | 워커 스레드로 나간다. 올바름 |
async def | await 하는 비동기 호출 | 올바름 |
async def | 동기 호출 | 이벤트 루프가 멈춘다 |
LLM 호출은 대개 몇 초씩 걸립니다. 이 실수 하나로 동시 사용자 5명이 5배 느린 서비스를 쓰게 됩니다.
4-6. 스트리밍: 총 시간이 아니라 첫 글자까지의 시간
5주차에서 모델이 답을 조각으로 준다는 것을 봤습니다. 그 조각을 HTTP로 흘리는 것이 이 절입니다.
docker compose exec api python examples/03_stream_buffered.py
/plan 첫 응답 1.21s · 완료 1.21s
0.00s start start
0.41s step search_places
0.81s step calc_budget
1.22s step step
1.22s final final
/plan/stream 첫 응답 0.00s · 완료 1.22s
위 타임라인의 SSE · 1건 모드가 같은 실측입니다. 이벤트 점 넷이 0.41초 간격으로 켜지는 것을 보세요.
총 시간은 같습니다. 바뀐 것은 사용자가 빈 화면을 보는 시간이고, 그것이 1.21초에서 0초가 됐습니다. 스트리밍은 비용을 1원도 줄이지 않습니다. 체감만 바꿉니다.
그리고 흐르는 내용을 보세요. search_places, calc_budget은 6주차에
트레이스로 읽던 그 스텝들입니다. 로그였던 것이 화면이 됩니다.
코드에서 조심할 곳은 둘입니다.
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__})}
두 번째가 3주차에는 없던 이야기입니다. 스트림이 시작되면 응답 상태 코드는 이미 200으로 나가 버렸습니다. 그 뒤에 상류가 죽으면 502로 고칠 방법이 없습니다. 실패도 이벤트로 보내야 합니다.
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"
프록시가 스트림을 통째로 모았다가 한 번에 주는 사고도 흔합니다. 그래서
Cache-Control: no-cache와 X-Accel-Buffering: no를 함께 보냅니다.
5. 앞문 ②: MCP 서버 만들기
5-1. 6주차에서 이미 한 것
6주차 6장에서 도구를 MCP 서버로 내어놓는 법을 이미 봤습니다.
examples/07_mcp/01_mcp_server.py가 그것이었고, 마지막 절은 이렇게
끝났습니다.
1번 예제의
@mcp.tool()데코레이터에 우리 함수를 붙이고 HTTP로 띄우면, 남의 클라이언트가 우리 도구를 부릅니다. 가져오기를 이해했다면 내어주기는 같은 그림을 뒤집어 보는 일입니다.
오늘 그 문장을 실행합니다. 달라지는 것은 데코레이터에 무엇을 붙이느냐뿐입니다. 그때는 함수 두 개였고, 지금은 에이전트 하나와 도구 셋입니다.
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, ...}
손으로 쓴 스키마가 한 줄도 없습니다. 시그니처와 docstring이 그대로 명세가 됩니다.
붙는 쪽은 이 함수를 이렇게 만납니다. 왕복 세 종류가 전부입니다.
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악수 → 목록 → 호출. MCP 클라이언트가 하는 일은 이 셋뿐입니다. 사람이 Swagger 문서를 읽고 curl을 치는 순서와 같고, 읽는 쪽이 모델이라 문서가 JSON이어야 할 뿐입니다.
tools/list가 무엇을 돌려주는지는 말로 하는 것보다 보는 편이 빠릅니다.
아래는 돌고 있는 컨테이너에 붙어 받아 적은 것입니다.
우리가 쓴 것 — 파이썬
붙는 쪽이 받는 것 — tools/list 응답
한 번 불러 본 것 — tools/call
위의 세 칩을 눌러 보세요. 함수 이름이 도구 이름이 되고, docstring이 통째로 모델이 읽는 설명이 되고, 타입 힌트와 기본값이 inputSchema가 됩니다. 우리가 손으로 쓴 JSON은 한 글자도 없습니다. plan_trip 하나만 성격이 다릅니다. 저 한 번의 호출 안에서 우리 에이전트 루프가 돕니다.
plan_trip의 description을 보면 docstring이 통째로 넘어가 있습니다.
예: "오사카 2박 3일 2명, 보통 스타일로" 한 줄까지 모델이 읽습니다. 반대로
description이 비어 있으면 모델은 이름만 보고 고릅니다. docstring은 주석이
아니라 인터페이스입니다. 5주차에 도구 설명을 다듬어 선택 품질을 올렸던
것과 같은 자리입니다.
같은 것을 테스트로도 박아 뒀습니다.
def test_schemas_come_from_the_function_signature():
budget = {t.name: t for t in _run(mcp.list_tools())}["calc_budget"]
assert set(budget.inputSchema["properties"]) == {
"nights", "people", "style", "include_flight"
}
assert budget.inputSchema["required"] == ["nights", "people"]
한 가지 주의할 점이 있습니다. 로컬 패키지 이름을 mcp로 지으면 안
됩니다. MCP SDK를 가려 버립니다. 그래서 이 저장소의 폴더 이름은
mcp_server/입니다.
그리고 버전 이야기가 하나 더 있습니다. 6주차 랩과 이 저장소는 mcp>=1.0,<2에
고정돼 있습니다. mcp 2.x에서 FastMCP가 MCPServer로 이름이 바뀌어
6주차 예제와 import가 달라지기 때문입니다. 7주차에 litellm 요금표 드리프트로
겪은 것과 같은 종류의 문제이고, 해법도 같습니다. 핀을 박습니다.
5-2. 도구를 어디서 자를 것인가
정답이 없고 갈림길이 있습니다. 우리는 둘 다 내어놓고 부르는 쪽이 고르게 했습니다.
에이전트를 통째로 (plan_trip) | 도구를 낱개로 (search_places 등) | |
|---|---|---|
| 부르는 쪽이 하는 일 | 한 번 부르고 답을 받는다 | 자기 루프로 조합한다 |
| 루프는 누가 도나 | 우리 | 부르는 쪽 AI |
| 통제 | 우리가 스텝·예산·하네스를 쥔다 | 넘어간다 |
| 유연함 | 우리가 설계한 만큼 | 부르는 쪽이 상상한 만큼 |
| 비용 | 우리 지갑 | 부르는 쪽 지갑 |
flowchart LR
subgraph one["에이전트를 통째로"]
A1(("남의 AI")) -->|"plan_trip 1회"| A2["우리 루프가<br/>3번 돈다"]
A2 --> A3["우리 지갑"]
end
subgraph many["도구를 낱개로"]
B1(("남의 AI")) -->|"search_places"| B2["조회"]
B1 -->|"calc_budget"| B3["계산"]
B1 -->|"추론은 저쪽 루프"| B4["남의 지갑"]
endmcp_server/server.py
core/service.py
core/tools.py
plan_trip은 코어의 plan 하나로 이어지고, 나머지 셋은 core/tools.py의 함수로 곧장 갑니다. 통째로와 낱개의 차이가 화살표의 길이입니다.
비용 열이 중요합니다. 에이전트를 통째로 내어놓으면 남이 부를 때마다 우리 모델 비용이 나갑니다. 도구만 내어놓으면 추론은 부르는 쪽 AI가 하므로 우리는 조회 비용만 냅니다. 5주차에 도구 목록이 길수록 선택 품질이 떨어진다고 했던 것도 여기서 다시 걸립니다. 낱개로 열 개를 내어놓는 것이 늘 좋은 것은 아닙니다.
5-3. stdio냐 HTTP냐는 붙는 쪽이 정한다
6주차 6장 4절의 대비표가 여기서 실전 이유를 얻습니다.
| stdio | streamable HTTP | |
|---|---|---|
| 서버의 수명 | 클라이언트가 띄우고 거둔다 | 먼저 떠서 계속 산다 |
| 관계 | 1 클라이언트 : 1 전용 서버 | N 클라이언트 : 1 서버 |
| 쓰임 | 내 기계 안의 도구 | 세상에 내어주는 배포 |
flowchart TB
subgraph s["stdio — 내 기계 안"]
C1(("클라이언트")) -->|"하위 프로세스로 띄운다"| S1["서버"]
end
subgraph h["streamable HTTP — 세상에"]
S2["상주 서버 :8010/mcp"]
C2(("클라이언트 A")) --> S2
C3(("클라이언트 B")) --> S2
C4(("ChatGPT")) -->|"공개 HTTPS 필요"| S2
end우리 서버는 둘 다 됩니다. 컨테이너는 HTTP로 뜨고, 필요하면 --stdio로
바꿉니다.
def main() -> None:
if "--stdio" in sys.argv:
mcp.run() # 클라이언트가 이 프로세스를 띄운다
else:
mcp.run(transport="streamable-http") # 상주 서버: /mcp 에서 기다린다
5-4. 내어줄 때의 안전
도구를 남에게 열어 준다는 것은 우리 코드를 남의 AI가 부르게 한다는 뜻입니다. 6주차 하네스에서 세운 원칙이 그대로 필요합니다.
- 설명문이 곧 인터페이스다. docstring이 남의 AI가 읽는 유일한 설명입니다. 5주차에서 이름과 설명이 선택 품질을 가른다고 한 그 자리입니다.
- 위험한 도구에는 게이트를 둔다. 우리 랩의 도구는 전부 조회라 위험이 없지만, 쓰기·삭제·결제가 붙는 순간 6주차 5장 5절의 승인 게이트가 필요합니다.
- 인자로 신원을 받지 않는다. 7주차 원칙 그대로입니다.
customer_id를 도구 스키마에 넣으면 남의 AI가 남의 청구서를 조회하겠다고 마음먹을 수 있습니다. - 공개하면 인증이 필요하다. 로컬에서는 아무나 붙어도 내 기계 안입니다. 공개 주소가 되는 순간 다릅니다 (6장 5절)
6. 붙이기 다섯 가지
문을 열었으면 붙여 봐야 합니다. 다섯 가지 방법이 있고, 뒤로 갈수록 우리 서버가 멀리 나갑니다.
| 부르는 쪽 | 무엇으로 | 필요한 것 |
|---|---|---|
| 사람 | curl · Swagger UI(/docs) | 없음 |
| 검사기 | MCP Inspector | 없음. 전원 가능 |
| 프로그램 | 파이썬 MCP 클라이언트 | 없음 |
| 다른 AI | Claude Code · Codex · Desktop | 로컬로 충분 |
| 다른 AI | ChatGPT | 공개 HTTPS 또는 터널 |
| 자동화 | n8n | n8n 컨테이너 (7장) |
flowchart LR
L["내 기계 안<br/>curl · Inspector · 파이썬"] --> M["내 AI 도구<br/>Claude Code · Codex"]
M --> W["세상<br/>ChatGPT · n8n · 남의 서비스"]
L -.->|"주소도 인증도 필요 없다"| L
W -.->|"주소 · 인증 · 상한 · 비용"| W6-1. 사람: curl과 Swagger
sh clients/curl.sh
/docs를 브라우저로 열면 같은 일을 화면으로 합니다. 9주차에 UI를 고르기
전까지, 이 화면이 이미 데모입니다. 3주차에서 “curl이나 Swagger로 불러도
똑같이 동작한다”고 한 것이 헤드리스 구조의 증명이었습니다.
http://localhost:8501에 화면도 한 장 붙여 뒀습니다. React와 shadcn/ui로
만들고 nginx가 냅니다. 이번 주의 주제는 화면이 아니라 문이라서 만드는 법은
다루지 않습니다. 다만 문이 열려 있다는
것을 눈으로 보는 편이 낫고, 스트리밍이 실제로 차오르는 장면은 curl -N보다
브라우저가 잘 보여줍니다. 이 화면은 문이 아니라 손님입니다. 특별한 통로
없이 /config와 /plan/stream만 부르므로 curl과 같은 문을 씁니다. 9주차에
각자 고를 UI가 이 자리에 앉습니다.
6-2. 검사기: MCP Inspector
npx @modelcontextprotocol/inspector@latest
벤더 중립 도구이고 계정이 필요 없습니다. 도구 목록·스키마·호출 결과를 눈으로 확인합니다. 서버가 멀쩡한데 안 붙는 것과, 서버가 잘못된 것은 다른 문제입니다. 이 도구가 그 둘을 갈라 줍니다.
6-3. 프로그램: 파이썬 클라이언트
6주차 예제 02·04와 같은 코드입니다. 방향만 뒤집혔습니다.
docker compose exec api python clients/py_client.py
[http] 이미 떠 있는 서버에 접속한다: http://mcp:8010/mcp
=== 프로토콜로 받은 도구 4개 ===
plan_trip: 여행 요청 한 줄로 일정과 예산을 세운다. 안에서 에이전트 루프가 돈다.
search_places: 도시의 관광지·식당·카페를 검색한다. 지원 도시: 오사카, 교토.
estimate_travel_time: 두 지역 사이의 대략적 이동 시간(분)을 조회한다.
calc_budget: 숙박·식비·항공을 합쳐 여행 예산(원)을 계산한다. style: 절약·보통·고급.
=== 에이전트를 통째로 부르기: plan_trip ===
거친 도구: ['search_places', 'calc_budget']
답: [각본 대역] 교토 1박 2일, 3명 일정입니다.
--stdio를 붙이면 같은 코드가 서버를 하위 프로세스로 띄워 붙습니다.
6-4. 다른 AI: Claude Code · Codex · ChatGPT
Claude Code는 한 줄이면 됩니다.
claude mcp add --transport http travel-planner http://localhost:8010/mcp
또는 프로젝트 루트에 .mcp.json을 둡니다.
{ "mcpServers": {
"travel-planner": { "type": "http", "url": "http://localhost:8010/mcp" }
} }
붙으면 Claude Code에서 /mcp로 연결과 도구 목록이 보이고, 자기가 7주 동안
만든 것을 자기 AI가 도구로 부릅니다. Codex도 같은 서버를 그대로 씁니다.
여기서 한 번은 헷갈립니다. claude mcp add가 성공했는데 Claude Desktop의
설정 화면에는 아무것도 안 나옵니다. 껐다 켜도 안 나옵니다. 고장이 아니라
둘이 다른 제품이고 설정 파일도 다르기 때문입니다.
| 설정이 사는 곳 | 전송 | 확인하는 곳 | |
|---|---|---|---|
| Claude Code | ~/.claude.json (프로젝트별) 또는 .mcp.json | HTTP·stdio | claude mcp list · 세션에서 /mcp |
| Claude Desktop | claude_desktop_config.json | stdio | 설정 → 개발자 → 로컬 MCP 서버 |
claude mcp add가 고쳤다고 알려 주는 파일 이름을 그대로 읽으면 됩니다.
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.json이라고 적혀 있습니다. Desktop 화면은 claude_desktop_config.json을
보여 주는 창이므로 여기 나올 리가 없습니다. 제대로 붙었는지는 이렇게 봅니다.
claude mcp list
travel-planner: http://localhost:8010/mcp (HTTP) - ✔ Connected
Desktop에 붙이려면 clients/claude_desktop.json 견본을 쓰십시오. 저 화면이
읽는 파일은 명령어와 인수를 받는 자리라 stdio입니다. 그래서 견본도
docker run --rm -i … --stdio입니다. 5장 3절의 “붙는 쪽이 정한다”가
여기서 그대로 걸립니다. 서버 코드는 한 줄도 바뀌지 않고 붙는 쪽 설정만
다릅니다.
ChatGPT는 다릅니다. 절차는 clients/chatgpt.md에 적어 두었습니다.
- ChatGPT 설정 → 보안 및 로그인 → 개발자 모드를 켠다 (가용 여부는 계정·워크스페이스 정책에 따라 다를 수 있다)
chatgpt.com/plugins에서 + → MCP 서버 URL을/mcp경로까지 넣는다.- 요구사항은 공개 HTTPS + streamable HTTP다. 로컬 stdio는 받지 않는다. Secure MCP Tunnel을 쓰면 서버를 공개하지 않고도 개발자 모드에서 닿게 할 수 있다.
이 절차는 2026-09-10에 확인한 것입니다. 화면과 메뉴 이름은 바뀔 수 있습니다.
6-5. 로컬과 세상의 차이
앞의 표에서 ChatGPT 줄만 요구사항이 다른 것이 우연이 아닙니다.
- stdio는 내 기계 안에서 끝난다. 클라이언트가 서버를 직접 띄우니 주소도 인증도 필요 없습니다.
- 웹 기반 AI에 붙이려면 우리 서버가 밖으로 나가야 한다. 그 순간부터 주소·인증·상한·비용이 전부 남의 일이 아니게 됩니다.
12주차 배포가 그 이야기입니다. 8주차는 문을 여는 데까지, 12주차는 그 문을 세상에 두는 데까지입니다.
7. 세 번째 문: n8n
7-1. 왜 자동화인가
지금까지의 문은 누군가 부를 때 열렸습니다. 사람이 브라우저를 열거나, 프로그램이 요청을 보내거나, AI가 도구를 골랐습니다. 전부 누군가의 의지가 있어야 움직였습니다.
세 번째 문은 다릅니다. 이벤트가 우리를 부릅니다.
- 웹훅이 도착한다 (고객이 폼을 제출했다)
- 정해진 시간이 됐다 (매일 아침 9시)
- 다른 서비스에서 무슨 일이 생겼다 (메일이 왔다, 시트가 바뀌었다)
flowchart LR
subgraph before["지금까지"]
P1(("사람")) -->|"의지"| S1["우리 서비스"]
A1(("다른 AI")) -->|"의지"| S1
end
subgraph after["세 번째 문"]
E1(["웹훅 도착"]) --> N["n8n"]
E2(["09:00"]) --> N
E3(["메일·시트 변경"]) --> N
N --> S2["우리 서비스"]
end이 문이 열리면 우리 서비스는 남의 업무 흐름 속의 부품이 됩니다. 그게 업무 자동화 트랙에 n8n이 적혀 있는 이유입니다.
7-2. n8n 한 바퀴
n8n은 노드를 이어 붙여 워크플로를 만드는 자동화 도구입니다. 우리 랩에서는 compose 서비스 하나로 뜹니다.
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는 워크플로에 초안과 발행판이 따로 있어서, 발행해야 웹훅 주소가 생깁니다. 화면에서는 오른쪽 위 토글이 같은 일을 합니다.
마지막 줄을 빼먹지 마세요. publish:workflow가 직접 그렇게 말해 줍니다.
Note: Changes will not take effect if n8n is running.
Please restart n8n for changes to take effect if n8n is currently running.
네 줄을 한꺼번에 붙여 넣을 때 주의할 것이 하나 있습니다. zsh 대화형 셸은
# 뒤를 주석으로 보지 않습니다. 명령 뒤에 설명을 붙여 두면 그것까지
인자로 들어가 no such service: #로 끝납니다. 앞의 세 줄은 성공했는데
마지막 한 줄만 조용히 실패해서, 웹훅을 불러 보고서야 알게 됩니다.
셋 중 02 · 아침 9시에만 발행하지 않는 것은 일부러입니다. 발행하면 매일
아침 9시에 진짜로 돕니다. 강의실에서는 7장 4절에서 화면으로 한 번 돌려 보는
것으로 충분합니다.
제대로 살았는지는 불러 보면 압니다.
curl -s -X POST localhost:5678/webhook/travel \
-H 'Content-Type: application/json' \
-d '{"question":"오사카 2박 3일 2명, 보통 스타일로"}'
404 … webhook "POST travel" is not registered가 돌아오면 발행이나 재시작
둘 중 하나가 빠진 것입니다.
http://localhost:5678 을 엽니다. 처음 열면 계정을 만들라고 하는데, 이 컨테이너 안에만 있는 로컬 계정입니다.
알아 둘 개념은 넷뿐입니다.
| 개념 | 무엇인가 | 우리가 아는 것으로 치면 |
|---|---|---|
| 노드 | 한 가지 일을 하는 상자 | 함수 하나 |
| 트리거 | 워크플로를 시작시키는 노드 | if __name__ == "__main__" |
| 크리덴셜 | 키·토큰을 따로 보관하는 곳 | .env |
| 실행 이력 | 매 실행의 입출력이 통째로 남는 기록 | 6주차의 트레이스 |
실행 이력이 6주차 트레이스와 같은 자리라는 것을 짚어 두세요. 노드마다 무엇이 들어가고 무엇이 나왔는지가 전부 남습니다. 사후 추적이 가능해야 운영이라는 말은 여기서도 같습니다.
7-3. 거울: 손으로 짠 루프가 노드 하나가 되어 있다 (슬라이드에 추가하지 않음)
캔버스의 **+**를 눌러 AI → AI Agent를 얹어 보세요. 우리 워크플로에
필요해서가 아니라, 6주차에 손으로 짠 것이 남의 도구에서 어떤 모양인지
보려는 것입니다.
노드를 열면 파라미터는 몇 개 없습니다. 프롬프트를 어디서 받을지, 출력 형식을 고정할지, 모델이 실패했을 때 대신 부를 모델을 둘지. 진짜는 아래쪽 세 연결점입니다.
Chat Model * Memory Tool
↑ ↑ ↑
6주차 core/llm.py 6주차 대화 이력 6주차 core/tools.py
6주차에 각각 파일 하나씩이었던 것이 여기서는 소켓 셋입니다. 별표가 붙은 Chat Model만 필수인 것도 같습니다. 모델 없이는 루프가 돌지 않고, 메모리와 도구는 없어도 한 바퀴는 돕니다.
5주차의 LiteLLM 도입, 7주차의 LangGraph 도입과 같은 자리입니다. 바닥을 본 다음에 추상화를 보는 것.
선택지가 사라졌다는 것이 답이다
옛 n8n에서는 이 노드에 에이전트 종류를 고르는 칸이 있었습니다. 지금은 없습니다. 컨테이너 안을 열어 보면 이유가 보입니다.
Agent 노드 V1 (버전 1 ~ 1.9) conversationalAgent · openAiFunctionsAgent
planAndExecuteAgent · reActAgent
sqlAgent · toolsAgent ← 여섯 중 고름
Agent 노드 V3 (버전 3 · 3.1) toolsAgent ← 하나뿐, 기본값
여섯 폴더는 아직 디스크에 그대로 있습니다. 옛 워크플로가 깨지면 안 되니까 남겨 둔 것이고, 새로 얹는 노드는 3.1이라 고를 것이 없습니다.
6주차 4장에서 루프의 스펙트럼을 보며 “적응력과 비용 사이”라고 했던 그 스펙트럼이, 현장에서는 도구 호출 기반 하나로 좁혀졌다는 뜻입니다. ReAct도 Plan-and-Execute도 사라진 것이 아니라 그 안으로 들어갔습니다. 이런 판단을 읽으려면 스펙트럼을 알아야 합니다.
7-4. 우리 서비스를 부른다
첫 번째 워크플로는 노드 셋입니다.
flowchart LR
W["웹훅<br/>POST /webhook/travel"] --> H["HTTP Request<br/>POST http://api:8000/plan"]
H --> R["웹훅에 응답<br/>answer · usage"]HTTP Request 노드가 우리 API를 부릅니다. 주소가 localhost가 아니라
api인 것을 봐 두세요. compose 네트워크에서는 서비스 이름이 곧
호스트명입니다. 2주차 app↔db, 3주차 ui↔api와 같은 원리입니다.
curl -s -X POST http://localhost:5678/webhook/travel \
-H 'content-type: application/json' \
-d '{"question": "교토 2박 3일 4명 고급 여행"}'
{"answer":"[각본 대역] 교토 2박 3일, 4명 일정입니다.\n\n- 1일차: 후시미 이나리 …
예산 합계는 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}}
코드를 한 줄도 쓰지 않고 우리 서비스에 새 입구가 하나 생겼습니다. 이것이 문이 껍데기라는 말의 마지막 증거입니다. 두 번째 워크플로는 트리거만 바꾼 것입니다. 매일 아침 9시가 되면 사람 없이 같은 요청이 나갑니다.
화면에서 「Execute workflow」를 누르면
여기서 한 번 더 걸립니다. 화면에서 실행 버튼을 눌러 놓고 위의 curl을 쳐도
캔버스에는 아무 일도 일어나지 않습니다. 웹훅 주소가 둘이기 때문입니다.
웹훅 노드를 열면 위쪽에 Test URL과 Production URL 탭이 나란히 있습니다.
| 주소 | 언제 받나 | 결과가 보이는 곳 | |
|---|---|---|---|
| 테스트 | /webhook-test/travel | 「Execute workflow」를 누른 뒤 딱 한 번 | 캔버스에 바로 |
| 운영 | /webhook/travel | 워크플로가 발행돼 있으면 항상 | 실행 이력에만 |
즉 노드마다 무엇이 오갔는지 눈으로 보려면 테스트 주소로 쏴야 합니다.
curl -s -X POST http://localhost:5678/webhook-test/travel \
-H 'content-type: application/json' \
-d '{"question": "교토 2박 3일 4명 고급 여행"}'
버튼을 안 누른 채로 테스트 주소를 치면 n8n이 직접 알려 줍니다.
{"code":404,"message":"The requested webhook \"travel\" is not registered.",
"hint":"Click the 'Execute workflow' button on the canvas, then try again.
(In test mode, the webhook only works for one call after you click this button)"}
한 번 받으면 리스닝이 끝나므로 다시 보려면 버튼을 또 눌러야 합니다. 반대로 운영 주소는 버튼과 무관하게 항상 열려 있고, 대신 캔버스가 아니라 왼쪽 실행 이력에 남습니다. 시연은 테스트 주소로 하고, 남에게 주는 주소는 운영 주소입니다.
7-5. 반대 방향: 워크플로가 MCP 서버가 된다
세 번째 워크플로는 방향이 반대입니다. n8n이 도구를 내어놓고, Claude가 그것을 부릅니다.
flowchart LR
C(("Claude Code")) -->|"MCP"| T["MCP Server Trigger<br/>/mcp/travel-tools"]
T --- X["HTTP Request Tool<br/>plan_trip"]
X --> A["api :8000<br/>우리 에이전트"]우리 파이썬 클라이언트로 n8n에 붙어 보면 이렇게 보입니다.
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명 일정입니다. …
한 바퀴가 닫혔습니다. Claude가 n8n을 부르고, n8n이 우리 FastAPI를 부르고, 그 안에서 6주차 에이전트가 돕니다. 세 층이 전부 MCP와 HTTP라는 같은 프로토콜로 이어져 있고, 어느 층도 다른 층의 내부를 모릅니다.
MCP Server Trigger는 typeVersion 2.1부터 streamable HTTP입니다. 1.x는 SSE라
/mcp/<path>/sse로 붙어야 합니다. 판이 올라가면 확인이 필요합니다.
7-6. 얻는 것과 잃는 것
n8n이 코드를 대체하지 않습니다. 무엇을 주고 무엇을 가져가는지가 분명합니다.
| 얻는 것 | 잃는 것 |
|---|---|
| 연결 (Slack·Gmail·시트·cron 수백 종) | 버전 관리와 코드 리뷰 |
| 속도 (오늘 만들어 오늘 돌린다) | 테스트 (pytest 19개 같은 것) |
| 화면으로 보이는 흐름 | 세밀한 제어 (하네스·게이트·재계획) |
| 실행 이력이 공짜 | 비용 통제 (예산 게이트를 우리가 못 짠다) |
언제 코드로 돌아와야 하는가. 판단 기준은 6주차에 배운 것과 같습니다. 실패했을 때 무엇을 할지 정교하게 정해야 하면, 비용 상한을 요청 단위로 지켜야 하면, 같은 입력에 같은 결과를 보장해야 하면 코드입니다. 그 외에는 n8n이 빠릅니다.
그리고 라이선스를 한 줄 짚고 갑니다. n8n은 OSI 오픈소스가 아니라 Sustainable Use License(fair-code) 입니다. 개인·사내 사용과 포트폴리오는 자유지만, n8n 자체를 호스팅해 되파는 것은 금지되어 있습니다. 개인 프로젝트에 쓰는 데는 문제가 없지만 “오픈소스”라고 뭉뚱그리지는 않습니다.
8. 뒷문: 키와 지갑
8-1. 키를 쥐는 세 가지 배치
지금까지 키는 .env에 있었습니다. 배포하는 순간 그 자리가 달라집니다.
| 배치 | 키를 쥐는 쪽 | 비용 | 무너지는 지점 |
|---|---|---|---|
| 운영자 키 | 서버의 환경변수·시크릿 | 운영자 | 데모 URL 하나로 지갑이 열린다 |
| 사용자 키 (BYOK) | 사용자가 입력, 런타임 주입 | 사용자 | 키를 어디 두나. 로그·에러에 새지 않게 |
| 가상키 | 게이트웨이가 진짜 키를 쥔다 | 운영자 + 사람별 상한 | 게이트웨이가 단일 장애점 |
배치를 바꿔 가며 요청을 보내 보세요. 열쇠가 어디 있고 각 구간에 무엇이 실려 가는지가 배치마다 다릅니다. 가상키 배치에서는 한도 소진을 켜고 다시 보내면 요청이 모델에 닿지 못합니다.
BYOK는 구조가 간단합니다. .env에서 오던 키가 요청에서 올 뿐이고, LiteLLM에
api_key 인자로 넘기면 됩니다. 호출 코드는 그대로입니다. 다만 키를
로그에 남기지 않는 것과 에러 메시지에 실어 보내지 않는 것을 지켜야
합니다. 설정 화면은 UI 이야기라 9주차에서 다룹니다.
8-2. 게이트웨이: LiteLLM이 서버로 선다
5주차에 배운 litellm이 이번에는 라이브러리가 아니라 서버입니다. compose 서비스 하나가 늘고, 앱은 진짜 키를 모르게 됩니다.
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 # 이 키로만 가상키를 발급한다
여기서 키가 셋이 됩니다. 이름이 다 비슷해서 헷갈리기 쉬우니 층을 갈라
둡니다. LITELLM_MASTER_KEY는 어느 AI 회사에도 등록돼 있지 않은, 우리가
지어낸 값입니다.
| 진짜 프로바이더 키 | 마스터 키 | 가상키 | |
|---|---|---|---|
| 누가 만드나 | Google·OpenAI·Anthropic 콘솔 | 우리가 지어낸다 (sk-로 시작만 하면 된다) | 게이트웨이가 발급 |
| 무엇을 여나 | 모델 벤더의 문 | 게이트웨이의 관리자 문 | 게이트웨이의 사용자 문 |
| 어디 사나 | 게이트웨이의 .env | 게이트웨이의 .env | 앱·사람에게 나눠준다 |
| 할 수 있는 일 | 모델 호출 (돈이 나간다) | 키 발급·폐기, 예산·모델 제한, 장부 조회 | 허락된 모델만, 상한 안에서 호출 |
| 유출되면 | 벤더 콘솔에서 폐기 + 요금 폭탄 | 무제한 발급 + 전체 사용량 열람 | 그 키 하나만 폐기 |
한 줄로 하면, 마스터 키는 게이트웨이의 root 비밀번호입니다. 모델을 부르라고 있는 것이 아니라 누가 모델을 부를 수 있는지를 정하라고 있습니다. 직접 두드려 보면 선이 분명합니다.
# ① 마스터 키로 가상키 발급
curl -s -X POST localhost:4000/key/generate \
-H 'Authorization: Bearer sk-week08-master' \
-H 'content-type: application/json' \
-d '{"models":["travel-demo"],"max_budget":1}'
{"key":"sk-X2YZqszic5CYcfVl5IbXlA", …}
# ② 방금 받은 가상키로 또 발급을 시도하면
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.
가상키는 모델을 부를 수는 있어도 키를 찍어낼 수는 없습니다. 그 권한이 마스터 키에만 있다는 것이 이 구조의 전부입니다. 저장소에서 셋이 앉는 자리는 이렇습니다.
# gateway/.env — 게이트웨이 컨테이너에만 간다
GEMINI_API_KEY=AIza… # 진짜. 돈이 여기서 나간다
LITELLM_MASTER_KEY=sk-week08-master # 우리가 지은 값. 벤더와 무관하다
# .env — 앱(api·mcp)에 가는 것 전부
GATEWAY_URL=http://litellm-proxy:4000
GATEWAY_KEY=sk-…
# core/llm.py — 앱이 쥐는 것은 가상키뿐이다
kwargs["api_base"] = os.environ["GATEWAY_URL"]
kwargs["api_key"] = os.environ["GATEWAY_KEY"] # sk-X2YZ… (가상키)
주의할 것 둘입니다.
- 마스터 키는 앱에도 수강생에게도 주지 않습니다. 배포할 때는
sk-week08-master처럼 짐작 가능한 값이 아니라 긴 난수로 둡니다. - 마스터 키로도
/chat/completions를 부를 수는 있습니다. 관리자니까요. 다만 그러면 상한도 구분도 사라지므로 그렇게 쓰지 않습니다.
마스터 키로 가상키를 발급하고, 상한을 아주 낮게 걸고, 소진시켜 봅니다.
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! Key=student-demo Current cost: 2.6e-05, Max budget: 2e-05
호출 4: 429 Budget has been exceeded! …
호출 5: 429 Budget has been exceeded! …
여기서 얻는 것이 셋입니다.
- 앱에 키를 주지 않는다. 앱은 가상키만 압니다. 유출돼도 그 키만 폐기하면 됩니다.
- 사람마다 다른 상한을 건다. 앱을 고치지 않고 발급 시점에 정합니다.
- 모델 접근을 좁힌다.
models: ["travel-demo"]로 그 키가 부를 수 있는 모델을 제한합니다.
앱 쪽 변경은 이게 전부입니다. 주소와 키만 바뀌고 호출 코드는 그대로입니다.
if config.gateway(): # .env의 GATEWAY_URL
kwargs["api_base"] = config.gateway()
kwargs["api_key"] = os.environ.get("GATEWAY_KEY", "")
기본은 꺼져 있습니다. .env의 GATEWAY_*가 비어 있으면 각본 대역이
답합니다. 이 랩의 앱에는 프로바이더로 가는 길이 아예 없으므로, 게이트웨이가
없으면 진짜 호출도 없습니다. 둘을 채우면 같은 코드가 게이트웨이를
지나갑니다.
# .env — 필요한 것은 둘뿐이다
GATEWAY_URL=http://litellm-proxy:4000 # compose 서비스 이름. localhost가 아니다
GATEWAY_KEY=sk-… # 가상키. 발급은 다음 절에서
앱이 아는 것은 주소와 키 문자열 하나뿐입니다. 그 키가 어떤 모델을 부를 수
있고 얼마까지 쓸 수 있는지는 앱이 모릅니다. 게이트웨이가 압니다. 상한과 허용
모델은 .env가 아니라 발급할 때 화면에서 정하기 때문입니다.
말로만 하면 믿기 어려우니 앱 컨테이너 안을 들여다봅니다.
docker compose exec api python -c "
import os
for v in ['GEMINI_API_KEY','LITELLM_MASTER_KEY','GATEWAY_URL','GATEWAY_KEY']:
print(v, '있음' if os.environ.get(v) else '없음')"
GEMINI_API_KEY 없음
LITELLM_MASTER_KEY 없음
GATEWAY_URL 있음
GATEWAY_KEY 있음
그리고 이 컨테이너가 진짜 Gemini의 답을 받아 옵니다.
mode: live | model: openai/travel
거친 도구: ['calc_budget', 'search_places', 'estimate_travel_time']
답: 오사카 2박 3일 2명 여행을 위한 추천 일정을 제안해 드립니다. …
진짜 키가 하나도 없는 컨테이너가 진짜 모델을 썼습니다. 키는 게이트웨이 컨테이너에만 있습니다.
docker-compose.yml도 그렇게 되어 있습니다. .env를 통째로 물리지 않고
서비스마다 필요한 것만 골라 줍니다.
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 파일로 나타납니다.
부를 모델의 이름만 앱이 고릅니다. 비워 두면 travel입니다.
GATEWAY_MODEL=travel-demo # 선택. 모의 응답으로 돌려 보고 싶을 때만
GATEWAY_KEY를 비워 두면 시작은 하지만 첫 호출에서 막힙니다. 비어 있는 키
자리에 환경의 프로바이더 키가 대신 실려 나가고, 게이트웨이는 모르는 키라며
거절하기 때문입니다. 그래서 코어가 아예 앞에서 막고 할 일을 알려줍니다.
{"error": "UpstreamError",
"detail": "GATEWAY_URL은 있는데 GATEWAY_KEY가 비어 있다. 관리자 화면(:4000/ui/)에서 …"}
켜고 나서 /config를 보면 모델 이름이 바뀌어 있습니다.
{"mode": "live", "model": "openai/travel-demo"}
gemini/…가 아니라 게이트웨이 뒤의 별명입니다. 앱이 어느 회사 모델을
쓰는지 모른다는 사실이 이 한 줄에 드러납니다. 바꾸는 것은 게이트웨이 설정
파일이고, 앱은 다시 배포하지 않습니다.
8-3. 관리자 화면: 키와 장부를 눈으로
여기까지는 전부 curl이었습니다. 그런데 게이트웨이에는 관리자 화면이 이미
들어 있습니다. 우리가 만들 것이 아니라 제품에 딸려 온 것입니다.
http://localhost:4000/ui/
아이디 admin · 비밀번호는 LITELLM_MASTER_KEY (기본 sk-week08-master)

가상키를 발급하고 앱에 물리는 순서는 이렇습니다.
docker compose up -d. 게이트웨이가 먼저 떠야 합니다. 이 시점에 앱은 아직 프로바이더를 직접 부릅니다.:4000/ui/에서 + Create New Key. 별명·상한·허용 모델을 정합니다. Organization 칸에서week08을 고릅니다. 키 문자열은 만든 직후 한 번만 보여주므로 그때 복사합니다..env의GATEWAY_URL과GATEWAY_KEY둘을 채웁니다. 상한과 허용 모델은 2단계에서 이미 정했으므로 여기 적을 것이 없습니다.docker compose up -d --force-recreate api mcp. 앱만 다시 만듭니다. 1초쯤 걸립니다.
닭과 달걀처럼 보이지만 아닙니다. 가상키는 게이트웨이의 상태입니다. 게이트웨이의 장부에 “이 키는 이 모델을, 이 상한까지”라고 적힌 한 줄이고, 앱에는 그것이 설정으로 들어갑니다. 그래서 게이트웨이가 먼저 있고, 발급이 그다음이고, 앱의 재시작이 마지막입니다. 실제 배포도 이 순서입니다. 운영자가 키를 한 번 발급하고, 그것을 시크릿에 넣고, 앱을 배포합니다.
키를 바꿀 때도 같은 네 단계입니다. 새로 발급하고, .env를 고치고, 앱만
다시 만듭니다. 몇 가지를 짚어 둡니다.
-
docker compose down은 필요 없습니다. 앱 컨테이너 둘만 다시 만들면 됩니다. 게이트웨이·DB·n8n·화면은 그대로 돕니다. -
restart로는 안 됩니다. 환경변수는 컨테이너를 만들 때 굳습니다..env의 모델 이름을 바꿔 놓고 둘을 비교하면 이렇습니다.docker compose restart api → model: openai/travel (옛 값) docker compose up -d --force-recreate api → model: openai/travel-demo (새 값) -
순서가 중요합니다. 새 키 발급 → 앱에 반영 → 그다음에 옛 키 폐기. 반대로 하면 그 사이의 요청이 전부 실패합니다.
-
다시 만드는 1초 남짓 동안
api·mcp는 요청을 받지 못합니다. 짧지만 중단은 중단입니다.
실제 서비스라면 키를 바꾸느라 서비스가 끊기면 곤란합니다. 방법이 몇 가지 있습니다.
- 시크릿을 파일로 마운트하고 호출할 때마다 읽습니다. 도커와 쿠버네티스의 시크릿이 환경변수가 아니라 파일인 이유가 이것입니다
- 시크릿 매니저에서 런타임에 조회하고 잠깐 캐시합니다 (Vault, AWS Secrets Manager 같은 것들)
- 인스턴스를 하나씩 교체합니다. 앞의 것이 살아 있는 동안 뒤의 것이 올라옵니다. 우리 랩은 한 대씩이라 잠깐 끊깁니다
- 새 키와 옛 키를 겹쳐 두고 갈아탄 뒤 옛 키를 지웁니다
이 랩은 “설정은 배포 시점에 들어간다”는 가장 단순한 그림을 그대로 둡니다. 무중단 교체는 12주차 배포에서 다룹니다.
.env를 고치기 전에 한 번만 시험해 보고 싶다면 재시작 없이 이렇게도 됩니다.
docker compose exec \
-e GATEWAY_URL=http://litellm-proxy:4000 \
-e GATEWAY_KEY=sk-… \
-e GATEWAY_MODEL=travel \
api python -c "from core import service; print(service.plan('오사카 2박 3일 2명').answer[:60])"
화면에서 바로 되는 일들입니다.
- 가상키 발급:
+ Create New Key로 별명·상한·허용 모델을 정해 만듭니다.curl로 하던 일과 같은 것이고, 만든 뒤 키 문자열을 한 번만 보여줍니다. - 사용액 보기: 키마다
$0.00 of $5처럼 상한 대비 얼마를 썼는지 막대로 보입니다. 넘긴 키는 붉게 표시됩니다. - 허용 모델 확인:
batch-job은travel까지,student-01은travel-demo만 부를 수 있습니다. 8장 2절의 모델 허용목록이 이 열입니다. - 그리고 왼쪽에 Usage·Logs·Budgets·Teams가 있습니다. 5주차에 비용 콜백으로 손수 찍던 장부가 여기서는 화면입니다.
Organization 칸을 건드리지 않으면 키가 만들어지지 않습니다. 화면이 빈 문자열을 보내고 게이트웨이가 “그런 조직이 없다”며 500으로 거절합니다. LiteLLM v1.100에서 확인한 것입니다. 랩에서는
gateway-init서비스가 기동할 때week08조직을 하나 만들어 두므로, 목록에서 그것을 고르면 됩니다. 남의 제품에도 이런 자리가 있다는 것을 한 번 보고 가는 셈입니다.
화면은 영어입니다. 한국어는 없습니다. 열이 몇 개 안 되니 한 번만 짚고 가겠습니다.
| 열 | 뜻 |
|---|---|
| Key | 별명과 키 앞자리. 키 전체는 발급 직후 한 번만 보입니다 |
| Spend / Budget | 이 키가 지금까지 쓴 금액과 상한 |
| Budget Reset | 상한을 언제 되돌리나 (Never면 한 번 쓰면 끝) |
| Models | 이 키로 부를 수 있는 모델 |
| Team · User | 키를 팀이나 사람에 묶었을 때 채워집니다 |
이 화면이 열려 있다는 것
마스터 키가 이 화면의 비밀번호입니다. 마스터 키를 쥔 쪽은 키를 찍어낼 수 있고 남의 사용액을 볼 수 있습니다. 앱에 주지 않는 이유가 이것입니다.
그런데 우리 랩의 마스터 키는 sk-week08-master입니다. 교안에 적혀 있으니
비밀이 아닙니다. 그래서 게이트웨이의 포트를 이 기계에만 열어 두었습니다.
ports:
- "127.0.0.1:4000:4000" # 같은 망의 다른 기계에서는 보이지 않는다
0.0.0.0:4000이었다면 같은 카페 와이파이에 있는 사람이 관리자 화면에 들어와
키를 찍어낼 수 있습니다. 컨테이너끼리는 compose 네트워크로 통하므로 앱은
영향을 받지 않습니다.
배포할 때 더 해야 할 것들입니다.
- 마스터 키를 긴 난수로 바꿉니다.
.env에 두고 절대 커밋하지 않습니다. - 화면 로그인을 마스터 키와 분리합니다 (
UI_USERNAME·UI_PASSWORD), 또는 SSO를 붙입니다. - 공개 주소에 그냥 두지 않습니다. 리버스 프록시 뒤에 놓고 IP를 제한합니다.
6주차에 “프롬프트는 부탁이고 게이트는 물리 법칙”이라고 했습니다. 여기서는 포트 바인딩이 그 물리 법칙입니다.
8-4. 소진되면 거절인가, 강등인가
같은 “예산 초과”인데 두 곳에서 다르게 처리됩니다.
| 6주차 budget guard | 게이트웨이 | |
|---|---|---|
| 어디 | 루프 안 | 문 앞 |
| 언제 | 이미 몇 번 부른 뒤 | 모델에 닿기 전 |
| 무엇을 | 멈추고 답으로 알린다 | 429로 거절한다 |
flowchart LR
Q(["요청"]) --> GW{"게이트웨이<br/>가상키 상한"}
GW -->|"초과"| X["429<br/>모델에 닿지 못한다"]
GW -->|"통과"| LOOP["루프 시작"]
LOOP --> BG{"budget guard<br/>요청 단위 상한"}
BG -->|"초과"| Y["200 + stopped_by: budget<br/>중간까지의 상황을 답으로"]
BG -->|"통과"| Z["최종 답"]우리 랩에서 둘 다 볼 수 있습니다.
curl -s -X POST "localhost:8000/plan?simulate=budget" \
-H 'content-type: application/json' -d '{"question":"오사카 2박"}'
{"stopped_by":"budget","answer":"[중단] 비용 상한 초과: 누적 $0.5000 ≥ 중단 임계 $0.20",
"spent_usd":0.5}
200입니다. 사용자는 중간까지의 상황을 답으로 받습니다. 반면 게이트웨이는 429로 문을 닫습니다.
어느 쪽이 옳은가는 제품이 정합니다. 무료 데모라면 거절이 맞고, 유료 서비스라면 5주차에서 배운 폴백으로 싼 모델에 내려앉히는 편이 나을 수 있습니다. 엔지니어링 결정과 사업 결정이 같은 코드 한 줄에서 만나는 자리입니다.
9. 재현할 때 유의할 점
- 포트를 겹치지 않게 합니다. 이 저장소는 8000·8010·5678·4000을 씁니다.
7주차 저장소들도 8000·8501을 쓰므로 한 번에 하나만 띄웁니다. 넘어갈
때는
docker compose down으로 내리고 갑니다. - mcp는 1.x에 고정입니다. 2.x에서
FastMCP가MCPServer로 개명돼 6주차 예제와 import가 달라집니다.requirements.txt의 핀을 풀지 않습니다. - n8n 워크플로는 판을 탑니다. 이미지 태그를
2.38.5로 고정해 두었습니다. 올리면 노드 파라미터가 바뀌어 불러오기가 깨질 수 있고, 특히 MCP Server Trigger는 1.x(SSE)와 2.x(streamable HTTP)의 주소가 다릅니다. - 워크플로를 다시 불러오면 덮어씁니다. JSON에
id를 박아 두었기 때문입니다. 빼면 같은 워크플로가 여러 개로 늘어납니다. - 불러온 뒤에 발행하고 재시작합니다. n8n 2.x는 초안과 발행판이 따로라
publish:workflow까지 해야 트리거가 삽니다. 옛 판의update:workflow --active=true가 있던 자리입니다. 발행 상태는docker compose restart n8n후에 반영됩니다. - 각본 대역에는 일부러 지연이 있습니다.
OFFLINE_LATENCY_MS(기본 400)를 0으로 두면 스트리밍이 흐르는 것도, 동시 요청의 차이도 눈에 보이지 않습니다. - 게이트웨이 장부는 볼륨에 남습니다. 가상키를 지우고 처음부터 하려면
docker compose down -v가 필요합니다.
10. 이 세션이 남기는 것
경계 (3장)
- 문을 달기 전에 할 일은 내 기능을 함수 하나로 말하는 것이다. 그게 8할이다.
- 코어는 문을 모른다. import 방향이 그 증거다.
- 스트리밍과 동기 응답이 다른 코드를 돌면 둘 중 하나는 거짓말을 시작한다.
- 스키마 하나가 요청 검증·도구 스키마·MCP 명세·OpenAPI 네 곳에서 쓰인다.
HTTP 문 (4장)
- 계약이 있으면 핸들러는 잘못된 값을 한 번도 보지 않는다. 방어 코드가 필요 없는 이유다.
- 상류의 장애는 500이 아니라 502다. 500은 우리가 깨졌다는 뜻이다.
- 그래프를 얹으면 상태가 생긴다. 상태는 프로세스가 아니라 DB에 산다.
async def안의 동기 호출 한 줄이 동시 5건을 5배 느리게 만든다.- 스트리밍은 총 시간을 줄이지 않는다. 첫 글자까지의 시간을 줄인다.
- 스트림이 시작된 뒤의 실패는 상태 코드가 아니라 이벤트로 알린다.
MCP 문 (5장)
- 6주차의
@mcp.tool()에 붙이는 것만 달라졌다. 함수 둘에서 에이전트 하나로 - 에이전트를 통째로 낼지 도구를 낱개로 낼지는 통제·유연함·비용의 문제다.
- stdio냐 HTTP냐는 붙는 쪽이 정한다.
붙이기 (6장)
- Inspector가 먼저다. 서버가 잘못된 것과 안 붙는 것은 다른 문제다.
- 내 AI가 내 도구를 부르는 순간이 7주 작업의 결과를 가장 잘 보여준다.
- 로컬에 붙이는 것과 세상에 내어주는 것은 다르다.
자동화 문 (7장)
- 이벤트가 우리를 부른다. 우리 서비스가 남의 업무 흐름의 부품이 된다.
- 손으로 짠 ReAct가 남의 도구에서는 항목 하나다. 그래서 바닥을 먼저 본다.
- Claude → n8n → 우리 API → 6주차 에이전트. 한 바퀴가 닫힌다.
- 얻는 것은 연결과 속도, 잃는 것은 테스트·버전 관리·비용 통제다.
뒷문 (8장)
- 앱은 진짜 키를 몰라도 모델을 쓴다.
- 한도는 코드가 아니라 게이트웨이가 지킨다. 사람마다 다르게
- 예산 초과를 답으로 알릴지 문 앞에서 거절할지는 제품이 정한다.
한 장으로
flowchart TB
P(("사람")) --> A["HTTP :8000"]
AI(("다른 AI")) --> M["MCP :8010"]
E(["이벤트"]) --> N["n8n :5678"]
N --> A
N --> M
A --> C["core/service.py<br/>plan() · plan_events()"]
M --> C
C --> H["6주차 루프 · 하네스 · 도구"]
H --> G["게이트웨이 :4000<br/>가상키 · 상한"]
G --> L(("모델 제공자"))
U(["9주차 UI"]) -.-> A그리고 다음
9주차에는 이 문들 앞에 화면을 답니다. Streamlit·Gradio·Next.js 중에서
고르고, /docs만으로도 데모가 성립한다는 것을 이미 봤으니 Swagger UI도
선택지입니다. 오늘 연 MCP 문 덕분에 하나가 더 늘었습니다. ChatGPT 플러그인은
MCP Apps UI 표준을 구현해서, MCP 서버가 UI 컴포넌트를 함께 내보낼 수
있습니다. 대화 안에서 도는 화면이라는 뜻입니다.
무엇을 고르든 API는 한 줄도 바뀌지 않습니다. 3주차부터 헤드리스로 만들어 온 이유가 그것입니다.