도구 연동과 MCP 규격: Tool Calling과 스키마 검증

본 포스트는 'AI 에이전트 엔지니어링(AI Agent Engineering)' 시리즈의 3편입니다. LLM Tool Calling의 5단계 생명주기, Model Context Protocol(MCP) 규격, 그리고 Pydantic v2 기반 방어적 스키마 검증 기법을 심층 파헤칩니다.

---

1. 도구 정의와 LLM Tool Calling 메커니즘

LLM(대화형 언어 모델)이 격리된 상자(Sandbox)를 벗어나 외부 실세계를 조작하기 위해서는 도구(Tool / Function)를 호출할 수 있어야 합니다. 초기 프롬프트 엔지니어링 기법에서는 ReAct(Reasoning + Acting) 패턴처럼 일반 텍스트 출력 속에 Action: search_database("query") 형태의 문자열 파싱을 사용했으나, 이는 괄호 누락이나 인자 타입 오염 등 심각한 구문 오류(Syntax Error)를 야기했습니다.

현대의 프로덕션 에이전트 런타임은 LLM 공급업체(OpenAI, Anthropic, Google 등)가 제공하는 네이티브 Tool Calling (Function Calling) 기능에 의존합니다.

1.1 ReAct 텍스트 파싱 vs 네이티브 Tool Calling 비교

1.2 네이티브 Tool Calling 5단계 생명주기 (Lifecycle Architecture):

준비

1. 1subgraph
2. 2Pydantic / Python Handler
3. 3JSON Schema Generator
4. 4Tools Array (JSON Schemas)
5. 5end

반복 실행

1. 1API Request Payload Inject
2. 2User Goal & History

실패 시 다시 실행 단계로 돌아갑니다.

정리

1. 1LLM Provider Engine
2. 2Tool Execution Needed?
3. 3Standard Content Text Output
4. 4Grammar-Guided Constrained Sampler
5. 5Native tool_calls JSON Output
6. 6Agent Runtime Parser
7. 7Pydantic Schema Validation
8. 8Diagnostic Error Generation
9. 9Tool Handler Execution
10. 10Inject Role: tool (Error Feedback)
11. 11Inject Role: tool (Success Result)

LLM Tool Calling의 5단계 세부 동작

1. 도구 정의 전달 (Tool Schema Injection): 호스트 애플리케이션은 사용 가능한 도구 목록을 JSON Schema 래퍼로 변환하여 LLM 요청 파라미터(tools)로 주입합니다.
2. 페이로드 전송 (Payload Transmission): 사용자 입력, 대화 히스토리, 도구 스키마를 묶어 LLM API로 전송합니다.
3. 문법 제어 샘플링 (Constrained Decoding & Tool Call Generation): 모델은 프롬프트 컨텍스트와 사용자의 목표를 분석하여 정형화된 JSON 형태의 tool_calls 객체(id, name, arguments)를 생성합니다.
4. 호스트 실행 및 검증 (Host Validation & Execution): 에이전트 런타임은 tool_calls 배열을 수신하여 해당 도구의 핸들러(Handler)를 찾고, 인자값을 검증한 뒤 실행합니다.
5. 결과 반환 및 대화 환류 (Context Feedback Loop): 실행 결과(성공 텍스트 또는 JSON 에러)를 role: "tool" 메시지로 변환하여 컨텍스트 히스토리에 추가하고 모델에게 재추론을 요청합니다.

컨텍스트 오버헤드 주의: 수십 개의 도구 스키마를 무분별하게 tools 배열에 주입하면 매 요청마다 수천 토큰 이상의 프롬프트 비용이 발생하며, 도구 간 이름/설명 충돌로 인해 모델의 도구 선택 정확도가 저하됩니다.

스키마 최적화 노하우: 도구 설정을 작성할 때 description을 명확하고 구체적으로 기술해야 합니다. 모델은 함수 이름보다 description을 우선시하여 도구를 선택합니다.

---

2. 도구 실행 제어 루프 및 시퀀스 다이어그램

