프런트엔드 · FastAPI · Celery 워커 · 외부 API · 오토힐링 · Docker
— 전체 구조, 예시 폴더 구조, 빌드·실행 구성
멀티에이전트 + LLM + 외부 API가 섞인 서비스를 "요청 받는 곳"과 "일하는 곳"으로 나눠 설계한다.
LLM 호출을 HTTP 요청 안에서 기다리면 무엇이 깨지는지 말할 수 있다.
프런트 → API → 큐 → 워커 → LLM/외부 API, 그리고 결과가 돌아오는 길을 그릴 수 있다.
backend/, agents/, shared/, docker/가 각각 무엇을 담고 어떤 이미지가 되는지 안다.
재시도·폴백·자동 재시작을 어느 계층에 넣어야 하는지 구분한다.
멀티에이전트 한 번 = LLM 호출 여러 번 + 외부 API 여러 번 → 수십 초 ~ 수 분.
# ❌ 이렇게 만들면 안 됩니다 @router.post("/analyze") async def analyze(body: Req): result = await graph.ainvoke(body.dict()) # ↑ Supervisor → 진단 → 복구 → 검증 # LLM 6번 + 외부 API 4번 … 90초 return result
사용자는 90초 동안 로딩 스피너만 봅니다. 그 사이에 무슨 일이 생길까요?
홀 직원이 직접 요리까지 하면 손님 응대가 멈춥니다. 그래서 주문 접수와 조리를 나눕니다.
| 식당 | 우리 시스템 | 하는 일 |
|---|---|---|
| 손님 | 프런트엔드 | 웹/앱 화면. 주문하고, 진행 상황을 봄 |
| 홀 직원 (카운터) | FastAPI API 서버 | 주문 확인(인증·입력 검증) 후 주문표를 걸고 바로 진동벨을 건넴 |
| 주문표 | Job (DB 한 행) | 무엇을 요청했고 지금 어떤 상태인지 기록 |
| 주문 레일 | 큐 (Redis) | 주방이 처리할 순서대로 주문표가 대기하는 곳 |
| 주방 / 셰프 팀 | 워커 / 멀티에이전트 | 주문표를 하나 꺼내 Supervisor·전문 에이전트들이 협업해 처리 |
| 식자재 납품업체 | LLM · 외부 API | 가끔 늦거나 품절 → 재시도하거나 다른 업체로 (= 오토힐링) |
| 진동벨 | job_id + SSE | "지금 굽는 중", "완성!"을 손님에게 알려줌 |
| 구성요소 | 책임 (해야 할 일) | 하면 안 되는 일 | 기술 예시 |
|---|---|---|---|
| 프런트엔드 | 요청 보내기, job_id로 진행 상황 구독, 결과 표시, 에이전트 사고 과정 가시화 | LLM API 키 보관·직접 호출 | React/Next.js, Streamlit, Flutter |
| API 서버 | 인증·권한, 입력 검증, Job 생성, 큐 투입, 상태 조회, SSE 중계 | LLM·에이전트를 요청 안에서 실행 | FastAPI, Pydantic, SQLAlchemy |
| 큐 / 브로커 | 작업을 안전하게 보관하고 워커에게 순서대로 전달 | 결과를 영구 저장 (그건 DB) | Redis (Celery 브로커) |
| 워커 | Job 꺼내서 LangGraph 실행, 진행 이벤트 발행, 결과 저장, 실패 시 재시도 | HTTP 요청을 직접 받음 | Celery (+ Flower 모니터링) |
| DB | Job 상태·결과·감사 로그의 "단일 진실 공급원" | — | PostgreSQL, Supabase |
| LLM·외부 API | 워커 안의 통합 계층(integrations)에서만 호출, 타임아웃·재시도·폴백 적용 | 에이전트 코드 곳곳에서 날것으로 호출 | LiteLLM, httpx, tenacity |
핵심: API는 ②에서 즉시 응답하고 빠진다. 무거운 일은 ④~⑧, 워커가 한다.
FE① 사용자가 "분석 요청" 클릭 → POST /api/v1/jobs
API② 검증 후 DB에 Job 저장 status=queued
API③ Celery로 send_task("agents.run_agent_job", [job_id]) → 202 + job_id 응답
FE④ GET /jobs/{id}/events (SSE) 구독 시작
Worker⑤ Celery 워커가 태스크 수신 → status=running
Worker⑥ LangGraph 실행. 노드가 끝날 때마다 {"type":"step","node":"diagnosis"} 발행
Ext⑦ 외부 API 실패 → 재시도 / 폴백 (오토힐링)
Worker⑧ 결과 DB 저장 status=succeeded + done 이벤트
FE⑨ done 수신 → GET /jobs/{id}로 최종 결과 표시
GET /jobs/{id}로 언제든 현재 상태·결과를 다시 볼 수 있어요.DB의 jobs.status 한 컬럼이 화면·재시도·오토힐링·감사 로그의 기준이 됩니다.
※ waiting_approval: 서비스 재시작처럼 위험한 복구는 사람 승인 후 진행 (가드레일·Human-in-the-loop). 팀 주제에 필요 없으면 생략 가능.
| 방식 | 동작 | 장점 | 단점 |
|---|---|---|---|
| 폴링 | 프런트가 2초마다 GET /jobs/{id} | 가장 쉬움. 일단 이것부터 | 지연·불필요한 요청 |
| SSE ⭐ 권장 | 서버 → 브라우저 한 방향 스트림. 이벤트가 생길 때마다 push | HTTP 그대로, 구현 간단, 자동 재연결 | 단방향 (요청은 별도 POST) |
| WebSocket | 양방향 연결 유지 | 채팅처럼 주고받기가 잦을 때 | 연결 관리·인증·배포 설정이 더 복잡 |
{"type":"token","text":"..."} 이벤트를 발행 → SSE로 전달.| Celery 용어 | 뜻 (식당 비유) |
|---|---|
| Broker | 태스크 메시지가 대기하는 곳 = 주문 레일. 우리는 Redis |
| Task | 워커가 실행할 함수 = 레시피. @app.task로 등록 |
| Worker | 태스크를 꺼내 실행하는 프로세스 = 주방. 컨테이너 여러 개로 확장 |
| Queue | 태스크를 나누는 줄. 예: agents, monitor |
| Beat | 정해진 시각에 태스크를 넣는 스케줄러 = 알람 |
| Flower | 워커·태스크 상태를 보는 웹 대시보드 (시연·모니터링용) |
왜 Celery? 파이썬 백그라운드 작업의 사실상 표준 → 자료·예제가 가장 많고, 재시도·시간 제한·스케줄·모니터링이 모두 갖춰져 있음. (가벼운 대안: arq, Taskiq / 데모 전용: FastAPI BackgroundTasks)
team-project/ ├── frontend/ # → {팀}-fe 이미지 (웹/앱) ├── backend/ # → {팀}-be 이미지 (FastAPI) ├── agents/ # → {팀}-agents 이미지 │ # (Celery 워커 + LangGraph) ├── shared/ # be·agents 공용 코드 ├── tests/ ├── docs/ # 산출물(설계서·결과서) ├── docker/ # 빌드·실행 스크립트 (뒤에서) ├── .env # 실제 값 — 커밋 금지 ├── .env.example # 키 이름만 └── .gitignore
be는 가볍고 빨라야 하고(요청 응답), agents는 무겁고 오래 걸립니다(LangGraph·LLM SDK). 이미지를 나누면 따로 빌드·배포·확장할 수 있고, 에이전트를 고쳐도 API 서버는 그대로 둘 수 있습니다.
양쪽이 똑같이 알아야 하는 것만: 설정(Settings), DB 연결, jobs 테이블 모델과 상태 상수. 빌드할 때 두 이미지에 모두 복사됩니다.
backend/ # {팀}-be ├── app/ │ ├── main.py # 앱 생성·라우터 등록 │ ├── core/ │ │ ├── security.py # JWT 검증·권한 │ │ └── celery_client.py # 태스크 "보내기" 전용 │ ├── api/v1/ │ │ ├── jobs.py # POST/GET /jobs, SSE │ │ ├── approvals.py # 위험 작업 승인 │ │ └── health.py # /health │ ├── schemas/job.py # Pydantic 요청·응답 │ └── services/job_service.py └── requirements.txt # fastapi, celery, redis shared/ # 두 이미지 공용 ├── config.py # Settings(환경변수) ├── db.py # 엔진·세션 └── models.py # jobs 테이블·상태 상수
agents/ # {팀}-agents ├── worker/ │ ├── celery_app.py # Celery 앱·설정 │ ├── tasks.py # run_agent_job 태스크 │ ├── job_store.py # jobs 상태 변경 │ └── events.py # 진행 이벤트 발행 ├── graph/ # LangGraph 멀티에이전트 │ ├── build.py # build_graph() │ ├── state.py # 공유 State │ ├── supervisor.py │ ├── nodes/ # 팀 주제에 맞게 │ │ └── diagnosis.py, recovery.py … │ └── prompts/ ├── integrations/ # 바깥 세상과의 경계 │ ├── base.py # 타임아웃·재시도 공통 │ ├── llm.py # LLM 게이트웨이 │ └── public_api.py ├── healing/ # 폴백·정책·주기 점검 └── requirements.txt # celery, langgraph, httpx
be는 send_task("agents.run_agent_job", ...)처럼 문자열 이름으로 보냅니다. 그래서 be 이미지에는 LangGraph·LLM 라이브러리가 없어도 됩니다.
큰 입력(문서·대화 내용)은 DB에 저장하고 태스크 인자로는 job_id만. 재시도·감사 추적이 쉬워지고 브로커가 가벼워집니다.
에이전트 노드에서 FastAPI·Request를 import하면 안 됩니다. 에이전트는 HTTP를 몰라야 단독으로 테스트할 수 있습니다.
from fastapi import APIRouter, Depends, status from app.core.celery_client import celery_client from app.core.security import current_user from app.schemas.job import JobCreate, JobAccepted, JobRead from app.services import job_service from shared.db import get_db router = APIRouter(prefix="/jobs", tags=["jobs"]) @router.post("", status_code=status.HTTP_202_ACCEPTED, response_model=JobAccepted) async def create_job(body: JobCreate, db=Depends(get_db), user=Depends(current_user)): job = await job_service.create(db, user.id, body) # ① DB: queued celery_client.send_task("agents.run_agent_job", # ② 이름으로 전송 args=[job.id], queue="agents") return JobAccepted(job_id=job.id, status="queued") # ③ 즉시 응답 @router.get("/{job_id}", response_model=JobRead) async def get_job(job_id: str, db=Depends(get_db)): return await job_service.get(db, job_id) # 상태·결과 조회
from celery import Celery from shared.config import settings # 보내기 전용 클라이언트 # (태스크 함수는 여기 없음!) celery_client = Celery( "be", broker=settings.redis_url)
· send_task는 브로커에 메시지만 넣고 즉시 돌아옵니다 (수 ms).
· 태스크 이름 "agents.run_agent_job"은 워커 쪽 @app.task(name=...)와 정확히 같아야 합니다.
· 결과는 Celery가 아니라 DB의 jobs 테이블에서 조회합니다.
from agents.worker.celery_app import app from agents.worker import job_store as js from agents.worker.events import publish from agents.graph.build import build_graph from agents.integrations.base import TransientError graph = build_graph() # 워커 시작 시 한 번만 조립 @app.task(name="agents.run_agent_job", bind=True, max_retries=3) def run_agent_job(self, job_id: str): if not js.claim(job_id): # queued→running 선점 실패면 return # 이미 처리 중 → 중복 실행 방지 try: state = {} for upd in graph.stream(js.get_input(job_id), stream_mode="updates"): node, data = next(iter(upd.items())) publish(job_id, {"type": "step", "node": node}) state.update(data or {}) js.succeed(job_id, state) publish(job_id, {"type": "done"}) except TransientError as e: # 잠깐의 장애 → 다시 if self.request.retries < self.max_retries: js.mark_retrying(job_id) raise self.retry(exc=e, countdown=10 * (self.request.retries + 1)) js.fail(job_id, e); raise # 재시도 소진 except Exception as e: # 복구 불가 → 실패 기록 js.fail(job_id, e); raise # status=failed + failed 이벤트
from celery import Celery from shared.config import settings app = Celery("agents", broker=settings.redis_url, include=["agents.worker.tasks"]) app.conf.update( task_default_queue="agents", task_acks_late=True, # 끝난 뒤 완료 처리 task_reject_on_worker_lost=True, # 워커가 # 죽으면 다른 워커가 다시 받음 worker_prefetch_multiplier=1, # 하나씩 task_soft_time_limit=540, # 9분: 예외로 경고 task_time_limit=600, # 10분: 강제 종료 task_ignore_result=True, # 결과는 DB에 )
import json, redis r = redis.Redis.from_url(settings.redis_url) def publish(job_id, ev): r.publish(f"job:{job_id}", json.dumps(ev, ensure_ascii=False))
from sqlalchemy import update from shared.db import SessionLocal from shared.models import Job def claim(job_id: str) -> bool: """queued/retrying 인 Job만 running으로. UPDATE 한 번이라 두 워커가 동시에 와도 한 명만 성공(rowcount == 1).""" with SessionLocal() as s, s.begin(): res = s.execute( update(Job) .where(Job.id == job_id, Job.status.in_(["queued", "retrying"])) .values(status="running")) return res.rowcount == 1
acks_late를 켜면 같은 태스크가 두 번 올 수 있습니다 → 이 선점 로직이 "복구가 두 번 실행"을 막아 줍니다.
워커 쪽 코드(graph.stream, httpx.Client, 동기 DB 세션)는 동기로 작성하는 것이 가장 단순합니다. async 코드를 꼭 써야 하면 태스크 안에서 asyncio.run(...)으로 감쌉니다.
docker run -p 6379:6379 redis:7-alpine uvicorn app.main:app --reload # backend/ celery -A agents.worker.celery_app worker \ -Q agents -l INFO # 루트에서
Windows에서는 워커에 --pool=solo를 붙이세요.
localhost:5555)로 워커 수·대기 태스크·실패·재시도를 실시간으로 보여주면 오토힐링 시연에 좋습니다.import json from fastapi.responses import StreamingResponse @router.get("/{job_id}/events") async def job_events(job_id: str, request: Request): async def stream(): ps = request.app.state.redis.pubsub() await ps.subscribe(f"job:{job_id}") try: async for msg in ps.listen(): if msg["type"] != "message": continue yield f"data: {msg['data']}\n\n" # SSE 형식 if json.loads(msg["data"])["type"] in ("done", "failed"): break finally: await ps.unsubscribe() await ps.aclose() return StreamingResponse(stream(), media_type="text/event-stream")
const res = await fetch("/api/v1/jobs", { method: "POST", headers, body }); const { job_id } = await res.json(); const es = new EventSource( `/api/v1/jobs/${job_id}/events`); es.onmessage = (e) => { const ev = JSON.parse(e.data); if (ev.type === "step") showStep(ev.node); if (ev.type === "done" || ev.type === "failed") { es.close(); loadResult(job_id); // GET /jobs/{id} } };
GET /jobs/{id}로 현재 상태를 먼저 그리기EventSource는 Authorization 헤더를 못 붙임 → 쿠키 인증 또는 fetch 기반 SSE 라이브러리 사용"오토힐링 = 에이전트가 알아서 고친다"가 전부가 아닙니다. 아래 계층일수록 단순·확실하게.
| 계층 | 무엇이 고장나나 | 자동 조치 | 코드 위치 |
|---|---|---|---|
| ① 호출 | 외부 API 타임아웃·5xx·429, LLM 과부하 | 타임아웃 → 지수 백오프 재시도 → 폴백(백업 API·캐시·다른 모델) | agents/integrations/agents/healing/ |
| ② 에이전트 | LLM 출력 형식 오류, 근거 부족, 잘못된 판단 | 스키마 검증 실패 → 재생성, 자기성찰 노드에서 재진단(최대 N회) → 사람 이관 | agents/graph/ |
| ③ 작업 | Job 처리 중 예외, 워커 강제 종료 | Celery self.retry(), acks_late로 워커가 죽어도 재전달, 상태 선점(claim)으로 중복 방지, 최종 실패는 failed | agents/worker/tasks.pycelery_app.py |
| ④ 인프라 | 프로세스 다운, 메모리 초과 | 헬스체크 실패 → 컨테이너 자동 재시작, 워커 여러 개 띄우기 | docker/compose/compose.ymlagents/healing/monitor.py |
import httpx from tenacity import (retry, stop_after_attempt, wait_exponential, retry_if_exception_type) class TransientError(Exception): ... # "잠깐 기다리면 될 오류" @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=8), # 1→2→4초 retry=retry_if_exception_type(TransientError), reraise=True) def get_json(client, url, params): try: r = client.get(url, params=params, timeout=5.0) except (httpx.TimeoutException, httpx.NetworkError) as e: raise TransientError(str(e)) from e if r.status_code == 429 or r.status_code >= 500: raise TransientError(f"HTTP {r.status_code}") r.raise_for_status() # 4xx = 내 잘못 → 재시도 X return r.json() def get_crowd(area: str) -> dict: with httpx.Client() as c: try: return get_json(c, PRIMARY_URL, {"area": area}) except TransientError: if cached := cache.get(area): # 폴백 ① 캐시 return {**cached, "stale": True} return get_json(c, BACKUP_URL, {"area": area}) # ② 백업
일시적 (타임아웃·5xx·429) → 재시도할 가치 있음
영구적 (400·401·404) → 재시도해도 똑같음, 즉시 실패
① 여기(tenacity): 몇 초 안의 짧은 재시도
② 그래도 실패 → TransientError가 태스크까지 올라가 Celery self.retry()로 수십 초 뒤 전체 재실행
"stale": true처럼 남겨 에이전트·화면이 "최신 아님"을 알게 합니다. LLM도 integrations/llm.py(LiteLLM 등)에 모아 모델 폴백을 한 곳에서.
docker/ ├── build.sh # 모든 이미지 빌드 + VERSION 갱신 ├── start.sh # 컴포즈 시작 ├── stop.sh # 컴포즈 종료 ├── restart.sh # 재시작 (stop → start) ├── compose/ │ ├── compose.yml # 서비스 정의 │ └── .env # 서비스 환경설정 │ # (루트 .env 심볼릭 링크 가능) └── images/ # 우리 소스로 빌드하는 이미지 ├── {팀}-fe/ # 프런트엔드 │ ├── Dockerfile │ └── VERSION # 예: 261119-1650 ├── {팀}-be/ # 백엔드 API 서버 │ ├── Dockerfile │ └── VERSION ├── {팀}-agents/ # Celery 워커 + 에이전트 │ ├── Dockerfile │ └── VERSION └── … # 필요 시 추가
images/bike-be/ → 이미지 bike-be:261119-1650. 팀 프리픽스로 다른 팀·프로젝트 이미지와 섞이지 않습니다.
Redis·PostgreSQL·Flower처럼 공식 이미지를 그대로 쓰는 서비스는 빌드하지 않고 compose.yml에서 바로 가져옵니다.
YYMMDD-hhmm 형식으로 build.sh가 자동 기록. 문제가 생기면 이전 시각 태그로 바로 되돌릴 수 있습니다.
ln -s ../../.env docker/compose/.envcompose.yml과 같은 폴더의 .env를 자동으로 읽습니다.#!/usr/bin/env bash # 사용법: ./docker/build.sh (전체) # ./docker/build.sh bike-agents (일부만) set -euo pipefail cd "$(dirname "$0")/.." # 프로젝트 루트로 이동 VERSION=$(date +%y%m%d-%H%M) # 예: 261119-1650 TARGETS=("$@") if [ ${#TARGETS[@]} -eq 0 ]; then TARGETS=($(ls docker/images)) # 인자 없으면 전부 fi for name in "${TARGETS[@]}"; do dir="docker/images/$name" echo "▶ $name:$VERSION" docker build -f "$dir/Dockerfile" \ -t "$name:$VERSION" -t "$name:latest" . # 컨텍스트=루트 echo "$VERSION" > "$dir/VERSION" # 성공했을 때만 기록 done
빌드 컨텍스트가 프로젝트 루트라서 Dockerfile이 shared/, backend/, agents/를 모두 COPY할 수 있습니다.
FROM python:3.12-slim
WORKDIR /srv
COPY backend/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY shared/ ./shared/
COPY backend/app/ ./app/
ENV PYTHONPATH=/srv
CMD ["uvicorn", "app.main:app", \
"--host", "0.0.0.0", "--port", "8000"]
FROM python:3.12-slim
WORKDIR /srv
COPY agents/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY shared/ ./shared/
COPY agents/ ./agents/
ENV PYTHONPATH=/srv
CMD ["celery", "-A", "agents.worker.celery_app", \
"worker", "-Q", "agents", "-l", "INFO"]
requirements를 먼저 COPY → 소스만 바뀌면 pip 단계는 캐시 재사용 (빌드 빨라짐).
services:
fe:
image: ${TEAM}-fe:${FE_VERSION:-latest}
ports: ["80:80"]
be:
image: ${TEAM}-be:${BE_VERSION:-latest}
env_file: .env
ports: ["8000:8000"]
depends_on: [redis, db]
restart: unless-stopped
agents:
image: ${TEAM}-agents:${AGENTS_VERSION:-latest}
env_file: .env
depends_on: [redis, db]
restart: unless-stopped # 죽으면 자동 재시작
deploy: { replicas: 2 } # 워커 2개
agents-beat: # 주기 작업 (같은 이미지!)
image: ${TEAM}-agents:${AGENTS_VERSION:-latest}
env_file: .env
command: celery -A agents.worker.celery_app beat -l INFO
flower: # 모니터링 대시보드
image: mher/flower
command: celery --broker=redis://redis:6379/0 flower
ports: ["5555:5555"]
redis: { image: redis:7-alpine, restart: unless-stopped }
db:
image: postgres:16
env_file: .env
volumes: [pgdata:/var/lib/postgresql/data]
volumes: { pgdata: {} }
COMPOSE_PROJECT_NAME=bike
TEAM=bike
# 롤백할 때만 지정 (비우면 latest)
# AGENTS_VERSION=261118-0930
REDIS_URL=redis://redis:6379/0
POSTGRES_PASSWORD=change-me
DATABASE_URL=postgresql://postgres:change-me@db/app
OPENAI_API_KEY=...
AGENTS_VERSION만 바꾸고 start → 그 시각 이미지로restart는 프로세스가 죽었을 때만 재시작합니다. 응답 없음(unhealthy) 감지·재시작은 healing/monitor가 맡도록 설계하세요.#!/usr/bin/env bash set -euo pipefail cd "$(dirname "$0")/compose" docker compose up -d "$@" docker compose ps
#!/usr/bin/env bash set -euo pipefail cd "$(dirname "$0")/compose" docker compose down # DB 볼륨은 유지됨 # (down -v 는 DB 삭제!)
#!/usr/bin/env bash set -euo pipefail DIR="$(cd "$(dirname "$0")" && pwd)" "$DIR/stop.sh" "$DIR/start.sh"
| 상황 | 명령 |
|---|---|
| 처음 띄우기 | ./docker/build.sh && ./docker/start.sh |
| 에이전트 코드만 고침 | ./docker/build.sh bike-agents && ./docker/start.sh (바뀐 서비스만 새로 생성) |
| 깨끗하게 다시 시작 | ./docker/restart.sh |
| 워커 로그 보기 / 워커 늘리기 | cd docker/compose && docker compose logs -f agents / docker compose up -d --scale agents=4 |
| 장애 주입 (오토힐링 시연) | docker compose exec agents sh -c "kill 1" → 워커 자동 재시작·태스크 재전달 확인 (Flower로 시연) |
처음 한 번 실행 권한 부여: chmod +x docker/*.sh
구조는 그대로 두고 Job · 에이전트 · 외부 API · 힐링 포인트만 팀 주제에 맞게 채웁니다. (아래는 예시)
| 묶음배달 오토힐링 | 축제 다국어 안심 관광 비서 | 자전거 안전 상담·코스 추천 | |
|---|---|---|---|
| Job 1건 | "이 배달 묶음에 이상 있음 → 진단·재배정" | "외국인 관광객 질문 1건 → 안전 답변 생성" | "출발지·조건 → 코스 추천 + 안전 상담" |
| 에이전트 | 감지 → 진단 → 재배정(복구) → 검증 | 언어·의도 파악 → 혼잡도 조회 → 경로·대피 안내 → 응답 검증 | 상담 → 코스 탐색 → 위험구간 결합 → 검증 |
| 외부 API | 지도·경로, 기상 | 공공 혼잡도·관광 정보, 번역(LLM) | 자전거도로·사고다발 공공데이터, 기상 |
| 힐링 포인트 | 지연·이탈 감지 시 재배정 / 경로 API 실패 시 거리 추정 폴백 | 공공 API 1차 → 2차 → 캐시(stale 표시) 페일오버 | 기상 API 장애 시 기본 안전 안내 + 재시도 / LLM 모델 폴백 |
| 주기 작업 | N분마다 진행 중 배달 점검 | N분마다 혼잡도 수집·캐시 갱신 | 매일 공공데이터 갱신 |
Celery 태스크 안에서 time.sleep(3) 세 번 + 이벤트 발행만. POST → 202 → 폴링 → done이 돌면 성공.
jobs 테이블과 상태 머신(queued/running/succeeded/failed) 완성. 새로고침해도 결과가 보여야 함.
폴링을 SSE로 교체. 노드 이름이 화면에 하나씩 찍히는 "사고 과정 타임라인".
sleep 자리에 graph.stream(). 에이전트는 노트북/단위 테스트로 먼저 검증한 뒤 붙이기.
agents/integrations/ 래퍼에 재시도·폴백. 장애 주입 스위치(환경변수)를 만들어 둔다.
docker/build.sh → start.sh로 배포. 장애 주입 → 감지·복구 시간 로그 → Auto-Healing 결과서.
☐ API 엔드포인트 안에서 graph.ainvoke()를 기다리고 있다
☐ BackgroundTasks로 멀티에이전트를 돌린다 (재시작 시 유실)
☐ Celery 태스크 인자로 대화 전문·파일 내용을 통째로 넘긴다 → ID만
☐ Job 상태를 DB에 안 남겨서 새로고침하면 결과가 사라진다
☐ docker compose down -v로 DB 볼륨까지 지운다
☐ 모든 오류를 무조건 재시도한다 (400·401도)
☐ 재시도 횟수·타임아웃 상한이 없다 → 무한 루프·비용 폭탄
☐ LLM·외부 API 키가 프런트 코드나 GitHub에 있다
☐ API 서버의 async def 안에서 requests·time.sleep 같은 동기 호출을 한다
☐ 같은 요청이 두 번 들어와 복구가 두 번 실행된다 → 멱등 키
☐ 이미지를 latest로만 관리해 이전 버전으로 되돌릴 수 없다