표준화된 도구 통합 및 외부 API 활용 설계 - 100-hours-a-week/KTB4-13th-wiki GitHub Wiki

MCP는 아무 데나 쓰는 게 아니라, "AI가 대화·추론 중에 도구를 골라 부르는" 딱 그 상황을 위한 규격이다.

1. MCP라는 표준 연결 규격은 안 쓴다

• 표준으로 연결할 곳은 한 지점 존재
  • V2 쇼핑 에이전트가 BE 기능 7개(장바구니 담기·빼기·조회, 주문 요약, 재고 확인, 책 정보)를 부르는 것.
• 외부 AI 모델(문장 생성, 벡터 변환)은 이미 우리 자체 창구인 "모델 게이트웨이"로 깔끔하게 정리돼 있다.
• MCP의 장점은 "도구가 계속 늘고, 남이 만든 도구를 갖다 쓰고, 여러 AI가 도구를 나눠 쓸 때" 나온다.
  • 우리는 도구 7개 고정 + 상대는 우리 BE 팀 하나라 장점이 없음

2. 대신 쇼핑 에이전트 BE tool 기능 목록을 "MCP랑 똑같은 양식"으로만 적어둔다

• 기능마다 이름 / 설명 / 받는 값 형식 / 성격(읽기 전용인지, 여러 번 불러도 안전한지)을 적는다. (실제 통신은 그냥 평범한 내부 REST.)
• 나중에 진짜 MCP로 바꿔야 할 일이 생겨도, 부르는 쪽 코드는 안 고쳐도 된다. 통로만 갈아 끼우면 끝.

3. 모델 부르는 건 이미 표준화돼 있다

• 추천·검색 코드는 complete()(문장 생성)와 embed()(벡터 변환) 두 함수만 부른다.
  • 어느 회사 모델을 쓰는지 몰라도 된다.
• 과제가 요구하는 "표준 인터페이스 + 권한 관리 + 비용·지연·안정성 제어"는 MCP가 아니라 이 게이트웨이 계층이 담당한다.

4. 이미지·영상·음성 만드는 기능이 없다

AI 서버가 자기 프로세스 밖과 주고받는 지점

💡 판정: MCP 전송/서버 프로세스는 미도입.

MCP의 스키마 관례(선언적 도구 디스크립터 + 능력 어노테이션)만 차용한다.

AI↔BE tool을 아래 형식으로 정의한다.

BE는 이걸 구현하고, AI 서버의 ToolRegistry가 그대로 읽어 LLM tool-calling 목록으로 넘긴다.

{
  "name": "cart.add",
  "description": "장바구니에 도서를 담는다. 재고·권한은 BE가 재검증한다.",
  "inputSchema": {
    "type": "object",
    "required": ["user_id", "book_id", "qty"],
    "properties": {
      "user_id": { "type": "integer" },
      "book_id": { "type": "integer" },
      "qty":     { "type": "integer", "minimum": 1 }
    }
  },
  "annotations": {
    "readOnlyHint": false,
    "idempotentHint": true,
    "audience": ["agent"],
    "owner": "backend-commerce"
  }
}

• "성격표시" 칸을 보고 재시도 정책이 자동으로 갈립니다.

설명서의 성격표시 칸에 "이 도구는 읽기만 함" / "두 번 불러도 안전함" 같은 게 적혀 있습니다. 호출 실패했을 때 우리 코드가 이걸 보고 알아서 판단

• 읽기 도구(재고 조회 등) → 실패하면 그냥 다시 부름 (여러 번 불러도 아무 일 안 생기니까)
• 쓰기 도구(장바구니 담기 등) → "이거 두 번 하지 마" 표식(멱등키)이 붙어 있을 때만 다시 부름 (안 그러면 두 번 담길 수 있으니까)
• 이 설명서를 AI 코드에 넣어두고, BE 팀과 "계약서"로 공유한다

1. 에이전트가 자체 BE 밖의 도구를 써야 한다
   1. 배송사 추적 API 직결, 외부 예약/티켓, 결제대행.
2. BE tool의 소비자가 AI 서버 외에 생긴다
   1. 다른 내부 서비스, 파트너.
3. tool 세트가 동적·대규모가 되어 수기 디스크립터 관리가 불가능해진다
   1. (단계 4의 LangGraph 재평가 트리거 ⓑ와 같은 신호)
4. 서드파티가 우리 추천을 도구로 호출하는 B2B 요구(우리가 MCP 서버가 되는 경우)