도구 실행은 단발성 호출로 끝나지 않습니다. 도구 실행 결과가 예외를 반환하거나 예상과 다른 데이터가 반환될 경우, LLM이 오류 메시지를 관찰(Observe)하여 스스로 인자값을 수정하거나 대체 도구를 호출하는 자율 복구 루프(Self-Correction Loop)가 동작해야 합니다.

2.1 에이전트 도구 실행 전과정 시퀀스 다이어그램:

준비

1. 1User

반복 실행

1. 1Agent
2. 2Registry

3. Top-K 선택된 Tool Schemas

정리

1. 1LLM
2. 2MCP
3. 3과업 완수 결과 반환

2.2 자율 복구 루프 (Self-Correction Loop) 메커니즘:

반복 실행

1. 1LLM_Inference
2. 2ToolCall_Generated
3. 3Final_Answer
4. 4Schema_Validation
5. 5state
6. 6Syntax_Check
7. 7Type_Check
8. 8Diagnostic_Syntax_Error
9. 9Business_Rule_Check
10. 10Diagnostic_Type_Error
11. 11Validated
12. 12Diagnostic_Rule_Error
13. 13LLM_Self_Correction
14. 14Retry_Check

실패 시 다시 실행 단계로 돌아갑니다.

정리

1. 1Max_Retry_Exceeded
2. 2Tool_Execution
3. 3Executing
4. 4Execution_Success
5. 5Execution_Failure

2.3 에이전트 도구 실패 처리 전략 비교

무한 루프 방지 (Max Retries Bound): 자율 복구 루프는 반드시 max_retries (예: 3회) 제한을 두어야 합니다. 잘못된 스키마로 인해 모델이 동일 오류를 반복 생성하는 경우, 토큰 폭발과 무한 대기 현상을 차단해야 합니다.

---

3. Model Context Protocol (MCP) 규격과 아키텍처

에이전트 생태계가 확장됨에 따라 호스트 애플리케이션(Claude Desktop, Cursor, Custom Agent Framework)과 개별 도구(PostgreSQL, GitHub, Slack, Local Filesystem) 간의 표준화된 통신 인터페이스가 필요해졌습니다.

3.1 MCP 3대 핵심 원시 요소 (Primitives) 비교

MCP는 JSON-RPC 2.0 프로토콜 기반 위에서 세 가지 원시 요소를 제공합니다.

3.2 MCP Stdio vs SSE Transport 레이어 아키텍처:

준비

1. 1subgraph
2. 2Host Application (Claude / Cursor / Custom Agent)
3. 3MCP Client Manager
4. 4end
5. 5direction

반복 실행

1. 1Stdio Transport Client
2. 2Child Process stdin (NDJSON)
3. 3Child Process stdout (NDJSON)

실패 시 다시 실행 단계로 돌아갑니다.

정리

1. 1SSE Transport Client
2. 2HTTP POST Channel (/messages)
3. 3SSE Event Stream Channel (/sse)
4. 4Local MCP Server Process
5. 5Remote MCP HTTP/SSE Server
6. 6LocalDB
7. 7Cloud Enterprise APIs / PostgreSQL

3.3 MCP Stdio vs SSE 전송 레이어 상세 비교

JSON-RPC 2.0 표준 규격: MCP는 모든 메시지 교환 시 jsonrpc: "2.0", method, params, id 필드를 갖는 JSON-RPC 규격을 따릅니다. 이를 통해 클라이언트와 서버의 구현 언어가 달라도 완벽한 호환성을 제공합니다.

로컬 개발과 원격 분산 구동: 개발 단계에서는 오버헤드가 없는 Stdio 트랜스포트로 구축한 후, 프로덕션 배포 시 SSE/HTTP 트랜스포트로 전환하여 마이크로서비스로 확장하는 패턴이 권장됩니다.

---

4. MCP 파이썬 실전 구현 (Server & Client)

이 절에서는 현대적인 파이썬 백엔드 환경에서 MCP 서버를 구축하고, 에이전트 클라이언트가 이와 연결하여 도구를 동적으로 가져와 실행하는 프로덕션 레벨 코드 구조를 구축합니다.

4.1 MCP Handshake 및 메시지 교환 통신 시퀀스:

반복 실행

1. 1Client
2. 2Transport
3. 3Server

3. JSON-RPC response: initialize (serverInfo, capabilities)

4.2 MCP 도구 서버 구현 (mcp_server.py)

Copy1"""2MCP Server Implementation using FastMCP / Async patterns.3이 서버는 엔터프라이즈 데이터베이스 조회 및 사용자 권한 변경 도구를 제공합니다.4"""5 6import asyncio7import logging8from typing import Dict, Any9from pydantic import BaseModel, Field10from mcp.server.fastmcp import FastMCP11 12logging.basicConfig(level=logging.INFO)13logger = logging.getLogger("EnterpriseMCPServer")14 15# FastMCP 서버 인스턴스 초기화16mcp = FastMCP("Enterprise-Data-MCP-Server")17 18 19# ==========================================20# Pydantic Input Schemas21# ==========================================22class UserQueryInput(BaseModel):23    user_id: str = Field(description="조회할 사용자의 고유 UUID 키", json_schema_extra={"example": "usr_102938"})24    include_deleted: bool = Field(default=False, description="탈퇴된 사용자 계정 포함 여부")25 26 27class UserRoleUpdateInput(BaseModel):28    user_id: str = Field(description="권한을 변경할 사용자의 ID")29    target_role: str = Field(description="부여할 새로운 역할 (admin, operator, viewer)")30    reason: str = Field(min_length=10, description="권한 변경 사유 (최소 10자 이상 필수)")31 32 33# ==========================================34# MCP Tool Registration35# ==========================================36@mcp.tool(37    name="get_user_profile",38    description="사용자 ID를 기반으로 상세 프로필 데이터와 최근 활동 내역을 데이터베이스에서 조회합니다."39)40async def get_user_profile(user_id: str, include_deleted: bool = False) -> Dict[str, Any]:41    # 방어적 검증 (서버 내부 이차 검증)42    input_data = UserQueryInput(user_id=user_id, include_deleted=include_deleted)43    logger.info(f"User Query Executed for ID: {input_data.user_id}")44 45    # 가상 DB 조회 시뮬레이션46    if input_data.user_id == "usr_404":47        return {"status": "error", "message": f"User '{input_data.user_id}' not found."}48 49    return {50        "status": "success",51        "data": {52            "user_id": input_data.user_id,53            "name": "Jane Doe",54            "email": "user_account_id",55            "role": "operator",56            "is_active": True,57        }58    }59 60 61@mcp.tool(62    name="update_user_role",63    description="사용자의 시스템 접근 권한(Role)을 변경합니다. 고위험 도구이므로 사유 작성이 필수적입니다."64)65async def update_user_role(user_id: str, target_role: str, reason: str) -> Dict[str, Any]:66    # Pydantic 스키마 기반 데이터 정제67    try:68        payload = UserRoleUpdateInput(user_id=user_id, target_role=target_role, reason=reason)69    except Exception as e:70        return {"status": "error", "message": f"Schema Validation Failed: {str(e)}"}71 72    if payload.target_role not in ["admin", "operator", "viewer"]:73        return {"status": "error", "message": f"Invalid role '{payload.target_role}'. Must be one of [admin, operator, viewer]."}74 75    logger.warning(f"SECURITY EVENT: User {payload.user_id} role changed to {payload.target_role} (Reason: {payload.reason})")76 77    return {78        "status": "success",79        "result": {80            "user_id": payload.user_id,81            "updated_role": payload.target_role,82            "audit_logged": True83        }84    }85 86 87if __name__ == "__main__":88    # Stdio 모드로 MCP 서버 구동89    mcp.run(transport="stdio")

4.3 MCP 에이전트 클라이언트 연동 (mcp_client.py)