전환 비용: ToolInvoker의 전송 어댑터 1개 교체(REST → MCP 클라이언트). 디스크립터가 이미 MCP 형식이라 호출부·프롬프트·grounding 로직 무변경.

flowchart TB
    subgraph AI["AI 서버 · FastAPI (단일 배포, 논리 모듈 분리)"]
        SRCH["검색 모듈 ①<br/>파서→BM25+벡터→RRF→랭킹"]
        PIPE["추천·취향 모듈 ③④⑤⑥<br/>해석·후보검색·재랭킹·이유·취향추출·프로필"]
        AGT["쇼핑 에이전트 ⑦ (V2)<br/>지시어해소→의도분류→tool루프→grounding"]

        subgraph GWs["표준화 게이트웨이 계층"]
            MGW["모델 게이트웨이<br/>complete() · embed() · vision_encode() · ocr()<br/>어댑터·폴백체인·서킷·응답캐시·레이트리밋"]
            TGW["도구 게이트웨이 (V2)<br/>ToolRegistry(MCP호환 디스크립터)<br/>ToolInvoker(재시도·타임아웃·서킷·파생멱등키·감사)<br/>GroundingEnforcer"]
        end
    end

    subgraph SELF["자체 서빙 (같은 VPC / 사이드카)"]
        E5["임베딩 e5-small (CPU, uvicorn workers)"]
        CLIP["표지 이미지 인코더 (open CLIP, 배치)<br/>V2+ · 트리거 관측 시에만"]
    end

    subgraph EXT["외부 상용 API"]
        LLM["상용 LLM API<br/>텍스트 생성 (스트리밍)"]
        OCRAPI["OCR + VLM 폴백 API<br/>표지 텍스트·단서 추출 (V2)"]
    end

    subgraph BE["백엔드 · 커머스 코어"]
        TOOLS["/internal/tools/*<br/>cart.add · cart.update · cart.view<br/>order.preview · inventory.check · book.detail"]
        CATCRON["카탈로그 레코드 적재 크론<br/>(제목·저자·가격·ISBN)"]
        BEDB[("BE · MySQL (커머스 원본)<br/>회원 · 카탈로그 · 장바구니 · 주문 · 결제")]
    end

    NL["국중도 SEOJI 서지 API<br/>BOOK_INTRODUCTION · BOOK_TB · 표지(조건부)"]
    AIDB[("AI 전용 · PostgreSQL + pgvector<br/>v_books·v_user_* (복제 사본)<br/>book_embeddings · taste_profile<br/>book_cover_embedding (V2)")]

    SRCH --> MGW
    PIPE --> MGW
    AGT --> PIPE
    AGT --> TGW
    PBATCH --> MGW
    MGW -->|"embed()"| E5
    MGW -->|"vision_encode()"| CLIP
    MGW -->|"complete()"| LLM
    MGW -->|"ocr()"| OCRAPI
    TGW -->|"내부 REST + 서비스 토큰"| TOOLS
    SRCH --> AIDB
    PIPE --> AIDB
    CLIP --> AIDB
    PBATCH --> AIDB
    CATCRON -->|"1 req/s, 체크포인트"| NL
    PBATCH -->|"1 req/s, BOOK_INTRODUCTION·BOOK_TB 전문"| NL
    CATCRON --> BEDB
    TOOLS --> BEDB
    BEDB ==>|"BE→AI 단방향 복제<br/>(신선도 예산: 명세 §1)"| AIDB

• 결정: multilingual-e5-small 자체 서빙 확정(bench/).
  • 상용 임베딩 API는 런타임 폴백으로도 쓰지 않는다. 모델이 다르면 벡터 공간(대개 차원까지)이 달라 book_embeddings·취향 프로필·기억 벡터와 비교할 수 없다.
• 근거: 최다 호출 경로(모든 검색·추천 질의).
  • 자체 서빙으로 p95 467ms→21ms(22배), 건당 과금 제거, 하이브리드 recall 0.90(Gemini 벡터 단독 동급). 인제스트 처리량 5.6→200+ docs/s.
• 제약: GIL+torch로 스레드 확장 안 됨
  • uvicorn --workers 프로세스 복제. CPU 코어가 스케일 단위.