Copy1"""2MCP Client Manager that connects to stdio MCP Server and exposes JSON-RPC tools to LLM.3"""4 5import sys6import asyncio7from typing import List, Dict, Any, Optional8from contextlib import AsyncExitStack9from mcp import ClientSession, StdioServerParameters10from mcp.client.stdio import stdio_client11 12 13class AgentMCPClientManager:14    """MCP 서버들과의 라이프사이클을 관리하고 도구 스키마를 LLM 표준 규격으로 변환하는 클라이언트 클래스"""15 16    def __init__(self, server_script_path: str):17        self.server_script_path = server_script_path18        self.session: Optional[ClientSession] = None19        self._exit_stack = AsyncExitStack()20 21    async def connect(self):22        """Python 하위 프로세스로 MCP 서버를 시작하고 stdio 채널을 개설합니다."""23        server_params = StdioServerParameters(24            command=sys.executable,25            args=[self.server_script_path],26            env=None27        )28 29        # stdio 트랜스포트 및 세션을 AsyncExitStack으로 수명주기 안전 관리30        read_stream, write_stream = await self._exit_stack.enter_async_context(31            stdio_client(server_params)32        )33        self.session = await self._exit_stack.enter_async_context(34            ClientSession(read_stream, write_stream)35        )36        await self.session.initialize()37        print("[MCP Client] Connection successfully established to MCP Server.")38 39    async def get_llm_tool_definitions(self) -> List[Dict[str, Any]]:40        """MCP 서버의 tools/list를 호출하여 LLM(OpenAI/Anthropic) 규격의 JSON Schema 목록으로 변환합니다."""41        if not self.session:42            raise RuntimeError("MCP Session is not initialized.")43 44        mcp_tools_response = await self.session.list_tools()45        llm_tools = []46 47        for tool in mcp_tools_response.tools:48            # MCP Tool Schema to OpenAI Function Calling Schema 변환49            input_schema = getattr(tool, "inputSchema", getattr(tool, "input_schema", {}))50            llm_tools.append({51                "type": "function",52                "function": {53                    "name": tool.name,54                    "description": tool.description or "",55                    "parameters": input_schema56                }57            })58        return llm_tools59 60    async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:61        """MCP 서버로 tools/call 메시지를 전송하고 결과를 수신합니다."""62        if not self.session:63            raise RuntimeError("MCP Session is not initialized.")64 65        result = await self.session.call_tool(tool_name, arguments)66 67        # MCP TextContent / ImageContent 응답 파싱68        output_chunks = []69        for content in result.content:70            if getattr(content, "type", None) == "text":71                output_chunks.append(content.text)72 73        is_error = getattr(result, "isError", getattr(result, "is_error", False))74        return {75            "is_error": bool(is_error),76            "raw_output": "\n".join(output_chunks)77        }78 79    async def close(self):80        """MCP 클라이언트 자원을 안전하게 해제합니다."""81        await self._exit_stack.aclose()82        self.session = None83        print("[MCP Client] Connection safely closed.")

보안 위협 주의 (Command & Tool Injection): Stdio MCP 서버가 하위 프로세스로 구동될 때, 클라이언트 입력이 검증 없이 os.system이나 Shell 명령으로 실행되면 시스템 전체 권한이 탈취될 수 있습니다. 반드시 파라미터를 Sanitization하고 Pydantic 검증을 수행하세요.

AsyncExitStack 자원 관리: MCP 클라이언트 구현 시 AsyncExitStack을 활용하면 프로세스 예외 종료나 네트워크 단절 시에도 하위 프로세스의 stdin/stdout 스트림 및 세션을 안전하게 정리할 수 있습니다.

---

5. Tool Registry 패턴과 동적 도구 선택 (Dynamic Tool Selection)

엔터프라이즈 환경에서는 에이전트에 등록된 도구 수가 수십 개 이상으로 늘어납니다. 모든 도구의 스키마를 매 프롬프트마다 주입하면 세 가지 치명적 문제가 발생합니다.

1. 컨텍스트 비용 폭발 (Token Cost Bloat): 도구 정의만으로 수만 토큰 소비.
2. 도구 선택 환각 (Tool Confusion): 무관한 도구들이 유사한 매개변수를 가질 때 모델이 엉뚱한 도구를 호출.
3. 추론 속도 지연 (Latency Penalty): 프롬프트 길이 증가에 따른 TTFT(Time to First Token) 지연.

이를 해결하기 위해 Tool Registry 패턴과 시맨틱 동적 도구 선택(Semantic Tool Selection) 기법을 도입해야 합니다.

5.1 정적 도구 주입 vs 동적 시맨틱 레지스트리 비교

5.2 동적 도구 선택 코사인 유사도 필터링 흐름:

subgraph

Tool 1: get_user_profile

Generate Text Embedding

Tool 2: update_user_role

Generate Text Embedding

Tool N: 100+ Enterprise Tools

Generate Text Embedding

VDB

end

User Input Goal: 'Jane의 프로필과 권한 확인해줘'

Query Text Embedder

Query Vector (V_q)

Cosine Similarity Calculator

Similarity Score Matrix

Top-K Ranking Filter (K=3)

Selected Schemas (Top-3)

Construct Final LLM Request

LLM Inference Call

5.3 시맨틱 동적 도구 레지스트리 구현 (tool_registry.py)

Copy1"""2Dynamic Tool Registry with Semantic Tool Filtering.3"""4 5import math6from typing import List, Dict, Any, Callable, Awaitable, Optional7from pydantic import BaseModel, Field, ConfigDict8 9 10class RegisteredTool(BaseModel):11    model_config = ConfigDict(arbitrary_types_allowed=True)12 13    name: str14    description: str15    parameters_schema: Dict[str, Any]16    handler: Callable[..., Awaitable[Dict[str, Any]]] = Field(exclude=True)17    tags: List[str] = Field(default_factory=list)18 19 20class DynamicToolRegistry:21    """도구를 체계적으로 등록하고, 사용자 질의에 맞춰 동적으로 Top-K 도구를 주입하는 레지스트리"""22 23    def __init__(self):24        self._tools: Dict[str, RegisteredTool] = {}25 26    def register_tool(27        self,28        name: str,29        description: str,30        parameters_schema: Dict[str, Any],31        handler: Callable[..., Awaitable[Dict[str, Any]]],32        tags: Optional[List[str]] = None33    ):34        tool = RegisteredTool(35            name=name,36            description=description,37            parameters_schema=parameters_schema,38            handler=handler,39            tags=tags or []40        )41        self._tools[name] = tool42 43    def _dummy_embedding(self, text: str) -> List[float]:44        """간이 임베딩 벡터 생성기 (실제 프로덕션에서는 OpenAI text-embedding-3 등 사용)"""45        vocab = ["user", "profile", "role", "update", "delete", "database", "search", "order", "email"]46        tokens = text.lower().replace("_", " ").split()47        vector = [1.0 if word in tokens else 0.0 for word in vocab]48        norm = math.sqrt(sum(v * v for v in vector)) or 1.049        return [v / norm for v in vector]50 51    def _cosine_similarity(self, vec1: List[float], vec2: List[float]) -> float:52        return sum(a * b for a, b in zip(vec1, vec2))53 54    def select_tools(self, query: str, top_k: int = 3) -> List[Dict[str, Any]]:55        """사용자의 입력 질의와의 유사도를 계산하여 가장 연관성이 높은 Top-K 도구만 필터링합니다."""56        if len(self._tools) <= top_k:57            return [58                {59                    "type": "function",60                    "function": {61                        "name": t.name,62                        "description": t.description,63                        "parameters": t.parameters_schema64                    }65                }66                for t in self._tools.values()67            ]68 69        query_vec = self._dummy_embedding(query)70        scored_tools = []71 72        for tool in self._tools.values():73            tool_text = f"{tool.name} {tool.description} {' '.join(tool.tags)}"74            tool_vec = self._dummy_embedding(tool_text)75            score = self._cosine_similarity(query_vec, tool_vec)76            scored_tools.append((score, tool))77 78        # 코사인 유사도 기준 내림차순 정렬79        scored_tools.sort(key=lambda x: x[0], reverse=True)80        selected = scored_tools[:top_k]81 82        return [83            {84                "type": "function",85                "function": {86                    "name": t.name,87                    "description": t.description,88                    "parameters": t.parameters_schema89                }90            }91            for _, t in selected92        ]93 94    async def execute_tool(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:95        if name not in self._tools:96            raise KeyError(f"Tool '{name}' is not registered in the Tool Registry.")97        return await self._tools[name].handler(**arguments)

K값 설정의 딜레마 (Top-K Balancing): top_k를 너무 작게(예: 2) 설정하면 복잡한 다단계 과업 시 필요한 도구가 누락될 수 있고, 너무 크게(예: 20 이상) 설정하면 동적 필터링의 토큰 절감 효과가 반감됩니다. 일반적으로 3–5개가 가장 이상적입니다.