• 자체 vs API: 이미 자체가 이김.
  • 자체 서빙 장애는 폴백 없이 강등(① keyword-only · ④ rule-only · ⑤ 503)으로 받는다.
  • 모델 회귀 시 되돌리기는 설정 변경이 아니라 모델 교체 절차를 따른다: 도서 임베딩 전량 재적재 + BE의 전 사용자 ⑥ 재호출 + 기억 벡터 재생성(ERD §7).

V2의 "사진으로 책 찾기"는 이미지 임베딩 최근접이 아니라 이미지→텍스트 변환 + 기존 텍스트 검색이다.

최종 매칭은 항상 v_books 검색이 결정하고(카탈로그 밖 반환 불가), 모델은 검색어만 만든다.

• 비용·성능: 질의 = OCR(API, ～수백 ms) + (폴백 시) VLM + v_books 텍스트 검색(BM25, ms대). 이미지 턴 SLO에 여유.
• 제약: OCR·VLM API 모두 데이터 경계 이탈 사용자 사진이 나감 → no-train + 짧은 보관 프로바이더 선택, Pre-signed URL만 넘기고 AI는 이미지 미저장.
• 표지 사진은 BE가 임시 보관함에 올리고 AI엔 만료되는 주소만 전달(명세 ③ V2).

→ 과제의 "GPU 자원 부족 시 상용 생성 API" 긴장은 이 서비스에 거의 비해당. 유일한 상용 의존은 소형 텍스트 LLM이고, 그건 게이트웨이가 관리한다.

프로바이더 중립 인터페이스. 파이프라인·에이전트는 이것만 호출한다.

class ModelGateway:
    def complete(self, req: CompletionReq) -> CompletionResp | Iterator[Delta]: ...   # LLM, 스트리밍 옵션
    def embed(self, texts: list[str], purpose: str) -> list[Vector]: ...               # e5-small 단일. 다른 모델로 폴백하지 않음
    def ocr(self, image: bytes) -> OcrResult: ...                                      # OCR API(주) / 자체(폴백) → 실패분 VLM 폴백 (V2)
    def vision_encode(self, image: bytes) -> Vector: ...                               # 자체 open CLIP — V2+, 표지 벡터 인덱스 트리거 시에만

class ToolGateway:
    registry: ToolRegistry          # MCP 호환 디스크립터 로드 (2-B), allow_tools 필터
    def invoke(self, call: ToolCall, turn: AgentTurn) -> ToolResult: ...

class ToolInvoker:
    # 내부 REST: POST {BE}/internal/tools/{name}, Authorization: Bearer <서비스 토큰>
    # - annotations.idempotentHint=false → 파생 멱등키 {idempotency_key}:{tool_call_index}
    # - annotations.readOnlyHint=true    → 재시도 자유 / false → 멱등키 있을 때만 재시도
    # - 타임아웃 3s, 재시도 2회(지터 백오프), tool별 서킷 브레이커
    # - 실패는 예외로 던지지 않고 ToolResult(ok=False, error=...) 로 흡수 → 발화로 안내, 200 유지
    # - 모든 호출을 tool_calls[]에 감사 기록 (name/arguments/result/grounded)

• 인증: 방향 전용 서비스 토큰(BE 발급).
  • 사용자 위임 토큰 없음. 소유권은 BE가 arguments.user_id로 tool마다 재확인.
• 권한 모델: allow_tools(턴별 화이트리스트, null이면 전부 허용, 표에 없는 이름은 400) → registry 필터 → user_context.logged_in=false면 쓰기 tool(cart.add·cart.update) 원천 차단.
• grounding: GroundingEnforcer가 발화의 모든 수치·상태(가격·재고·수량·합계·별점)를 tool_calls[].result에 대조
  • → 뒷받침 없으면 그 tool_call을 grounded: false로 기록하고 가능하면 그 문장만 축약(200).
  • 핵심 주장을 못 대면 422 grounding_failed(답변 통째 폐기, 클라이언트가 일반 안내로 대체). context_cards[].price는 직전 턴 스냅샷이라 쓰지 않고 inventory.check/book.detail로 재검증한 값만 사용.
• 되물음: resolved_reference.confidence < 0.6이면 tool 미실행하고 되묻는 답변(200, tool_calls: []).
• 왜 gRPC가 아니라 REST
  • BE가 이미 REST, tool 수 적음, 감사 로그·디버깅 가독성, LLM tool-calling이 JSON Schema 네이티브. gRPC는 임베딩 자체서빙 사이드카(고QPS 인제스트)에서만 후보로 남긴다.