하이브리드 필터링 (Tag + Semantic Search): 태그 기반 1차 하드 필터링(예: 카테고리가 database인 도구만 선별)과 임베딩 기반 2차 시맨틱 필터링을 결합하면 선택 정확도를 크게 높일 수 있습니다.

---

6. Pydantic v2 기반 엄격한 스키마 검증 및 자율 복구 (Self-Correction)

LLM이 생성한 tool_calls.arguments는 단순 문자열(JSON String)입니다. 모델은 종종 필수 필드를 누락하거나, 정수(int) 자리에 문자열(str)을 넣거나, JSON 닫는 괄호를 누락하는 오류를 유발합니다. 따라서 호스트 에이전트 런타임에는 Pydantic v2 기반의 검증 파이프라인(Validation Pipeline)이 필수적입니다.

6.1 Pydantic v2 방어적 검증 파이프라인 흐름:

1. JSON Syntax Parse

Generate Syntax Fix Diagnostic Prompt

Feedback Loop (role: 'tool')

2. Type & Schema Validation

Generate Schema Fix Diagnostic Prompt

3. Business Rule Validation

6.2 Pydantic 도구 검증 오류 분류 및 자율 복구 피드백 맵

6.3 방어적 스키마 파서와 자율 복구 루프 (schema_validator.py)

Copy1"""2Pydantic v2 Defensive Argument Parsing & LLM Diagnostic Error Feedback Loop.3"""4 5import json6from typing import Type, TypeVar, Tuple, Optional, Any, Dict7from pydantic import BaseModel, ValidationError, Field, field_validator8 9T = TypeVar("T", bound=BaseModel)10 11 12class DatabaseQueryArgs(BaseModel):13    table_name: str = Field(description="조회 대상 테이블 이름")14    limit: int = Field(default=10, ge=1, le=100, description="반환 레코드 수")15    filters: Dict[str, Any] = Field(default_factory=dict, description="검색 필터 조건")16 17    @field_validator("table_name")18    @classmethod19    def validate_table_name(cls, v: str) -> str:20        allowed_tables = ["users", "orders", "audit_logs", "products"]21        clean_v = v.strip().lower()22        if clean_v not in allowed_tables:23            raise ValueError(f"허용되지 않은 테이블 '{v}' 접근 시도입니다. 허용 테이블: {allowed_tables}")24        return clean_v25 26 27class SafeToolCallExecutor:28    """LLM이 생성한 JSON 문자열 인자를 안전하게 파싱하고 Pydantic v2로 검증하는 실행기"""29 30    @staticmethod31    def parse_and_validate(32        raw_arguments_json: str,33        schema_cls: Type[T]34    ) -> Tuple[Optional[T], Optional[str]]:35        """36        JSON 문자열을 파싱하고 Pydantic 스키마 검증을 진행합니다.37        성공 시 (ValidatedModel, None) 반환.38        실패 시 (None, DiagnosticErrorMessage) 반환하여 LLM 재추론 힌트로 사용.39        """40        # 1. JSON Syntax Validation41        try:42            parsed_dict = json.loads(raw_arguments_json)43        except json.JSONDecodeError as e:44            error_hint = (45                f"[Tool Argument Syntax Error] 입력된 인자가 올바른 JSON 형식이 아닙니다.\n"46                f"Error Details: {str(e)}\n"47                f"Raw Input: {raw_arguments_json}\n"48                f"조치 사항: 올바른 JSON 문법 형식으로 인자값을 재작성하세요."49            )50            return None, error_hint51 52        # 2. Pydantic v2 Schema & Business Rule Validation53        try:54            validated_model = schema_cls.model_validate(parsed_dict)55            return validated_model, None56        except ValidationError as ve:57            # Pydantic 진단 에러 세부 정보 구조화58            formatted_errors = []59            for err in ve.errors():60                loc = " -> ".join(str(p) for p in err["loc"])61                msg = err["msg"]62                formatted_errors.append(f"- Field '{loc}': {msg}")63 64            error_hint = (65                f"[Tool Argument Schema Validation Failed]\n"66                f"도구 실행 인자 검증에 실패했습니다. 아래 오류 사유를 확인하고 올바른 인자값으로 재호출하세요:\n"67                + "\n".join(formatted_errors)68                + f"\n요청된 스키마 구조: {json.dumps(schema_cls.model_json_schema(), indent=2, ensure_ascii=False)}"69            )70            return None, error_hint

진단 메시지의 중요성: LLM에게 단순히 "검증 실패"라고만 전달하면 동일한 실수를 반복합니다. 실패한 필드의 exact path, 원인, 그리고 허용 가능한 값 스키마(model_json_schema())를 피드백에 명확히 작성해야 LLM이 한 번만에 자율 복구에 성공합니다.

---

7. 방어적 도구 연동 엔지니어링 체크리스트

프로덕션 환경에 도구를 노출할 때 발생할 수 있는 보안 문제와 서비스 장애를 방지하기 위해 작성된 엔지니어링 검증 체크리스트입니다.

7.1 엔터프라이즈 도구 연동 보안 & 신뢰성 매트릭스

7.2 Human-in-the-Loop & 권한 경계 메커니즘:

준비

1. 1LLM Tool Call Request
2. 2Tool Risk Level Analysis

반복 실행

1. 1Direct System Execution
2. 2Interrupt Agent Loop & Request HITL Approval
3. 3Human Operator Action

실패 시 다시 실행 단계로 돌아갑니다.

정리

1. 1Return Rejection Error to LLM Context
2. 2Return Execution Result (role: 'tool')

7.3 방어적 도구 연동 체크리스트

인자 인젝션 방어 (Argument Injection Prevention)

• Path Traversal 방지: 파일 읽기/쓰기 도구에서 ../ 경로 조작을 차단하기 위해 os.path.abspath 및 샌드박스 루틴 기본 적용 여부.
• Command & SQL Injection 방지: Shell 명령을 실행하는 도구에서 shell=True 사용 금지 및 매개변수화된 쿼리(Parameterized Queries) 강제 적용 여부.

비동기 타임아웃 및 서킷 브레이커 (Timeout & Resilience)

• 모든 도구 핸들러 호출부에 하드 타임아웃 적용 여부 (asyncio.wait_for(..., timeout=15.0)).
• 외부 3rd-party API 호출 도구 실패 시 타임아웃 지연으로 인한 에이전트 루프 전체 블로킹 방지 여부.

인간 개입 승인 (Human-in-the-Loop & Permission Boundaries)

• Read-Only vs Mutating 구분: 시스템 상태를 변경하거나 파괴적인 작업(DB 삭제, 외부 이메일 전송, 결제 등) 수행 시 HITL 승인 단계 강제 배치 여부.

멱등성 보장 (Idempotency)

• 네트워크 재시도 또는 LLM self-correction 재시도 시 동일한 요청이 중복 실행되지 않도록 idempotency_key 또는 유일 식별자 처리 여부.

진단 메시지 vs 보안 마스킹 (Error Masking Policy)

• LLM에게 반환되는 도구 에러 텍스트에 내부 데이터베이스 접속 정보, API Key, Stack trace 등 민감 정보가 유출되지 않도록 마스킹 처리 되었는가?
• 동시에 LLM이 오류 원인을 파악하고 자율 복구할 수 있는 충분한 비즈니스 힌트가 포함되었는가?

고위험 도구 자동화 금지: DB 드롭(Drop Table), 결제 승인, 외부 일괄 메일 발송 등 원복 불가능한 작업은 절대로 LLM 자율 실행에 맡기지 말고, 반드시 HITL 승인 레이어를 통해 최종 인간 검증을 거치도록 설계하십시오.

---

8. 요약 및 다음 포스트 예고

8.1 3편 핵심 요약 매트릭스

다음 회차 04편: 오케스트레이션과 멀티 에이전트에서는 단일 에이전트의 한계를 넘어 복수의 전문 에이전트들이 역할을 분담하고 그래프 상태(Graph State) 기반으로 협업하는 멀티 에이전트 오케스트레이션 패턴을 심층 분석합니다.