class CatalogSource(Protocol):            # 새 소스 추가 시 이 인터페이스만 구현
    def fetch(self, isbn13: str) -> RawRecord: ...
    def list_recent(self, since: date) -> Iterator[str]: ...

class SeojiClient(CatalogSource):
    # rate_limit=1req/s, 체크포인트(마지막 성공 ISBN), 실패 ISBN 데드레터 큐
    # 에러 {RESULT:ERROR,ERR_CODE} → 재시도 or 데드레터, 크론은 계속 진행

• 두 적재가 같은 SEOJI 소스를 보지만 쓰는 DB가 다르다:
  • 카탈로그 레코드(제목·저자·가격·ISBN)는 BE MySQL로 들어가 복제되고,
  • AI는 같은 원본에서 BOOK_INTRODUCTION·BOOK_TB 전문만 따로 받아 청킹·②로 임베딩해 AI Postgres book_passage에 색인한다.
• 병합은 ISBN-13 조인 키 3계층(aladin-ingest 메모
  • raw → v_books COALESCE → 서빙). 새 소스는 raw 테이블 + COALESCE 우선순위만 추가.
• AI가 직접 돌리는 적재는 도서 임베딩(book_embeddings) 배치뿐이다.
  • v_books.description 복제가 끝난 뒤 이어서 ②로 임베딩해 upsert한다(카탈로그 복제 크론과 레이트리밋 공유).
  • v_books.description 복제가 끝난 뒤 이어서 ②로 임베딩해 upsert한다(카탈로그 복제 크론과 레이트리밋 공유).

• 모든 외부 I/O가 2개 게이트웨이로 수렴
  • 커넥션 풀링, 레이트리밋 샤딩, 프로바이더별 스케일을 한 곳에서 조정. 파이프라인 수가 늘어도 통합 표면은 안 늘어난다.
• 커머스 데이터는 복제로 들어와 AI가 BE에 매 요청 조회하지 않는다
  • BE 부하·왕복 지연이 추천 트래픽에 비례해 늘지 않고, AI Postgres 하나만 읽기 스케일하면 된다. 대가는 신선도 예산 안의 지연(가격·재고 5분 등).
• tool 세트가 선언적 디스크립터라, 에이전트 능력 확장이 "디스크립터 + BE 엔드포인트" 추가로 끝난다.
• MCP 전송을 안 깔았지만 디스크립터를 MCP 형식으로 유지해 전환 옵션을 열어뒀다
  • 서드파티·다중 소비자가 실제로 생기는 시점에 전송만 교체.

• 프로바이더·tool 변경이 어댑터/디스크립터로 국소화. LLM 호출 지점이 온라인 1곳(③)·야간 1곳(⑤)으로 명시적(V2에서 ⑦·표지 추가)
  • → grounding·강등 로직을 그 지점에 직접 붙인다(프레임워크 추상화 뒤에 숨지 않음
  • 후보 선택·채점은 결정론, LLM은 최종 3권 + 이유만).
• MCP 서버 프로세스·JSON-RPC 브리지를 안 넣어 의존성 트리가 얇다
  • (FastAPI + 임베딩 SDK + LLM SDK + HTTP 클라이언트). 배포·장애원인 추적이 단순.
• 외부 호출 정책(재시도·타임아웃·서킷)이 한 표로 통일
  • → 신규 통합도 같은 규칙을 따른다.

• 자체 서빙 임베딩이 최다 호출·최다 과금 경로를 제거(건당 과금 0, 22배 지연 개선).
• 긴 이유를 BE가 보관해 상세 페이지 재진입 시 LLM 0회
  • 이유 캐시 테이블·만료·권한 규칙이 통째로 사라짐(명세 결정). 대가는 안 열어 볼 카드의 긴 이유까지 생성하는 턴당 출력 토큰.
• 상용 LLM은 진짜 생성이 필요한 텍스트에만, 소형 모델 클래스로. 유휴 GPU 없음.
• 표지 인식은 V2에서도 텍스트 검색(OCR+VLM 폴백)으로 출시
  • 이미지 벡터 인프라를 트리거 관측 전엔 안 얹음.
• MCP 전송 오버헤드(추가 홉·프로세스)를 값이 안 나오는 곳에 안 넣음.
• 게이트웨이의 호출당 비용 로깅이 자체서빙 전환 손익분기를 상시 추적
  • → 트래픽이 임계를 넘으면 데이터에 근거해 소형 LLM 자체서빙으로 전환.