codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/services/rag_chat_agent.py

@@ -0,0 +1,2993 @@
+"""RAG Chat Agent — LangChain create_agent 기반 ReAct 에이전트.
+
+chat mode에서 RAG 검색이 필요할 때 LLM이 자동으로 rag_search tool을 호출.
+최대 2회 tool call, 스트리밍 지원.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from datetime import datetime
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, AsyncGenerator, Awaitable, Callable, Dict, List, Optional, Tuple
+
+from codebuff_core.platform_rules import with_platform_rules
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Raw LLM 로깅 유틸리티
+# ---------------------------------------------------------------------------
+
+_LOG_DIR = Path("agent_logs")
+
+
+def _get_raw_log_path() -> Path:
+    """타임스탬프 기반 로그 파일 경로 반환."""
+    _LOG_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return _LOG_DIR / f"raw_llm_{ts}.json"
+
+
+def _is_raw_logging_enabled() -> bool:
+    """config에서 rawLlmLogging 설정을 매번 확인 (핫리로드)."""
+    try:
+        from codebuff_core.managers.config_manager import get_config_manager
+
+        return bool(get_config_manager().get_config().get("rawLlmLogging", False))
+    except Exception as e:
+        print(f"[RAG] _is_raw_logging_enabled error: {e}", flush=True)
+        return False
+
+
+def _append_log(log_path: Path, entry: Dict[str, Any]) -> None:
+    """JSON 배열에 엔트리 추가 (보기 좋은 포맷)."""
+    try:
+        entries: list = []
+        if log_path.exists() and log_path.stat().st_size > 0:
+            with open(log_path, "r", encoding="utf-8") as f:
+                entries = json.load(f)
+        entries.append(entry)
+        with open(log_path, "w", encoding="utf-8") as f:
+            json.dump(entries, f, ensure_ascii=False, default=str, indent=2)
+    except Exception as e:
+        print(f"[RAG] _append_log error: {e} path={log_path}", flush=True)
+
+
+# ---------------------------------------------------------------------------
+# Harmony 토큰 필터 래퍼
+# ---------------------------------------------------------------------------
+
+# GPT-OSS harmony 특수 토큰 패턴
+_HARMONY_TOKEN_RE = re.compile(
+    r"<\|(?:start|end|message|channel|call|system|user|assistant|"
+    r"analysis|commentary|final|functions?)\|>"
+)
+_HARMONY_BLOCK_RE = re.compile(r"<\|message\|>.*?<\|end\|>", re.DOTALL)
+# GPT-OSS 인용 마커 (예: [9†L1-L7], [3†source]) — RAG에서 무의미
+# GPT-OSS 인용 마커 (예: [9†L1-L7], [7‡source], [3✝L2])
+# †(U+2020) ‡(U+2021) ✝(U+271D) ✙(U+2719) 등 십자가 계열 + 일반 특수문자
+_CITATION_MARKER_RE = re.compile(r"\[\d+[†‡✝✙✚✛✜⁺⁑][^\]]*\]")
+
+
+def _on_llm_retry_failure(exc: Exception) -> None:
+    """ModelRetryMiddleware on_failure: 로그 후 예외 재발생."""
+    print(f"[RAG] LLM API ERROR (all retries failed): {exc}", flush=True)
+    raise exc
+
+
+def _create_dynamic_system_prompt_middleware_class(prompt_holder: list):
+    """호출별로 시스템 프롬프트를 동적으로 교체하는 미들웨어.
+
+    prompt_holder는 [None] 또는 [str] 형태의 리스트.
+    RAGChatAgent._dynamic_prompt_holder를 공유 참조로 사용하므로
+    stream_response() 호출 전에 holder[0]을 설정하면 해당 호출에만 적용된다.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _DynamicSystemPrompt(AgentMiddleware):
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            override = prompt_holder[0]
+            if not override:
+                return None
+
+            from langchain_core.messages import SystemMessage
+
+            messages = state.get("messages", [])
+            new_msgs = []
+            replaced = False
+            for msg in messages:
+                if msg.type == "system" and not replaced:
+                    new_msgs.append(SystemMessage(content=override))
+                    replaced = True
+                else:
+                    new_msgs.append(msg)
+            if not replaced:
+                new_msgs.insert(0, SystemMessage(content=override))
+            return {"messages": new_msgs}
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+    return _DynamicSystemPrompt
+
+
+def _create_developer_role_middleware_class():
+    """SystemMessage → developer role 변환 미들웨어.
+
+    gpt-oss는 system role을 메타데이터로 취급하고,
+    developer role을 최우선 지시사항으로 따른다.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _DeveloperRole(AgentMiddleware):
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            from langchain_core.messages import ChatMessage
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            converted = []
+            changed = False
+            for msg in messages:
+                if msg.type == "system":
+                    converted.append(ChatMessage(role="developer", content=msg.content))
+                    changed = True
+                else:
+                    converted.append(msg)
+
+            return {"messages": converted} if changed else None
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+    return _DeveloperRole
+
+
+def _create_strip_content_on_toolcall_middleware_class():
+    """tool_calls가 있는 AIMessage에서 content를 제거하는 미들웨어.
+
+    LLM이 content + tool_calls를 동시에 보내면 content는 할루시네이션.
+    UI에서만 폐기하면 context에 누적되어 토큰 초과 원인이 됨.
+    after_model에서 AIMessage.content를 비워 context 절약.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _StripContentOnToolCall(AgentMiddleware):
+        def after_model(self, state, runtime=None):  # noqa: ARG002
+            from langchain_core.messages import AIMessage
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            last = messages[-1]
+            if (
+                not isinstance(last, AIMessage)
+                or not last.tool_calls
+                or not last.content
+            ):
+                return None
+
+            # tool_calls가 있으면 content 제거
+            stripped = last.model_copy(update={"content": ""})
+            new_messages = list(messages[:-1]) + [stripped]
+            logger.info(
+                "[RAG] Stripped %d chars content from AIMessage with tool_calls",
+                len(last.content),
+            )
+            return {"messages": new_messages}
+
+        async def aafter_model(self, state, runtime=None):  # noqa: ARG002
+            return self.after_model(state, runtime)
+
+    return _StripContentOnToolCall
+
+
+def _create_tool_call_dedupe_middleware_class():
+    """LLM 응답의 tool_calls에서 (name, args) 중복 제거.
+
+    gpt-oss-120b의 harmony tool format이 vLLM에서 같은 호출을 여러 번
+    emit하는 케이스 방어. LangGraph는 dedupe 없이 tool_calls 배열 전체를
+    parallel dispatch하므로 Athena 등 외부 호출이 N배로 늘어남.
+    args가 다르면 별개로 취급되어 정상 실행됨.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _ToolCallDedupe(AgentMiddleware):
+        def after_model(self, state, runtime=None):  # noqa: ARG002
+            from langchain_core.messages import AIMessage
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+            last = messages[-1]
+            if not isinstance(last, AIMessage):
+                return None
+            tcs = last.tool_calls
+            if not tcs or len(tcs) <= 1:
+                return None
+
+            seen = set()
+            deduped = []
+            for tc in tcs:
+                key = (
+                    tc.get("name"),
+                    json.dumps(tc.get("args", {}), sort_keys=True, default=str),
+                )
+                if key in seen:
+                    print(
+                        f"[RAG] dedupe duplicate tool_call: "
+                        f"{tc.get('name')} args={tc.get('args')}",
+                        flush=True,
+                    )
+                    continue
+                seen.add(key)
+                deduped.append(tc)
+            if len(deduped) == len(tcs):
+                return None
+
+            stripped = last.model_copy(update={"tool_calls": deduped})
+            new_messages = list(messages[:-1]) + [stripped]
+            return {"messages": new_messages}
+
+        async def aafter_model(self, state, runtime=None):  # noqa: ARG002
+            return self.after_model(state, runtime)
+
+    return _ToolCallDedupe
+
+
+def _create_snapshot_answer_middleware_class():
+    """get_iceberg_snapshots tool 결과 ToolMessage에 답변 가이드 지시 추가.
+
+    Athena의 committed_at이 UTC ISO8601이므로 KST 변환 + 사용자 질문
+    의도에 맞춘 답변을 LLM에 강제. rag_search의 evidence reflection과
+    동일하게 awrap_tool_call로 ToolMessage content를 후처리.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _SnapshotAnswer(AgentMiddleware):
+        async def awrap_tool_call(self, request, handler):
+            tc = getattr(request, "tool_call", {})
+            tool_name = tc.get("name", "") if isinstance(tc, dict) else ""
+            if "get_iceberg_snapshots" not in tool_name:
+                return await handler(request)
+
+            result = await handler(request)
+
+            from langchain_core.messages import ToolMessage
+
+            if not isinstance(result, ToolMessage):
+                return result
+            content = result.content
+            if not isinstance(content, str):
+                return result
+
+            return ToolMessage(
+                content=content + _SNAPSHOT_ANSWER_INSTRUCTION,
+                tool_call_id=result.tool_call_id,
+                name=result.name,
+            )
+
+    return _SnapshotAnswer
+
+
+# 검색 결과 뒤 근거 지시는 `prompts.chat_rag_prompt` 다 (이슈 #178, #218 — 코드 상수 없음).
+
+# rag_search 결과에 "FAQ 검색 결과" 그룹이 있을 때 추가되는 안내.
+# LLM이 사내 누적 단답 FAQ를 참고용으로만 활용하도록 유도.
+_FAQ_CONTEXT_NOTE = (
+    "\n\n---\n"
+    '[위 "FAQ 검색 결과"는 사내에 누적된 단답 질의응답입니다.]\n'
+    "- **사용자 질문과 직접 관련된 항목**이 있을 때만 답변에 활용하세요.\n"
+    '- 관련이 약하거나 모호하면 무시하고 "가이드 검색 결과"를 우선 사용하세요.\n'
+    "- FAQ 답변을 그대로 복붙하지 말고, 사용자 질문 맥락에 맞춰 다듬어 응답하세요."
+)
+
+
+# rag_search tool result에 추가되는 evidence 분석 지시
+_EVIDENCE_REFLECTION_INSTRUCTION = (
+    "\n\n---\n"
+    "[검색 결과 분석 지시]\n"
+    "1. 검색 결과에서 **사용자 질문과 직접 관련된 부분**만 골라 답변에 사용하세요. "
+    "무관한 내용을 끌어와 나열하지 마세요. 검색 결과를 통째로 요약하지 마세요.\n"
+    "2. 정보가 부족하면 다른 검색어로 rag_search를 다시 호출하세요. "
+    "일반 지식이나 추측으로 메우지 마세요.\n"
+    '3. 검색 결과에 답이 없으면 솔직히 "검색 결과에 해당 정보가 없습니다"라고 알리고, '
+    "사용자에게 추가 정보를 요청하세요.\n"
+    "4. 검색 결과에 없는 함수명·파라미터명·설정값·경로·숫자를 임의로 추가하지 마세요. "
+    "검색 결과에 없으면 그 항목은 답변에서 빼세요.\n"
+    "5. **간결하게 답변하세요.** 핵심만 포함하고 불필요한 서론이나 중복 설명을 넣지 마세요.\n"
+    "6. 음슴체(~한다/~함) 결과여도 반드시 대화체(~합니다)로 변환해서 답변하세요."
+)
+
+# rag_search 가 모든 검색에 실패했을 때(success: False) 위 지시 대신 붙는다 (이슈 #156).
+# 위 3번("답이 없으면 '해당 정보가 없습니다'")이 붙으면 장애가 틀린 답으로 바뀐다.
+_SEARCH_FAILED_INSTRUCTION = (
+    "\n\n---\n"
+    "[검색 실패 안내]\n"
+    "검색 시스템 오류로 검색이 실행되지 않았습니다(위 errors 참고). "
+    "결과가 없는 것이 아닙니다.\n"
+    '1. "검색 결과에 해당 정보가 없습니다"라고 답하지 마세요.\n'
+    "2. 사용자에게 검색 중 오류가 발생했다고 알리고, 잠시 후 다시 시도하도록 안내하세요.\n"
+    "3. 일반 지식이나 추측으로 답을 만들지 마세요."
+)
+
+
+def _search_failed(content: str) -> bool:
+    """rag_search 결과가 전체 실패(`success: False`)인지."""
+    try:
+        data = json.loads(content)
+    except (json.JSONDecodeError, TypeError):
+        return False
+    return isinstance(data, dict) and data.get("success") is False
+
+
+# get_iceberg_snapshots tool result에 추가되는 답변 가이드 지시.
+# Athena가 committed_at을 UTC ISO8601로 반환하므로 KST 변환 강제.
+_SNAPSHOT_ANSWER_INSTRUCTION = (
+    "\n\n---\n"
+    "[적재 이력 분석 지시]\n"
+    "1. **committed_at은 UTC 시각**입니다. 사용자에게 답변할 때 반드시 "
+    "**KST(UTC+9)로 변환**해서 표시하세요. "
+    '예: "2026-06-09T03:15:00.000Z" → "2026-06-09 12:15 (KST)".\n'
+    "2. **결과를 그대로 나열하지 마세요.** 사용자 질문 의도에 맞춰 답하세요.\n"
+    '   - "최근 적재 시각" → 가장 최근 1건만 KST로 답변\n'
+    '   - "적재 빈도/주기" → 적재 간격 또는 일·시간 단위 빈도 분석\n'
+    '   - "최근 N건" → 명시된 N건만 KST 시각으로 정리\n'
+    "3. snapshot_id, parent_id 같은 내부 식별자는 사용자가 명시적으로 "
+    "물어보지 않는 한 답변에서 빼세요.\n"
+    "4. operation, added/deleted/total records는 사용자가 적재 변동·증가량을 "
+    "물어봤을 때만 활용하세요.\n"
+    "5. **간결하게 답변하세요.** 표/리스트는 필요한 경우만 사용하고 핵심을 먼저 제시하세요."
+)
+
+
+# CRAG: 검색 결과 불충분 판정 시 사용하는 지시
+_EVIDENCE_INSUFFICIENT_INSTRUCTION = (
+    "\n\n---\n"
+    "[검색 결과 품질 평가: 불충분]\n"
+    "검색 결과가 사용자 질문에 답하기에 불충분합니다.\n"
+    "1. 다른 검색어나 다른 컬렉션으로 rag_search를 다시 호출하세요.\n"
+    "2. 재검색으로도 정보를 찾지 못하면, "
+    "'해당 정보를 찾을 수 없습니다. 관련 문서를 직접 참고하세요'라고 안내하세요.\n"
+    "3. **절대로 검색 결과에 없는 내용을 만들어내지 마세요.**"
+)
+
+# 반복 검색 감지 시 사용하는 지시 (이전 결과 활용 권장)
+_EVIDENCE_STOP_SEARCH_INSTRUCTION = (
+    "\n\n---\n"
+    "[행동 지시]\n"
+    "위에 이전 검색에서 수집한 실제 데이터가 첨부되어 있습니다. "
+    "이 데이터를 정독하고 그것을 근거로 답변을 작성하세요.\n"
+    "\n"
+    "**필수**:\n"
+    "- '해당 정보를 찾을 수 없습니다' / '검색 결과에 내용이 없습니다' 같은 답변 금지. "
+    "위 데이터에 충분한 정보가 있습니다.\n"
+    "- 이전 턴의 ToolMessage들도 컨텍스트에 남아있으니 함께 활용하세요.\n"
+    "- 데이터가 정말 부족한 부분만 의미적으로 다른 키워드로 재검색 — 같은 키워드 재시도 금지."
+)
+
+
+def _cosine_sim(a: list, b: list) -> float:
+    """두 벡터의 cosine similarity (순수 Python, 패키지 불필요)."""
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = sum(x * x for x in a) ** 0.5
+    norm_b = sum(x * x for x in b) ** 0.5
+    return dot / (norm_a * norm_b) if norm_a and norm_b else 0.0
+
+
+# 반복 검색 감지(cosine skip) 대상 컬렉션
+_GUIDE_COLLECTIONS = {"guide_docs", "ds_guide_docs"}
+
+_REPETITIVE_SEARCH_THRESHOLD = 0.85
+_CHUNK_OVERLAP_THRESHOLD = 0.7  # 결과 chunk 70% 이상 중복이면 중단
+
+# search_l2_table을 한 턴에 2번째로 호출하려 할 때 주입하는 차단 지시.
+# 자동 페이지네이션 루프(offset을 계속 올려 후보를 소진하되 사용자에겐 안 보여줌) 방지.
+_L2_PAGING_STOP_INSTRUCTION = (
+    "[중단: 이번 턴에 L2 검색은 이미 1회 수행했습니다]\n"
+    "추가로 search_l2_table을 호출하지 마세요. 직전 호출에서 받은 candidates(후보 "
+    "테이블명 목록)를 **지금 사용자에게 그대로 나열해서 보여주고** 어떤 테이블인지 "
+    "확인을 요청하세요. more_candidates_count가 있으면 '이 외에 N개가 더 있습니다, "
+    "더 구체적인 이름을 알려주시면 좁혀드릴게요'라고만 덧붙이세요. **다음 페이지는 "
+    "사용자가 다시 요청할 때만** 가져옵니다 — 지금 이어서 조회하지 마세요."
+)
+
+
+def _extract_chunk_ids(content: str) -> set:
+    """rag_search 결과 JSON에서 chunk 식별자 집합을 추출.
+
+    각 컬렉션의 result item 형식이 다르므로 우선순위로 ID 생성:
+    1. `id` 필드 (가이드/테이블 컬렉션)
+    2. `payload.id` (legacy)
+    """
+    ids: set = set()
+    try:
+        parsed = json.loads(content) if isinstance(content, str) else content
+        if not isinstance(parsed, dict):
+            return ids
+        for key in ("테이블 검색 결과", "가이드 검색 결과"):
+            for item in parsed.get(key, []):
+                if not isinstance(item, dict):
+                    continue
+                pid = item.get("id") or item.get("payload", {}).get("id")
+                if pid:
+                    ids.add(str(pid))
+    except Exception:
+        pass
+    return ids
+
+
+def _create_evidence_reflection_middleware_class(
+    reflection_instruction: str = _EVIDENCE_REFLECTION_INSTRUCTION,
+):
+    """rag_search tool result에 evidence 분석 지시를 추가하는 미들웨어.
+
+    `reflection_instruction` 은 검색이 성공했을 때 붙는 지시다. 채팅 답을 전제로 한
+    기본값("대화체로", "추가 정보를 요청") 대신 노트북 자동생성은 자기 문구를 준다(이슈 #155).
+
+    두 가지 중복 감지 메커니즘:
+    1. 임베딩 cosine similarity: 쿼리가 의미적으로 동일한지 (입력 관점)
+    2. Chunk ID 중복률: 검색 결과가 이전과 겹치는지 (출력 관점)
+    어느 하나라도 중복으로 판단하면 재검색 중단 지시.
+
+    - guide_docs 계열만 추적, 테이블 검색은 통과
+    - 병렬 호출은 pending에 모아뒀다가 before_model에서 확정
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _EvidenceReflection(AgentMiddleware):
+        def __init__(self):
+            super().__init__()
+            # 임베딩 벡터 추적 (쿼리 유사도)
+            self._searched_embeddings: list = []
+            self._pending_embeddings: list = []
+            # chunk ID 추적 (결과 중복률)
+            self._seen_chunk_ids: set = set()
+            # 검색 결과 캐시 — _searched_embeddings 와 인덱스 정렬
+            # skip 발생 시 매칭되는 이전 결과를 다시 첨부하기 위함
+            self._search_cache: list[str] = []
+            self._pending_cache: list[str] = []
+            # 동일 query 누적 반복 카운트 (LLM stuck 패턴 차단용)
+            # cosine ≥ _REPETITIVE_SEARCH_THRESHOLD 인 query를 normalize 후 카운트
+            self._query_repeat_counts: dict = {}
+            # search_l2_table 턴당 호출 카운터 (자동 페이지네이션 루프 차단용)
+            self._l2_call_count: int = 0
+
+        def reset(self):
+            """턴 시작 시 호출하여 누적 상태 초기화."""
+            self._searched_embeddings.clear()
+            self._pending_embeddings.clear()
+            self._seen_chunk_ids.clear()
+            self._search_cache.clear()
+            self._pending_cache.clear()
+            self._query_repeat_counts.clear()
+            self._l2_call_count = 0
+
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            """LLM 호출 직전: pending 벡터/캐시를 확정 목록으로 이동 (라운드 경계)."""
+            if self._pending_embeddings:
+                self._searched_embeddings.extend(self._pending_embeddings)
+                self._pending_embeddings.clear()
+            if self._pending_cache:
+                self._search_cache.extend(self._pending_cache)
+                self._pending_cache.clear()
+            return None
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+        async def awrap_tool_call(self, request, handler):
+            tc = getattr(request, "tool_call", {})
+            tool_name = tc.get("name", "") if isinstance(tc, dict) else ""
+
+            # ── search_l2_table 자동 페이지네이션 루프 차단 ──
+            # gpt-oss가 tool 결과의 next_candidate_offset을 보고 한 턴에 offset을
+            # 계속 올리며 후보를 다 소진하되 사용자에겐 아무것도 안 보여주는 문제.
+            # 턴당 1회만 실제 실행하고, 2번째부터는 synthetic ToolMessage로 차단해
+            # "가진 후보를 사용자에게 나열해 보여주고 멈추라"고 지시.
+            if "search_l2_table" in tool_name:
+                self._l2_call_count += 1
+                if self._l2_call_count > 1:
+                    print(
+                        f"[RAG] EvidenceReflection: search_l2_table paging blocked "
+                        f"(call #{self._l2_call_count} this turn) "
+                        f"— returning synthetic ToolMessage",
+                        flush=True,
+                    )
+                    from langchain_core.messages import ToolMessage
+
+                    return ToolMessage(
+                        content=_L2_PAGING_STOP_INSTRUCTION,
+                        tool_call_id=tc.get("id", "") if isinstance(tc, dict) else "",
+                        name="search_l2_table",
+                    )
+                return await handler(request)
+
+            if "rag_search" not in tool_name:
+                return await handler(request)
+
+            # guide_docs 계열 쿼리 추출
+            guide_queries: list = []
+            try:
+                args = tc.get("args", {}) if isinstance(tc, dict) else {}
+                queries_str = args.get("queries", "") if isinstance(args, dict) else ""
+                if queries_str:
+                    q_list = (
+                        json.loads(queries_str)
+                        if isinstance(queries_str, str)
+                        else queries_str
+                    )
+                    for q in q_list if isinstance(q_list, list) else []:
+                        if not isinstance(q, dict):
+                            continue
+                        col = q.get("collection", "")
+                        if col in _GUIDE_COLLECTIONS:
+                            guide_queries.append(q.get("query", ""))
+            except Exception:
+                pass
+
+            # ── 검색 전 임베딩 유사도 체크 (쿼리 관점) ──
+            # 이전 라운드와 동일 주제이면 검색 자체를 스킵
+            if guide_queries:
+                combined_query = " ".join(guide_queries)
+                try:
+                    from codebuff_core.services.vllm_embedding_service import (
+                        get_vllm_embedding_service,
+                    )
+
+                    emb_service = get_vllm_embedding_service()
+                    current_vec = await emb_service.embed_query(combined_query)
+
+                    max_sim = 0.0
+                    best_idx = -1
+                    for i, prev_vec in enumerate(self._searched_embeddings):
+                        sim = _cosine_sim(current_vec, prev_vec)
+                        if sim > max_sim:
+                            max_sim = sim
+                            best_idx = i
+
+                    print(
+                        f"[RAG] EvidenceReflection: PRE-CHECK "
+                        f"query={combined_query[:80]!r} "
+                        f"max_sim={max_sim:.3f} "
+                        f"prev_count={len(self._searched_embeddings)}",
+                        flush=True,
+                    )
+
+                    if max_sim > _REPETITIVE_SEARCH_THRESHOLD:
+                        # 동일 query 누적 카운트 (normalize 후 dict 키)
+                        norm_query = " ".join(combined_query.lower().split())
+                        repeat_count = self._query_repeat_counts.get(norm_query, 0) + 1
+                        self._query_repeat_counts[norm_query] = repeat_count
+                        print(
+                            f"[RAG] EvidenceReflection: SKIP search "
+                            f"(cosine={max_sim:.3f}, repeat#{repeat_count}) "
+                            f"— idx={best_idx}",
+                            flush=True,
+                        )
+                        self._pending_embeddings.append(current_vec)
+                        self._pending_cache.append("")  # skip은 캐시 추가 안 함
+                        from langchain_core.messages import ToolMessage
+
+                        cached_content = (
+                            self._search_cache[best_idx]
+                            if 0 <= best_idx < len(self._search_cache)
+                            else ""
+                        )
+
+                        # 동일 query 반복 시 — 항상 cached 데이터를 보여주되,
+                        # 횟수에 따라 헤더 메시지 톤만 변화. "차단됨" 단어 회피 —
+                        # LLM이 이를 "데이터 없음"으로 잘못 해석하는 문제 방지.
+                        if repeat_count == 1:
+                            note = (
+                                f"[재검색 불필요 — 직전 결과 재제공] "
+                                f"이미 유사한 쿼리(cosine={max_sim:.2f})로 검색한 "
+                                f"기록이 있어 동일 결과가 반환됩니다. 아래 데이터를 "
+                                f"활용해 답변하거나, 의미적으로 **다른 키워드**로 "
+                                f"새 검색을 시도하세요."
+                            )
+                        elif repeat_count == 2:
+                            note = (
+                                f"[동일 검색 {repeat_count}회째 — 이미 받은 데이터로 답변 작성] "
+                                f"같은 정보를 반복 조회하는 중입니다. **추가 검색 없이 "
+                                f"아래 결과만으로 즉시 답변을 작성**하세요. 다른 측면이 "
+                                f"필요하면 의미적으로 다른 키워드를 사용하세요."
+                            )
+                        else:
+                            note = (
+                                f"[동일 검색 {repeat_count}회째 — 즉시 답변 작성 필수] "
+                                f"이미 충분히 조회한 정보입니다. 아래 데이터(또는 이전 "
+                                f"턴의 ToolMessage)에 답이 있습니다. **지금 즉시 답변을 "
+                                f"작성**하세요. 추가 검색은 동일 결과만 반환합니다."
+                            )
+
+                        # 모든 경우에 cached_content 그대로 첨부 (있을 때만)
+                        if cached_content:
+                            body = note + "\n\n---\n[이전 검색 결과]\n" + cached_content
+                        else:
+                            body = note
+                        body += _EVIDENCE_STOP_SEARCH_INSTRUCTION
+
+                        return ToolMessage(
+                            content=body,
+                            tool_call_id=getattr(request, "tool_call", {}).get(
+                                "id", ""
+                            ),
+                            name="rag_search",
+                        )
+
+                    self._pending_embeddings.append(current_vec)
+                except Exception as e:
+                    print(
+                        f"[RAG] EvidenceReflection: embedding pre-check failed: {e}",
+                        flush=True,
+                    )
+
+            # ── 검색 실행 ──
+            result = await handler(request)
+            content = result.content if hasattr(result, "content") else str(result)
+
+            # guide_queries가 있을 때 검색 결과를 캐시 (skip 발생 시 재첨부용)
+            # _pending_embeddings에 방금 append된 벡터와 인덱스 일치하도록 같이 append
+            if guide_queries:
+                self._pending_cache.append(content)
+
+            # FAQ 검색 결과 존재 여부 (있으면 안내 prefix 부착)
+            _faq_note = ""
+            try:
+                _peek = json.loads(content)
+                if isinstance(_peek, dict) and _peek.get("FAQ 검색 결과"):
+                    _faq_note = _FAQ_CONTEXT_NOTE
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+            failed = _search_failed(content)
+
+            # guide_docs 쿼리가 없으면 (테이블 검색만) → 일반 지시
+            if not guide_queries:
+                from langchain_core.messages import ToolMessage
+
+                instruction = (
+                    _SEARCH_FAILED_INSTRUCTION if failed else reflection_instruction
+                )
+                return ToolMessage(
+                    content=content + _faq_note + instruction,
+                    tool_call_id=getattr(result, "tool_call_id", ""),
+                    name=getattr(result, "name", None),
+                )
+
+            # ── 검색 후 chunk ID 중복률 체크 (결과 관점) ──
+            is_repetitive = False
+            current_ids = _extract_chunk_ids(content)
+            if current_ids and self._seen_chunk_ids:
+                overlap = current_ids & self._seen_chunk_ids
+                overlap_ratio = len(overlap) / len(current_ids) if current_ids else 0
+                if overlap_ratio >= _CHUNK_OVERLAP_THRESHOLD:
+                    is_repetitive = True
+                print(
+                    f"[RAG] EvidenceReflection: chunk_ids={len(current_ids)} "
+                    f"overlap={overlap_ratio:.0%} repetitive={is_repetitive}",
+                    flush=True,
+                )
+            self._seen_chunk_ids.update(current_ids)
+
+            from langchain_core.messages import ToolMessage
+
+            if failed:
+                instruction = _SEARCH_FAILED_INSTRUCTION
+            elif is_repetitive:
+                instruction = _EVIDENCE_STOP_SEARCH_INSTRUCTION
+            else:
+                instruction = reflection_instruction
+
+            return ToolMessage(
+                content=content + _faq_note + instruction,
+                tool_call_id=getattr(result, "tool_call_id", ""),
+                name=getattr(result, "name", None),
+            )
+
+    return _EvidenceReflection
+
+
+_ENTITY_PATTERNS = [
+    re.compile(r"`([^`]+)`"),  # 백틱 내 용어
+    re.compile(
+        r"[a-z][a-z0-9]*(?:[_\-][a-z0-9]+){2,}"
+    ),  # snake/kebab 2+ (예: target-file-size-bytes)
+    re.compile(
+        r"[a-z][a-z0-9]*(?:\.[a-z_][a-z0-9_]*)+"
+    ),  # dot 표기 (예: system.rewrite_data_files)
+    re.compile(r"s3://[^\s\"',)]+"),  # S3 경로
+    re.compile(r"\d+\s*(?:MB|GB|TB|KB|ms|초|분|시간|일|회|개)\b"),  # 숫자+단위
+]
+
+# after_model 트리거 임계값: 응답에만 있는 미확인 개체 수
+_UNGROUNDED_ENTITY_THRESHOLD = 5
+
+
+def _extract_entities(text: str) -> set:
+    """텍스트에서 구체적 개체(함수명, 경로, 숫자+단위 등)를 추출."""
+    entities: set = set()
+    for pat in _ENTITY_PATTERNS:
+        for m in pat.finditer(text):
+            val = m.group(1) if m.lastindex else m.group(0)
+            val = val.strip().lower()
+            if len(val) > 2:
+                entities.add(val)
+    return entities
+
+
+def _create_rag_grounding_middleware_class(constraint_text: Optional[str] = None):
+    """ToolMessage 직후 LLM 호출 전 grounding constraint를 주입하는 미들웨어.
+
+    핵심 동작:
+    1. 마지막 메시지가 ToolMessage일 때만 발동.
+    2. 이전 라운드에 주입했던 grounding HumanMessage들을 모두 제거(누적 방지).
+    3. 현재 턴의 사용자 원본 질문(가장 최근 grounding 아닌 HumanMessage)을
+       constraint 텍스트 상단에 echo하여 LLM이 항상 질문을 인식하도록 함.
+    4. 그 turn 안에서 이미 시도한 rag_search 쿼리 옵션을 constraint 끝에 부착하여
+       "이전과 다른 쿼리로 재검색" 지시가 구체적인 회피 키워드를 갖도록 함.
+    5. 새 grounding HumanMessage는 additional_kwargs에 _rag_grounding 플래그를
+       박아 다음 라운드에서 식별/제거 가능하게 한다.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    from codebuff_core.managers.config_manager import prompt_value
+
+    # 호출부 문구(노트북·EDA) > `prompts.chat_rag_prompt` (이슈 #178, #218)
+    _constraint = constraint_text or prompt_value("chat_rag_prompt")
+    _GROUNDING_FLAG = "_rag_grounding"
+
+    def _is_grounding(m: Any) -> bool:
+        return bool(
+            getattr(m, "additional_kwargs", None)
+            and m.additional_kwargs.get(_GROUNDING_FLAG)
+        )
+
+    def _format_query_entry(q: Any) -> str:
+        """rag_search queries 한 항목 → 사람이 읽기 쉬운 한 줄."""
+        if not isinstance(q, dict):
+            return str(q)
+        qt = (q.get("query") or "").strip()
+        parts: List[str] = []
+        if qt:
+            parts.append(f'"{qt}"')
+        for key in ("collection", "type"):
+            v = q.get(key)
+            if v:
+                parts.append(f"{key}={v}")
+        mt = q.get("match_text")
+        if mt:
+            parts.append(f"match_text={mt}")
+        return " / ".join(parts) if parts else str(q)
+
+    def _extract_prior_queries(messages_after_user: List[Any]) -> List[str]:
+        """이번 턴 안에서 호출된 rag_search 쿼리 목록 추출."""
+        import json as _json
+        from langchain_core.messages import AIMessage
+
+        out: List[str] = []
+        seen: set = set()
+        for m in messages_after_user:
+            if not isinstance(m, AIMessage):
+                continue
+            tcs = getattr(m, "tool_calls", None) or []
+            for tc in tcs:
+                if tc.get("name") != "rag_search":
+                    continue
+                args = tc.get("args") or {}
+                raw = args.get("queries", "")
+                parsed = raw
+                if isinstance(raw, str):
+                    try:
+                        parsed = _json.loads(raw)
+                    except Exception:
+                        parsed = raw
+                if isinstance(parsed, dict):
+                    parsed = [parsed]
+                if not isinstance(parsed, list):
+                    continue
+                for q in parsed:
+                    entry = _format_query_entry(q)
+                    if entry and entry not in seen:
+                        seen.add(entry)
+                        out.append(entry)
+        return out
+
+    class _RagGrounding(AgentMiddleware):
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            from langchain_core.messages import HumanMessage, ToolMessage
+            from langchain_core.messages import RemoveMessage
+            from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            # 마지막 메시지가 ToolMessage인 경우에만 inject
+            last_msg = messages[-1]
+            if not isinstance(last_msg, ToolMessage):
+                return None
+
+            # 1) 이전 grounding HumanMessage 제거 (누적 방지)
+            filtered: List[Any] = [m for m in messages if not _is_grounding(m)]
+
+            # 2) 현재 턴 user 질문 = 가장 최근의 grounding 아닌 HumanMessage
+            user_question = ""
+            last_user_idx = -1
+            for idx, m in enumerate(filtered):
+                if isinstance(m, HumanMessage):
+                    user_question = (
+                        (m.content or "").strip()
+                        if isinstance(m.content, str)
+                        else str(m.content)
+                    )
+                    last_user_idx = idx
+
+            # 3) 사용자 메시지 이후의 rag_search 쿼리 누적
+            prior_queries = _extract_prior_queries(
+                filtered[last_user_idx + 1 :] if last_user_idx >= 0 else filtered
+            )
+
+            # 4) constraint 조립: 헤더(user 질문) + 본문 + (prior queries)
+            sections: List[str] = []
+            if user_question:
+                _uq = user_question[:1000]  # 매우 긴 질문 대비 cap
+                sections.append(f"[사용자 원본 질문]\n{_uq}")
+            sections.append(_constraint)
+            if prior_queries:
+                _lines = "\n".join(f"  - {q}" for q in prior_queries[:20])
+                sections.append(
+                    "[이미 시도한 rag_search 쿼리 — 다시 검색할 경우 이 키워드/조합과 "
+                    "구분되는 새 쿼리를 사용하세요]\n" + _lines
+                )
+
+            final_constraint = "\n\n".join(sections)
+
+            new_grounding = HumanMessage(
+                content=final_constraint,
+                additional_kwargs={_GROUNDING_FLAG: True},
+            )
+
+            return {
+                "messages": [
+                    RemoveMessage(id=REMOVE_ALL_MESSAGES),
+                    *filtered,
+                    new_grounding,
+                ]
+            }
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+    return _RagGrounding
+
+
+# tiktoken 인코더 싱글톤 캐시
+_tiktoken_enc = None
+_tiktoken_available = None  # None=미확인, True/False
+
+
+def _get_tiktoken_encoder():
+    """tiktoken 인코더를 한 번만 초기화. 패키지 내장 캐시를 사용하여 오프라인 지원."""
+    global _tiktoken_enc, _tiktoken_available  # noqa: PLW0603
+    if _tiktoken_enc is not None:
+        return _tiktoken_enc
+
+    import os
+
+    import tiktoken
+
+    # 패키지 내장 캐시 디렉토리를 TIKTOKEN_CACHE_DIR로 설정
+    if "TIKTOKEN_CACHE_DIR" not in os.environ:
+        cache_dir = str(Path(__file__).parent.parent / "data" / "tiktoken_cache")
+        if Path(cache_dir).is_dir():
+            os.environ["TIKTOKEN_CACHE_DIR"] = cache_dir
+
+    _tiktoken_enc = tiktoken.get_encoding("cl100k_base")
+    _tiktoken_available = True
+    return _tiktoken_enc
+
+
+CHUNK_SIZE = 10000  # 분할 인코딩 단위 (큰 텍스트 O(n²) 방지)
+
+
+def _count_tokens_text(enc, text: str) -> int:
+    """큰 텍스트를 청크로 분할 후 batch 인코딩하여 토큰 수 반환."""
+    if len(text) <= CHUNK_SIZE:
+        return len(enc.encode(text))
+    chunks = [text[i : i + CHUNK_SIZE] for i in range(0, len(text), CHUNK_SIZE)]
+    results = enc.encode_ordinary_batch(chunks)
+    return sum(len(r) for r in results)
+
+
+def _estimate_tokens(messages) -> int:
+    """tiktoken으로 메시지 토큰 수 추정. 실패 시 한국어 보수적 추정(2자/토큰) 폴백."""
+    global _tiktoken_available  # noqa: PLW0603
+
+    if _tiktoken_available is False:
+        return _estimate_tokens_fallback(messages)
+
+    try:
+        enc = _get_tiktoken_encoder()
+        total = 0
+        for msg in messages:
+            content = msg.content if hasattr(msg, "content") else str(msg)
+            total += _count_tokens_text(enc, content) + 4
+            if hasattr(msg, "tool_calls") and msg.tool_calls:
+                tc_str = str(msg.tool_calls)
+                total += _count_tokens_text(enc, tc_str)
+        print(
+            f"[RAG] tiktoken estimate: {total} tokens ({len(messages)} messages)",
+            flush=True,
+        )
+        return total
+    except Exception as e:
+        _tiktoken_available = False
+        print(f"[RAG] tiktoken unavailable, using fallback: {e}", flush=True)
+        return _estimate_tokens_fallback(messages)
+
+
+def _estimate_tokens_fallback(messages) -> int:
+    """tiktoken 없을 때 폴백. 한국어 보수적 추정 (2자/토큰)."""
+    total = 0
+    for msg in messages:
+        content = msg.content if hasattr(msg, "content") else str(msg)
+        total += len(content) // 2 + 4
+        if hasattr(msg, "tool_calls") and msg.tool_calls:
+            total += len(str(msg.tool_calls)) // 2
+    print(
+        f"[RAG] token estimate (fallback): {total} tokens ({len(messages)} messages)",
+        flush=True,
+    )
+    return total
+
+
+def _create_context_compression_middleware_class(model_context_limit: int = 131072):
+    """LLM 호출 전 토큰 사전 체크 + 점진적 ToolMessage 축소 미들웨어.
+
+    1. score 낮은 검색 결과부터 점진적 삭제
+    2. 마지막 1개 남으면 columns 제거 + content 2000자 컷
+    3. 87.5% 초과 시 더 공격적 축약
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    # 시스템 프롬프트 + tools 스키마 오버헤드 감안 (메시지만 세므로 보수적)
+    SOFT_LIMIT = int(model_context_limit * 0.5)
+    HARD_LIMIT = int(model_context_limit * 0.65)
+
+    class _ContextCompression(AgentMiddleware):
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            import json as _json
+
+            from langchain_core.messages import ToolMessage
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            estimated = _estimate_tokens(messages)
+            if estimated <= SOFT_LIMIT:
+                return None
+
+            # 메시지별 토큰 상세 로깅
+            for i, msg in enumerate(messages):
+                content = msg.content if hasattr(msg, "content") else ""
+                msg_tokens = len(content) // 2
+                logger.info(
+                    "[RAG] Context msg[%d] type=%s tokens≈%d chars=%d",
+                    i,
+                    type(msg).__name__,
+                    msg_tokens,
+                    len(content),
+                )
+
+            logger.info(
+                "[RAG] Context compression: estimated=%d tokens, soft=%d, hard=%d",
+                estimated,
+                SOFT_LIMIT,
+                HARD_LIMIT,
+            )
+
+            # ToolMessage 인덱스 수집
+            new_messages = list(messages)
+            changed = False
+
+            for msg_idx in range(len(new_messages) - 1, -1, -1):
+                msg = new_messages[msg_idx]
+                if not isinstance(msg, ToolMessage) or not msg.content:
+                    continue
+
+                # ToolMessage의 content를 JSON 파싱하여 결과 리스트 축소
+                # EvidenceReflection이 append한 텍스트를 strip 후 파싱
+                _raw_content = msg.content
+                _marker_pos = _raw_content.find("\n\n---\n[검색 결과 분석 지시]")
+                _json_part = (
+                    _raw_content[:_marker_pos] if _marker_pos > 0 else _raw_content
+                )
+                _suffix = _raw_content[_marker_pos:] if _marker_pos > 0 else ""
+                try:
+                    parsed = _json.loads(_json_part)
+                except (ValueError, TypeError):
+                    continue
+
+                if not isinstance(parsed, dict):
+                    continue
+
+                # 결과 리스트 키 찾기
+                result_keys = [
+                    k
+                    for k in ("테이블 검색 결과", "가이드 검색 결과")
+                    if k in parsed
+                    and isinstance(parsed[k], list)
+                    and len(parsed[k]) > 0
+                ]
+
+                if not result_keys:
+                    continue
+
+                # Step 1: (결과 삭제 비활성화 — 컬럼 축소로 충분)
+
+                # Step 2: 모든 결과의 컬럼을 동시에 50%씩 삭감 + content 축약
+                # 기존 방식: 결과 하나씩 컬럼 0까지 → 다음 결과 (비효율적)
+                # 개선: 모든 결과 컬럼을 한 라운드에 50%씩 → estimate → 반복
+                estimated = _estimate_tokens(new_messages)
+                if estimated > SOFT_LIMIT:
+                    # 모든 결과의 payload 수집
+                    all_payloads = []
+                    for key in result_keys:
+                        for r in parsed.get(key, []):
+                            p = r.get("payload", r)
+                            if isinstance(p, dict):
+                                all_payloads.append(p)
+
+                    # 라운드별: 모든 payload의 컬럼을 동시에 50% 삭감
+                    max_rounds = 12
+                    for round_i in range(max_rounds):
+                        any_cut = False
+                        for p in all_payloads:
+                            cols = p.get("columns")
+                            if not cols or not isinstance(cols, list):
+                                continue
+                            original = len(cols)
+                            keep = max(original // 2, 0)
+                            if keep == 0:
+                                del p["columns"]
+                                p["_notice"] = (
+                                    "[토큰 제한으로 컬럼 상세 정보 전부 생략]"
+                                )
+                            else:
+                                p["columns"] = cols[:keep]
+                                p["_notice"] = (
+                                    f"[토큰 제한으로 컬럼 {original} → {keep}개]"
+                                )
+                            any_cut = True
+
+                        if not any_cut:
+                            break
+
+                        changed = True
+                        new_content = (
+                            _json.dumps(parsed, ensure_ascii=False, default=str)
+                            + _suffix
+                        )
+                        new_messages[msg_idx] = ToolMessage(
+                            content=new_content,
+                            tool_call_id=msg.tool_call_id,
+                            name=getattr(msg, "name", None),
+                        )
+                        estimated = _estimate_tokens(new_messages)
+                        print(
+                            f"[RAG] Compression round {round_i + 1}: "
+                            f"{estimated} tokens",
+                            flush=True,
+                        )
+                        if estimated <= SOFT_LIMIT:
+                            break
+
+                    # 컬럼 전부 제거 후에도 초과 → content 50%씩 축약
+                    if estimated > SOFT_LIMIT:
+                        for p in all_payloads:
+                            ct = p.get("content", "")
+                            if not ct or not isinstance(ct, str):
+                                continue
+                            original_len = len(ct)
+                            while (
+                                estimated > SOFT_LIMIT
+                                and len(p.get("content", "")) > 200
+                            ):
+                                cur = len(p["content"])
+                                keep = max(cur // 2, 200)
+                                p["content"] = p["content"][:keep]
+                                p["_content_notice"] = (
+                                    f"[토큰 제한으로 원문 {original_len} → {keep}자]"
+                                )
+                                changed = True
+                                new_content = (
+                                    _json.dumps(parsed, ensure_ascii=False, default=str)
+                                    + _suffix
+                                )
+                                new_messages[msg_idx] = ToolMessage(
+                                    content=new_content,
+                                    tool_call_id=msg.tool_call_id,
+                                    name=getattr(msg, "name", None),
+                                )
+                                estimated = _estimate_tokens(new_messages)
+
+                # Step 3: 87.5% 초과 시 더 공격적 축약
+                estimated = _estimate_tokens(new_messages)
+                if estimated > HARD_LIMIT:
+                    for key in result_keys:
+                        results = parsed.get(key, [])
+                        for r in results:
+                            payload = r.get("payload", r)
+                            if isinstance(payload, dict) and "content" in payload:
+                                if len(payload["content"]) > 500:
+                                    payload["content"] = payload["content"][:500]
+                                    payload["_content_notice"] = (
+                                        "[토큰 제한으로 원문이 500자로 축약되었습니다]"
+                                    )
+                                    changed = True
+
+                    if changed:
+                        new_content = (
+                            _json.dumps(parsed, ensure_ascii=False, default=str)
+                            + _suffix
+                        )
+                        new_messages[msg_idx] = ToolMessage(
+                            content=new_content,
+                            tool_call_id=msg.tool_call_id,
+                            name=getattr(msg, "name", None),
+                        )
+
+                # 하나의 ToolMessage 처리 후 토큰 재확인
+                estimated = _estimate_tokens(new_messages)
+                if estimated <= SOFT_LIMIT:
+                    break
+
+            if changed:
+                from langgraph.graph.message import REMOVE_ALL_MESSAGES
+                from langchain_core.messages import RemoveMessage
+
+                final_tokens = _estimate_tokens(new_messages)
+                print(
+                    f"[RAG] Context compressed: → {final_tokens} tokens",
+                    flush=True,
+                )
+                return {
+                    "messages": [
+                        RemoveMessage(id=REMOVE_ALL_MESSAGES),
+                        *new_messages,
+                    ]
+                }
+
+            return None
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+    return _ContextCompression
+
+
+def _create_summary_to_system_middleware_class():
+    """SummarizationMiddleware가 생성한 요약 HumanMessage를 SystemMessage로 변환.
+
+    SummarizationMiddleware는 요약을 HumanMessage(lc_source=summarization)로 넣는데,
+    LLM이 이를 사용자 메시지로 착각해 요약을 그대로 답변으로 출력하는 문제 방지.
+    SystemMessage로 변환하여 "이전 세션 요약"임을 명시.
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _SummaryToSystem(AgentMiddleware):
+        def before_model(self, state, runtime=None):  # noqa: ARG002
+            from langchain_core.messages import HumanMessage, SystemMessage
+
+            messages = state.get("messages", [])
+            if not messages:
+                return None
+
+            new_messages = []
+            changed = False
+            for msg in messages:
+                if (
+                    isinstance(msg, HumanMessage)
+                    and msg.additional_kwargs.get("lc_source") == "summarization"
+                ):
+                    # 요약 HumanMessage → SystemMessage로 변환
+                    summary_content = msg.content
+                    # "Here is a summary..." 접두사 제거
+                    if ":\n\n" in summary_content:
+                        summary_content = summary_content.split(":\n\n", 1)[1]
+                    new_messages.append(
+                        SystemMessage(
+                            content=(
+                                "[이전 세션 요약]\n"
+                                "다음은 이전 대화의 요약입니다. 참고만 하고, "
+                                "사용자의 현재 질문에 답변하세요.\n\n"
+                                f"{summary_content}"
+                            )
+                        )
+                    )
+                    changed = True
+                    logger.info(
+                        "[RAG] Converted summary HumanMessage → SystemMessage (%d chars)",
+                        len(summary_content),
+                    )
+                else:
+                    new_messages.append(msg)
+
+            return {"messages": new_messages} if changed else None
+
+        async def abefore_model(self, state, runtime=None):  # noqa: ARG002
+            return self.before_model(state, runtime)
+
+    return _SummaryToSystem
+
+
+def _strip_harmony_tokens(text: str) -> str:
+    """응답 텍스트에서 harmony 특수 토큰/블록 + GPT-OSS 인용 마커를 제거."""
+    if not text:
+        return text
+    # 전체 harmony 블록 제거 (tool call이 content에 섞인 경우)
+    cleaned = _HARMONY_BLOCK_RE.sub("", text)
+    # 잔여 개별 토큰 제거
+    cleaned = _HARMONY_TOKEN_RE.sub("", cleaned)
+    # GPT-OSS 인용 마커 제거 (예: [9†L1-L7])
+    cleaned = _CITATION_MARKER_RE.sub("", cleaned)
+    return cleaned.strip()
+
+
+class TableConfirmationNeeded(Exception):
+    """rag_search 결과가 불확실할 때 raise. candidates를 프론트에 전달."""
+
+    def __init__(self, candidates: dict, confirmed_tables: Optional[list] = None):
+        self.candidates = candidates
+        self.confirmed_tables = confirmed_tables or []
+        super().__init__("Table confirmation needed")
+
+
+def _create_table_confirmation_middleware_class(
+    threshold: float = 0.7,
+    excluded_table_names: Optional[list] = None,
+    mode: str = "eda",
+):
+    """rag_search 결과를 다각적으로 검토하여, 불확실하면 후보 테이블 목록으로 교체.
+
+    확정 조건 (후보 안 보여줌):
+    - 쿼리별 top score > 0.8 이고 #1-#2 gap > 0.05
+    불확실 조건 (후보 보여줌):
+    - _warnings 존재 (match_text fallback = 테이블명 미존재)
+    - 쿼리별 모든 결과 score ≤ threshold
+    - top 2 score 밀집 (gap < 0.03, 명확한 1등 없음)
+
+    mode:
+    - "eda": 불확실 시 TableConfirmationNeeded 예외 raise (EDA Agent용)
+    - "chat": 불확실 시 ToolMessage에 안내 추가 + 결과 유지 (Knowledge Chat용)
+    """
+    from langchain.agents.middleware import AgentMiddleware
+
+    class _TableConfirmation(AgentMiddleware):
+        async def awrap_tool_call(self, request, handler):
+            result = await handler(request)
+
+            # ToolCallRequest.tool_call['name'] からtool名を取得
+            tc = getattr(request, "tool_call", {})
+            tool_name = tc.get("name", "") if isinstance(tc, dict) else ""
+            if "rag_search" not in tool_name:
+                return result
+
+            content = result.content if hasattr(result, "content") else str(result)
+            try:
+                parsed = json.loads(content) if isinstance(content, str) else content
+            except Exception:
+                return result
+
+            if not isinstance(parsed, dict):
+                return result
+
+            table_results = parsed.get("테이블 검색 결과", [])
+            if not table_results:
+                return result
+
+            # _warnings 존재 = match_text fallback 발생
+            has_warnings = any(bool(r.get("_warnings")) for r in table_results)
+
+            # 쿼리별 그룹핑
+            query_groups: dict = {}
+            for r in table_results:
+                q = r.get("_query", "default")
+                query_groups.setdefault(q, []).append(r)
+
+            # excluded 테이블 이름 집합 (소문자 정규화)
+            _excluded = {str(n).lower() for n in (excluded_table_names or []) if n}
+
+            def _get_field(p: dict, *keys: str) -> str:
+                for k in keys:
+                    v = p.get(k)
+                    if v:
+                        return str(v)
+                return ""
+
+            # 쿼리별 확정/불확실 판단
+            uncertain_queries: dict = {}
+            confirmed_tables: list = []  # 자동 확정된 테이블 (top-1)
+            _assigned_tables: set = set()  # cross-group dedup: 이미 할당된 테이블
+            for q, results in query_groups.items():
+                # excluded 테이블 제거
+                if _excluded:
+                    results = [
+                        r
+                        for r in results
+                        if str(
+                            r.get("payload", {}).get("table_name")
+                            or r.get("payload", {}).get("테이블명")
+                            or ""
+                        ).lower()
+                        not in _excluded
+                    ]
+                if not results:
+                    continue
+                sorted_r = sorted(
+                    results, key=lambda x: x.get("score", 0), reverse=True
+                )
+                scores = [r.get("score", 0) for r in sorted_r]
+                top = scores[0] if scores else 0
+                second = scores[1] if len(scores) > 1 else 0
+                gap = top - second
+
+                print(
+                    f"[RAG] TableConfirmation: query='{q}' "
+                    f"top={top:.3f} second={second:.3f} gap={gap:.3f} "
+                    f"warnings={has_warnings}",
+                    flush=True,
+                )
+
+                # 정확 이름 일치 판정: 사용자가 특정 테이블명(식별자)으로 물었는데
+                # top-1 결과 이름이 정확히 일치하지 않으면, 점수가 높아도 자동 확정하지
+                # 않고 L2 폴백 경로로 보낸다. L1은 벡터 검색이라 이름이 없어도 높은
+                # 점수의 유사 결과를 반환하므로, 점수만으로 확정하면 L2를 못 탄다.
+                # 자연어 쿼리(공백/한글 문구 등 식별자 아님)는 이 게이트에서 제외.
+                def _norm_name(s: str) -> str:
+                    core = (s or "").split(":", 1)[-1].rsplit(".", 1)[-1]
+                    return core.strip().lower().replace(" ", "")
+
+                _q_core = (q or "").split(":", 1)[-1].rsplit(".", 1)[-1].strip()
+                _q_is_identifier = bool(_q_core) and re.fullmatch(
+                    r"[A-Za-z0-9_]+", _q_core
+                )
+                _top_p0 = sorted_r[0].get("payload", {})
+                _q_norm = _norm_name(q)
+                _exact_match = _q_norm in (
+                    _norm_name(
+                        _get_field(_top_p0, "table_name", "테이블명", "table_id")
+                    ),
+                    _norm_name(
+                        _get_field(_top_p0, "korean_name", "테이블한글명", "한글명")
+                    ),
+                )
+                _force_fallback = bool(_q_is_identifier) and not _exact_match
+
+                # 확정: top > 0.8 이고 #2와 gap > 0.05 (단, 식별자 조회 정확일치 실패 시 보류)
+                if top > 0.8 and gap > 0.05 and not _force_fallback:
+                    # 확정 테이블 정보 저장 (불확실 쿼리가 있을 때 함께 전달)
+                    _top_r = sorted_r[0]
+                    _top_p = _top_r.get("payload", {})
+                    confirmed_tables.append(
+                        {
+                            "table_name": _get_field(
+                                _top_p, "table_name", "테이블명", "table_id"
+                            ),
+                            "korean_name": _get_field(
+                                _top_p, "korean_name", "테이블한글명", "한글명"
+                            ),
+                            "score": _top_r.get("score", 0),
+                            "columns": _top_p.get("columns", []),
+                            "col_headers": _top_p.get("col_headers", []),
+                            "payload": {
+                                k: v
+                                for k, v in _top_p.items()
+                                if k
+                                not in (
+                                    "columns",
+                                    "col_headers",
+                                    "_embed_text",
+                                    "_content_hash",
+                                    "_collection",
+                                )
+                            },
+                            "_auto_confirmed": True,
+                        }
+                    )
+                    _assigned_tables.add(
+                        _get_field(_top_p, "table_name", "테이블명", "table_id").lower()
+                    )
+                    continue
+
+                is_uncertain = False
+                reason = ""
+
+                if _force_fallback:
+                    is_uncertain = True
+                    reason = "특정 이름 조회인데 정확 일치 없음 (L2 폴백 필요)"
+                elif has_warnings:
+                    is_uncertain = True
+                    reason = "match_text 테이블명 미존재 (fallback)"
+                elif top <= threshold:
+                    is_uncertain = True
+                    reason = f"최고 score {top:.3f} ≤ {threshold}"
+                elif len(scores) >= 2 and gap < 0.03:
+                    is_uncertain = True
+                    reason = f"top 2 밀집 ({top:.3f} vs {second:.3f})"
+
+                if is_uncertain:
+                    # 중복 제거: 테이블명 기준 + cross-group dedup
+                    seen_table_names: dict = {}
+                    for r in sorted_r:
+                        p = r.get("payload", {})
+                        tname = (
+                            p.get("table_name")
+                            or p.get("테이블명")
+                            or p.get("table_id")
+                            or r.get("id", "")
+                        )
+                        tname_lower = str(tname).lower()
+                        if (
+                            tname not in seen_table_names
+                            and tname_lower not in _assigned_tables
+                        ):
+                            seen_table_names[tname] = r
+                    deduped = list(seen_table_names.values())[:5]
+                    # 할당 기록
+                    for r in deduped:
+                        p = r.get("payload", {})
+                        tname = _get_field(p, "table_name", "테이블명", "table_id")
+                        if tname:
+                            _assigned_tables.add(tname.lower())
+
+                    if not deduped:
+                        continue  # cross-group dedup으로 후보 0건
+                    uncertain_queries[q] = {
+                        "reason": reason,
+                        "candidates": [
+                            {
+                                "table_name": _get_field(
+                                    r.get("payload", {}),
+                                    "table_name",
+                                    "테이블명",
+                                    "table_id",
+                                ),
+                                "korean_name": _get_field(
+                                    r.get("payload", {}),
+                                    "korean_name",
+                                    "테이블한글명",
+                                    "한글명",
+                                ),
+                                "score": r.get("score", 0),
+                                "description": _get_field(
+                                    r.get("payload", {}),
+                                    "description",
+                                    "설명",
+                                ),
+                                "domain": _get_field(
+                                    r.get("payload", {}),
+                                    "domain",
+                                    "도메인",
+                                ),
+                                "columns": r.get("payload", {}).get("columns", []),
+                                "col_headers": r.get("payload", {}).get(
+                                    "col_headers", []
+                                ),
+                                "payload": {
+                                    k: v
+                                    for k, v in r.get("payload", {}).items()
+                                    if k
+                                    not in (
+                                        "columns",
+                                        "col_headers",
+                                        "_embed_text",
+                                        "_content_hash",
+                                        "_collection",
+                                    )
+                                },
+                            }
+                            for r in deduped
+                        ],
+                    }
+
+            if not uncertain_queries:
+                return result
+
+            print(
+                f"[RAG] Table confirmation: "
+                f"{len(uncertain_queries)} uncertain queries "
+                f"({[v['reason'] for v in uncertain_queries.values()]})",
+                flush=True,
+            )
+
+            candidates = {q: v["candidates"] for q, v in uncertain_queries.items()}
+            if confirmed_tables:
+                print(
+                    f"[RAG] Auto-confirmed tables: "
+                    f"{[t['table_name'] for t in confirmed_tables]}",
+                    flush=True,
+                )
+
+            if mode == "chat":
+                # Knowledge Chat: 검색 결과 유지 + 후보 안내를 ToolMessage에 추가.
+                # 후보 중 쿼리와 정확히 일치하는 테이블명이 하나도 없으면(=L1에
+                # 그 이름 자체가 없다는 뜻) LLM이 유사 후보를 정답으로 오인해
+                # 바로 되묻지 않도록, 되묻기 전에 search_l2_table 폴백을 먼저
+                # 시키는 지시를 주입한다. 정확 일치 후보가 있으면(통계적으로만
+                # uncertain) 기존처럼 되묻기 안내를 유지한다.
+                # 정확 일치는 영문 테이블명 + 한글명 둘 다로 판정 (사용자가 한글명으로
+                # 검색했을 수도 있으므로). 공백은 제거해 "카드매출 일별"↔"카드매출일별"도 매칭.
+                def _norm(s: str) -> str:
+                    return (s or "").lower().replace(" ", "")
+
+                _any_exact_match = any(
+                    _norm(c.get("table_name", "")) == _norm(q)
+                    or _norm(c.get("korean_name", "")) == _norm(q)
+                    for q, cands in candidates.items()
+                    for c in cands
+                )
+                if _any_exact_match:
+                    candidate_lines = [
+                        "\n\n---\n[테이블 확인 필요]\n"
+                        "검색 결과에 유사한 테이블이 여러 개 발견되었습니다. "
+                        "사용자에게 어떤 테이블을 의미하는지 자연스럽게 물어보세요.\n"
+                    ]
+                else:
+                    _q_for_l2 = ", ".join(f'"{q}"' for q in candidates.keys())
+                    candidate_lines = [
+                        "\n\n---\n[L1에 정확 일치 없음]\n"
+                        "L1 결과에 이름이 정확히 일치하는 테이블이 없습니다. 사용자가 "
+                        "L1/원본에서만 찾으라고 명시하지 않았다면, 이어서 "
+                        f"search_l2_table을 {_q_for_l2}(으)로 호출하세요(답변 보류). "
+                        "L2에 정확 일치가 있으면 그걸로 답하고, 없으면 L1·L2 후보를 합쳐 "
+                        "각 (L1)/(L2) 표시해 함께 보여주세요.\n"
+                    ]
+                for q, cands in candidates.items():
+                    candidate_lines.append(f"\n검색어 '{q}' 후보:")
+                    for c in cands:
+                        tname = c.get("table_name", "")
+                        kname = c.get("korean_name", "")
+                        desc = c.get("description", "")[:60]
+                        candidate_lines.append(f"- {tname} ({kname}): {desc}")
+                if confirmed_tables:
+                    candidate_lines.append(
+                        "\n자동 확인된 테이블: "
+                        + ", ".join(
+                            f"{t['table_name']}({t.get('korean_name', '')})"
+                            for t in confirmed_tables
+                        )
+                    )
+                from langchain_core.messages import ToolMessage
+
+                return ToolMessage(
+                    content=content + "\n".join(candidate_lines),
+                    tool_call_id=getattr(result, "tool_call_id", ""),
+                    name=getattr(result, "name", None),
+                )
+            else:
+                # EDA Agent: 기존 방식 — 예외 raise
+                raise TableConfirmationNeeded(candidates, confirmed_tables)
+
+    return _TableConfirmation
+
+
+# 기존 chat 시스템 프롬프트 + RAG 가이드
+# ============================================================
+# 모드별 시스템 프롬프트 (완전 독립, 각자 자기완결).
+# simple 모드는 centri `prompts.chat_system_prompt`(이슈 #178), knowledge 모드는
+# `prompts.chat_qa_system_prompt`(이슈 #208)로 바꿀 수 있다.
+# EDA agent는 http_handlers.py에서 별도 system_prompt_override 사용.
+# ============================================================
+
+# 본문은 코드 상수로 두지 않는다 (이슈 #208, #218). 도구 없는 Chat(chatMode="simple")은
+# `prompts.chat_system_prompt` — Chat 과 BDP Q&A 를 합친 뒤로는 사내 검색이 꺼진 환경
+# (py<3.11 또는 features.bdp_qa_enabled=false)에서만 쓴다(#183). RAG enable 모드
+# (chatMode="knowledge")는 `prompts.chat_qa_system_prompt` 다. 정본은 centri 이고, 없으면
+# 스냅샷 기본값(`schemas/config/codebuff_config_defaults.json`)이다.
+
+
+def build_chat_mode_system_prompt(chat_mode: str) -> str:
+    """Chat/Q&A가 엔진과 무관하게 공유하는 최종 시스템 프롬프트.
+
+    simple 모드 본문은 `prompts.chat_system_prompt`(이슈 #178), knowledge 모드 본문은
+    `prompts.chat_qa_system_prompt`(이슈 #208)다. 끝에 응답 서식 규칙
+    `prompts.answer_format_rules` 를 붙인다 (이슈 #218).
+    """
+    from codebuff_core.managers.config_manager import prompt_value
+
+    rules = "\n\n" + prompt_value("answer_format_rules")
+    if chat_mode != "knowledge":
+        return with_platform_rules(prompt_value("chat_system_prompt")) + rules
+
+    prompt = prompt_value("chat_qa_system_prompt")
+    # EDA on 시 테이블 컬렉션의 match_text 인덱스 정보 동적 주입
+    eda_enabled = False
+    try:
+        from codebuff_core.managers.config_manager import get_config_manager
+
+        _cfg = get_config_manager().get_config()
+        # 없으면 켜짐, 저장된 false 만 끈다 (이슈 #229)
+        eda_enabled = _cfg.get("features", {}).get("eda_enabled", True) is not False
+    except Exception:
+        pass
+    if eda_enabled:
+        match_text_info = _get_match_text_fields_info()
+        if match_text_info:
+            prompt = prompt + "\n\n" + match_text_info
+
+    # 사내 BDP: boto3 대신 bdpengine (이슈 #120)
+    return with_platform_rules(prompt) + rules
+
+
+def _has_table_results(content: str) -> bool:
+    """EDA 가 다음 단계에 넘길 테이블 문맥인가 — LangChain 경로의 판정과 같은 키를 본다."""
+    try:
+        parsed = json.loads(content)
+    except (json.JSONDecodeError, TypeError):
+        return False
+    return isinstance(parsed, dict) and (
+        "테이블 검색 결과" in parsed or "table_results" in parsed
+    )
+
+
+class CodexQAToolPostprocessor:
+    """기존 Knowledge Chat 도구 미들웨어를 Codex dynamic tool에 적용한다.
+
+    도구 구현만 재사용하면 검색 결과의 후보 안내·근거 지시·반복 제한·스냅샷
+    KST 규칙이 사라진다. LangChain ToolMessage 경계를 얇게 흉내 내 동일 미들웨어를
+    그대로 통과시키고, Codex에는 최종 content만 돌려준다.
+
+    grounding 은 구 경로에서 `before_model` 에 사람 메시지로 끼워 넣었다. codex 에는
+    그 자리가 없으므로 같은 미들웨어가 만든 문구를 도구 결과 끝에 붙인다 — 모델이
+    그 결과를 읽는 바로 그 시점이라 위치가 같다.
+    """
+
+    def __init__(
+        self,
+        table_confirm_mode: str = "chat",
+        table_score_threshold: float = 0.7,
+        excluded_table_names: Optional[list] = None,
+        grounding_constraint: Optional[str] = None,
+        evidence_instruction: Optional[str] = None,
+    ) -> None:
+        self.table_confirm_mode = table_confirm_mode
+        self.grounding_constraint = grounding_constraint
+        self._snapshot = _create_snapshot_answer_middleware_class()()
+        self._evidence = (
+            _create_evidence_reflection_middleware_class()()
+            if evidence_instruction is None
+            else _create_evidence_reflection_middleware_class(evidence_instruction)()
+        )
+        # "off": 되물을 사용자가 없는 한 턴(노트북 자동생성)이라 후보 안내도 턴 중단도 안 한다
+        self._table_confirmation = (
+            None
+            if table_confirm_mode == "off"
+            else _create_table_confirmation_middleware_class(
+                threshold=table_score_threshold,
+                excluded_table_names=excluded_table_names,
+                mode=table_confirm_mode,
+            )()
+        )
+        self._grounding = _create_rag_grounding_middleware_class(grounding_constraint)()
+        self._turn_messages: List[Any] = []
+        # EDA(`table_confirm_mode="eda"`)는 불확실한 검색에서 턴을 끊고 후보를 사용자에게
+        # 묻는다. LangChain 은 예외로 끊었지만 codex 턴은 도구 회신을 기다리므로 예외를
+        # 여기서 받아 두고, 핸들러가 턴을 취소한 뒤 SSE 로 알린다 (이슈 #155)
+        self.pending_confirmation: Optional[TableConfirmationNeeded] = None
+        # 마지막 테이블 검색 원문 — LangChain 은 agent state 에서 꺼냈다 (이슈 #155).
+        # 우선순위도 그쪽과 같다: 테이블 결과 키가 있는 도구 결과, 없으면 마지막 도구 결과
+        self.last_table_result = ""
+        self.last_tool_result = ""
+
+    def reset(self, question: str = "") -> None:
+        """새 사용자 턴: 검색·L2 호출 횟수와 grounding 이 볼 턴 기록을 다시 쌓는다."""
+        from langchain_core.messages import HumanMessage
+
+        self._evidence.reset()
+        self._turn_messages = [HumanMessage(content=question)] if question else []
+        self.pending_confirmation = None
+        self.last_table_result = ""
+        self.last_tool_result = ""
+
+    def _grounding_text(
+        self, tool_name: str, args: Dict[str, Any], call_id: str, content: str
+    ) -> str:
+        from langchain_core.messages import AIMessage, ToolMessage
+
+        self._turn_messages.append(
+            AIMessage(
+                content="",
+                tool_calls=[{"name": tool_name, "args": args, "id": call_id}],
+            )
+        )
+        self._turn_messages.append(
+            ToolMessage(content=content, tool_call_id=call_id, name=tool_name)
+        )
+        update = self._grounding.before_model({"messages": self._turn_messages})
+        if not update:
+            return ""
+        return str(update["messages"][-1].content)
+
+    async def invoke(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        call_id: str,
+        handler: Callable[[Dict[str, Any]], Awaitable[Any]],
+    ) -> Tuple[str, Any]:
+        """도구를 한 번 실행하고 (후처리 content, 원본 결과)를 반환한다."""
+        from langchain_core.messages import ToolMessage
+
+        # 직전 검색의 pending evidence를 다음 모델 라운드 상태로 확정한다.
+        self._evidence.before_model({})
+        request = SimpleNamespace(
+            tool_call={"name": tool_name, "args": args, "id": call_id}
+        )
+        raw_holder: List[Any] = [None]
+
+        async def run_tool(_request):
+            raw = await handler(args)
+            raw_holder[0] = raw
+            content = (
+                raw if isinstance(raw, str) else json.dumps(raw, ensure_ascii=False)
+            )
+            self.last_tool_result = content
+            if _has_table_results(content):
+                self.last_table_result = content
+            return ToolMessage(
+                content=content,
+                tool_call_id=call_id or "codex-qa-tool",
+                name=tool_name,
+            )
+
+        async def confirm_tables(_request):
+            if self._table_confirmation is None:
+                return await run_tool(_request)
+            return await self._table_confirmation.awrap_tool_call(_request, run_tool)
+
+        async def reflect_evidence(_request):
+            return await self._evidence.awrap_tool_call(_request, confirm_tables)
+
+        try:
+            result = await self._snapshot.awrap_tool_call(request, reflect_evidence)
+        except TableConfirmationNeeded as needed:
+            self.pending_confirmation = needed
+            return (
+                "검색된 테이블이 불확실해 사용자 확인을 기다립니다. "
+                "더 이상 도구를 부르거나 SQL 을 만들지 말고 이 턴을 끝내세요.",
+                raw_holder[0],
+            )
+        content = str(result.content if hasattr(result, "content") else result)
+        grounding = self._grounding_text(
+            tool_name, args, call_id or "codex-qa-tool", content
+        )
+        if grounding:
+            content = f"{content}\n\n---\n{grounding}"
+        return content, raw_holder[0]
+
+
+def _get_match_text_fields_info() -> str:
+    """Qdrant에서 enterprise_tables/bdp_tables의 text index 필드를 ���회."""
+    try:
+        from codebuff_core.services.rag_collections import (
+            COLLECTION_BDP,
+            COLLECTION_ENTERPRISE,
+            get_manager,
+        )
+
+        mgr = get_manager()
+        if mgr is None:
+            return ""
+
+        client = mgr._client
+        existing = {c.name for c in client.get_collections().collections}
+        lines: list = []
+
+        for col_name in [COLLECTION_ENTERPRISE, COLLECTION_BDP]:
+            if col_name not in existing:
+                continue
+            try:
+                col_info = client.get_collection(col_name)
+                text_fields = [
+                    fname
+                    for fname, schema in (col_info.payload_schema or {}).items()
+                    if "text" in str(getattr(schema, "params", "")).lower()
+                    or getattr(schema, "data_type", "") == "text"
+                ]
+                if text_fields:
+                    lines.append(
+                        f"- **{col_name}**: {', '.join(f'`{f}`' for f in sorted(text_fields))}"
+                    )
+            except Exception:
+                continue
+
+        if not lines:
+            return ""
+
+        return "### match_text 검색 가능 컬렉션 및 인덱스 필드\n" + "\n".join(lines)
+    except Exception:
+        return ""
+
+
+_COLLECTION_LABEL = {
+    "guide_docs": "가이드",
+    "ds_guide_docs": "DS가이드",
+    "bdp_tables": "L1테이블",
+    "enterprise_tables": "전사테이블",
+}
+
+
+def _format_tool_status(queries_str) -> str:
+    """tool_start 이벤트에서 사용자 친화적 상태 메시지 생성."""
+    try:
+        if isinstance(queries_str, list):
+            q_list = queries_str
+        elif isinstance(queries_str, str) and queries_str:
+            q_list = json.loads(queries_str)
+        else:
+            q_list = []
+    except Exception:
+        return "📚 검색 중..."
+
+    # 컬렉션별 라벨 추출
+    collections: set = set()
+    for q in q_list:
+        if isinstance(q, dict):
+            col = q.get("collection", "")
+            if col:
+                collections.add(col)
+
+    col_label = ", ".join(_COLLECTION_LABEL.get(c, c) for c in sorted(collections))
+    if not col_label:
+        col_label = "Knowledge base"
+
+    # 쿼리 텍스트 추출 (중복 제거, 4단어까지, 쉼표 구분)
+    seen: set = set()
+    queries: list = []
+    for q in q_list:
+        if not isinstance(q, dict):
+            continue
+        txt = q.get("query", "").strip()
+        if txt and txt.lower() not in seen:
+            seen.add(txt.lower())
+            words = txt.split()[:4]
+            queries.append(" ".join(words) + ("..." if len(txt.split()) > 4 else ""))
+    if queries:
+        q_text = ", ".join(queries[:3])
+        return f"📚 {col_label} 검색 중: {q_text}"
+
+    return f"📚 {col_label} 검색 중..."
+
+
+def qa_tool_start_status(tool_name: str, tool_input: Any) -> Optional[Dict[str, str]]:
+    """도구 호출이 시작될 때 패널에 띄우는 진행 줄. 없으면 None.
+
+    LangChain(`stream_response`)과 codex(`codex_bridge`) 두 엔진이 같은 문구를 쓴다 (이슈 #155).
+    """
+    if "skill" in tool_name.lower():
+        skill_names = ""
+        if isinstance(tool_input, dict):
+            skill_names = tool_input.get("names", "")
+        elif isinstance(tool_input, str):
+            skill_names = tool_input
+        if not skill_names:
+            return None
+        return {"status": f"🔧 스킬 로딩: {skill_names}", "icon": "search"}
+    if "get_table_columns" in tool_name:
+        tbl = tool_input.get("table_name", "") if isinstance(tool_input, dict) else ""
+        return {"status": f"📋 컬럼 목록 조회 중... {tbl}", "icon": "search"}
+    if "get_iceberg_snapshots" in tool_name:
+        tbl = ""
+        layer = ""
+        if isinstance(tool_input, dict):
+            tbl = tool_input.get("table_name", "") or ""
+            layer = tool_input.get("layer", "") or ""
+        status = "🗄️ 적재 이력 조회 중"
+        if tbl:
+            suffix = f" ({layer.upper()})" if layer else ""
+            status = f"🗄️ 적재 이력 조회 중: {tbl}{suffix}"
+        return {"status": status, "icon": "database"}
+    if "search_l2_table" in tool_name:
+        names_raw = (
+            tool_input.get("table_names", "")
+            if isinstance(tool_input, dict)
+            else tool_input
+        )
+        try:
+            names_list = (
+                json.loads(names_raw) if isinstance(names_raw, str) else names_raw
+            )
+        except Exception:
+            names_list = []
+        names_display = (
+            ", ".join(str(n) for n in names_list[:3])
+            if isinstance(names_list, list) and names_list
+            else ""
+        )
+        return {
+            "status": (
+                f"📚 L2 테이블 검색 중: {names_display}"
+                if names_display
+                else "📚 L2 테이블 검색 중..."
+            ),
+            "icon": "search",
+        }
+    queries_str = ""
+    if isinstance(tool_input, dict):
+        queries_str = tool_input.get("queries", "")
+    elif isinstance(tool_input, str):
+        queries_str = tool_input
+    return {"status": _format_tool_status(queries_str), "icon": "search"}
+
+
+def _parse_tool_output(output: Any) -> Any:
+    return json.loads(output) if isinstance(output, str) else output
+
+
+def qa_tool_end_status(
+    tool_name: str, output: Any, tool_input: Any = None
+) -> Optional[Dict[str, Any]]:
+    """도구 호출이 끝났을 때 패널에 띄우는 결과 줄. 없으면 None (스킬 로드).
+
+    `qa_tool_start_status` 와 짝이다 — 두 엔진이 같은 문구를 쓴다 (이슈 #155).
+    """
+    if "skill" in tool_name.lower():
+        return None
+    if "get_table_columns" in tool_name:
+        total_cols = 0
+        tbl_name = ""
+        try:
+            parsed = _parse_tool_output(output)
+            if isinstance(parsed, dict):
+                total_cols = parsed.get("total_columns", 0)
+                tbl_name = parsed.get("table_name", "")
+        except Exception:
+            pass
+        return {
+            "status": f"📋 컬럼 조회 완료. {tbl_name} {total_cols}개",
+            "icon": "search",
+        }
+    if "get_iceberg_snapshots" in tool_name:
+        snap_count = 0
+        tbl_name = ""
+        layer = ""
+        not_found = False
+        err = ""
+        try:
+            parsed = _parse_tool_output(output)
+            if isinstance(parsed, dict):
+                tbl_name = parsed.get("table_name", "") or ""
+                layer = parsed.get("layer", "") or ""
+                if parsed.get("success") is False:
+                    not_found = bool(parsed.get("table_not_found"))
+                    err = str(parsed.get("error", "오류"))[:50]
+                else:
+                    snap_count = int(parsed.get("snapshot_count", 0) or 0)
+        except Exception:
+            pass
+        suffix = f" ({layer.upper()})" if layer else ""
+        if not_found:
+            msg = f"🗄️ {tbl_name} 테이블 없음{suffix}"
+        elif err:
+            msg = f"🗄️ {tbl_name} 적재 이력 조회 실패: {err}"
+        elif tbl_name:
+            msg = f"🗄️ {tbl_name} 스냅샷 {snap_count}건 조회 완료"
+        else:
+            msg = f"🗄️ 스냅샷 {snap_count}건 조회 완료"
+        return {"status": msg, "icon": "database", "fade_previous": True}
+    if "search_l2_table" in tool_name:
+        matched = 0
+        not_found_count = 0
+        # ambiguous는 검색어 개수가 아니라 실제 후보 수(표시분+숨김분)로 집계 —
+        # "후보 1건"이 검색어 1개가 ambiguous였다는 뜻으로 오인되지 않도록.
+        cand_total = 0
+        err = ""
+        try:
+            parsed = _parse_tool_output(output)
+            if isinstance(parsed, dict):
+                if parsed.get("success") is False:
+                    err = str(parsed.get("error", "오류"))[:50]
+                else:
+                    for r in parsed.get("results", []):
+                        if not isinstance(r, dict):
+                            continue
+                        if r.get("not_found"):
+                            not_found_count += 1
+                        elif r.get("ambiguous"):
+                            cand_total += len(r.get("candidates", [])) + int(
+                                r.get("more_candidates_count", 0)
+                            )
+                        else:
+                            matched += 1
+        except Exception:
+            pass
+        if err:
+            msg = f"📚 L2 테이블 검색 실패: {err}"
+        else:
+            parts = []
+            if matched:
+                parts.append(f"{matched}건 매칭")
+            if cand_total:
+                parts.append(f"후보 {cand_total}건")
+            if not_found_count:
+                parts.append(f"{not_found_count}건 미발견")
+            msg = f"📚 L2 검색 완료: {', '.join(parts)}" if parts else "📚 L2 검색 완료"
+        return {"status": msg, "icon": "search", "fade_previous": True}
+    # rag_search 결과
+    total = 0
+    parsed: Any = None
+    try:
+        parsed = _parse_tool_output(output)
+        if isinstance(parsed, dict):
+            total = parsed.get("total", 0)
+    except Exception:
+        pass
+    # 검색 결과 내용 요약 (50글자 truncate) + 컬렉션 라벨
+    result_preview = ""
+    col_label = ""
+    result_key_label = {"가이드 검색 결과": "가이드", "테이블 검색 결과": "L1테이블"}
+    try:
+        if isinstance(parsed, dict):
+            found_labels: list = []
+            for rk in ("가이드 검색 결과", "테이블 검색 결과"):
+                items = parsed.get(rk, [])
+                if items:
+                    found_labels.append(result_key_label.get(rk, rk))
+                if rk == "테이블 검색 결과" and items:
+                    # 테이블: 각 후보의 한글명을 쉼표로
+                    tbl_names = []
+                    for ri in items:
+                        rp = ri.get("payload", {})
+                        kn = (
+                            rp.get("korean_name", "")
+                            or rp.get("테이블한글명", "")
+                            or rp.get("table_name", "")
+                        )
+                        if kn and kn not in tbl_names:
+                            tbl_names.append(kn)
+                    if tbl_names:
+                        result_preview = ", ".join(tbl_names)
+                elif not result_preview:
+                    # 가이드/코드: 첫 번째 content 50글자
+                    for ri in items:
+                        rc = ri.get("payload", {}).get("content", "")
+                        if rc:
+                            result_preview = rc[:50].replace("\n", " ")
+                            if len(rc) > 50:
+                                result_preview += "..."
+                            break
+            if found_labels:
+                col_label = ", ".join(found_labels)
+    except Exception:
+        pass
+    if not col_label:
+        # 결과 0건 시 input의 컬렉션에서 라벨 추출
+        try:
+            q_str = (
+                tool_input.get("queries", "") if isinstance(tool_input, dict) else ""
+            )
+            q_list = (
+                json.loads(q_str)
+                if isinstance(q_str, str) and q_str
+                else q_str
+                if isinstance(q_str, list)
+                else []
+            )
+            input_cols: set = set()
+            for q in q_list:
+                if isinstance(q, dict) and q.get("collection"):
+                    input_cols.add(q["collection"])
+            if input_cols:
+                col_label = ", ".join(
+                    _COLLECTION_LABEL.get(c, c) for c in sorted(input_cols)
+                )
+        except Exception:
+            pass
+    if not col_label:
+        col_label = "Knowledge base"
+    msg = f"📚 {col_label} 검색 {total}건 완료"
+    if result_preview:
+        msg += f": {result_preview}"
+    return {"status": msg, "icon": "search", "fade_previous": True}
+
+
+class RAGChatAgent:
+    """LangChain create_agent 기반 RAG chat agent.
+
+    chat mode에서 RAG가 가용할 때 LLMService 대신 사용.
+    rag_search 도구 1개로 ReAct loop (최대 2회 tool call).
+    """
+
+    def __init__(
+        self,
+        llm_config: Dict[str, Any],
+        checkpointer=None,
+        system_prompt_override: Optional[str] = None,
+        table_score_threshold: Optional[float] = None,
+        excluded_table_names: Optional[list] = None,
+        no_tools: bool = False,
+        table_confirm_mode: str = "eda",
+        grounding_constraint: Optional[str] = None,
+        workspace_root: Optional[str] = None,
+    ):
+        self._llm_config = llm_config
+        # load_skills 가 같은 이름의 포털 스킬을 보려면 워크스페이스가 필요하다 (이슈 #220)
+        self._workspace_root = workspace_root
+        self._checkpointer = checkpointer
+        self._system_prompt_override = system_prompt_override
+        self._table_score_threshold = table_score_threshold
+        self._excluded_table_names = excluded_table_names or []
+        self._no_tools = no_tools
+        self._table_confirm_mode = table_confirm_mode  # "eda" or "chat"
+        self._grounding_constraint = grounding_constraint
+        self._agent = None
+        # 호출별 동적 시스템 프롬프트 홀더 (phase_system_prompt 지원)
+        self._dynamic_prompt_holder: list = [None]
+        # 미들웨어 인스턴스 참조 (턴별 리셋용)
+        self._evidence_reflection = None
+        self._rag_grounding = None
+        self._table_confirmation = None
+
+    async def _cleanup_state_after_fallback(
+        self,
+        config: Dict[str, Any],
+        fallback_response: str,
+        compressed_messages: Optional[List[Any]] = None,
+    ):
+        """fallback 성공 후 그래프 state를 compressed context + fallback 응답으로 교체.
+
+        Args:
+            fallback_response: fallback LLM이 생성한 응답 텍스트
+            compressed_messages: fallback에서 사용한 compressed state messages
+        """
+        try:
+            from langchain_core.messages import AIMessage
+
+            if compressed_messages:
+                messages = list(compressed_messages)
+            else:
+                state = await self._agent.aget_state(config)
+                messages = list(state.values.get("messages", []))
+
+            # 빈 AIMessage(실패한 응답)를 fallback 응답으로 교체
+            replaced = False
+            for i in range(len(messages) - 1, -1, -1):
+                if isinstance(messages[i], AIMessage):
+                    if not messages[i].content and not messages[i].tool_calls:
+                        messages[i] = AIMessage(content=fallback_response)
+                        replaced = True
+                    break
+
+            if not replaced:
+                messages.append(AIMessage(content=fallback_response))
+
+            await self._agent.aupdate_state(config, {"messages": messages})
+            print(
+                f"[RAG] State updated after fallback: {len(messages)} messages, "
+                f"tokens≈{_estimate_tokens(messages)}",
+                flush=True,
+            )
+        except Exception as e:
+            print(f"[RAG] State update failed: {e}", flush=True)
+
+    def _create_model(self, temperature: float = 0.0):
+        """vLLM 설정으로 LangChain ChatModel 생성."""
+        import os
+
+        from langchain.chat_models import init_chat_model
+
+        cfg = self._llm_config.get("vllm", {})
+        # 주소·모델은 실효 config 우선 → env 폴백 (이슈 #200). 호출부가 넘기는 값은
+        # `ConfigManager.get_config()` 라 이미 centri > env > pod 파일로 얹혀 있다 —
+        # env 를 앞에 세우면 centri 조직 값(팀·프로젝트 오버라이드)이 pod env 에 밀린다.
+        # 시크릿 env 가 파일을 이기는 것은 실효 config 가 이미 지킨다.
+        # API 키는 centri 로 오지 않으므로 env > config(파일) 그대로다.
+        endpoint = (
+            cfg.get("endpoint", "") or os.environ.get("VLLM_ENDPOINT", "")
+        ).rstrip("/")
+        if not endpoint.endswith("/v1"):
+            endpoint += "/v1"
+        model = cfg.get("model", "") or os.environ.get("VLLM_MODEL", "") or "default"
+        api_key = os.environ.get("VLLM_API_KEY", "") or cfg.get("apiKey", "")
+
+        extra_body: Dict[str, Any] = {"include_reasoning": False}
+        if "gpt-oss" in model.lower():
+            # gpt-oss 토크나이저 고유 stop token — 다른 모델엔 적용하지 않음.
+            extra_body["stop_token_ids"] = [200002, 199999, 200012]
+
+        return init_chat_model(
+            f"openai:{model}",
+            base_url=endpoint,
+            api_key=api_key,
+            temperature=temperature,
+            streaming=True,
+            # tool 호출 시 병렬 tool_call 비활성화. tools 없는 호출(예: 요약)에도
+            # 같은 model 객체가 재사용되지만 parallel_tool_calls는 tools 미지정
+            # 요청에서도 에러 없이 무시됨(tool_choice와 달리 안전).
+            model_kwargs={"parallel_tool_calls": False},
+            extra_body=extra_body,
+        )
+
+    def _create_tools(self):
+        """rag_search + get_table_columns + get_iceberg_snapshots + search_l2_table + load_skills 도구 생성."""
+        from jupyter_ext.agent.langchain_tools import (
+            create_enhanced_rag_search_tool,
+            create_get_table_columns_tool,
+            create_iceberg_snapshots_tool,
+            create_load_skills_tool,
+            create_search_l2_table_tool,
+        )
+
+        return [
+            create_enhanced_rag_search_tool(),
+            create_get_table_columns_tool(),
+            create_iceberg_snapshots_tool(),
+            create_search_l2_table_tool(),
+            create_load_skills_tool(self._workspace_root),
+        ]
+
+    def _build_system_prompt(self) -> str:
+        """RAG enable 모드 시스템 프롬프트 = Q&A 본문(`chat_qa_system_prompt`) + 동적 주입.
+
+        - Chat/Q&A 의 실제 답변은 codex 가 한다(이슈 #155). codex 는 같은 문구를
+          build_chat_mode_system_prompt 로 받으므로 두 경로의 지시문은 한 벌이다.
+        - EDA agent는 system_prompt_override 별도 prompt 사용 (이 함수 우회).
+        - centri 키는 빌더가 읽는다(simple 은 `chat_system_prompt` 이슈 #178,
+          knowledge 는 `chat_qa_system_prompt` 이슈 #208).
+        """
+        # simple 모드 fallback (호출 경로가 거의 없지만 안전망)
+        if self._no_tools:
+            return build_chat_mode_system_prompt("simple")
+
+        return build_chat_mode_system_prompt("knowledge")
+
+    async def _fallback_llm_call(self, config: Dict[str, Any]):
+        """그래프 실패 시 state에서 메시지를 가져와 compression 후 LLM 직접 호출."""
+        from langchain_core.messages import (
+            HumanMessage,
+            SystemMessage,
+            ToolMessage,
+        )
+
+        # checkpointer에서 현재 state 가져오기
+        thread_id = (config.get("configurable") or {}).get("thread_id")
+        state_messages = []
+        if self._checkpointer and thread_id:
+            try:
+                state = await self._agent.aget_state(config)
+                state_messages = state.values.get("messages", [])
+            except Exception:
+                pass
+
+        if not state_messages:
+            raise RuntimeError("No messages in state for fallback")
+
+        print(
+            f"[RAG] Fallback: state has {len(state_messages)} messages",
+            flush=True,
+        )
+
+        # compression 미들웨어 로직 적용
+        try:
+            compressor = _create_context_compression_middleware_class()()
+            compressed = compressor.before_model({"messages": state_messages})
+            if compressed:
+                state_messages = compressed["messages"]
+                print("[RAG] Fallback: compression applied", flush=True)
+        except Exception as comp_err:
+            print(
+                f"[RAG] Fallback: compression failed ({comp_err}), using raw messages",
+                flush=True,
+            )
+
+        # 사용자 질문(마지막) + tool 결과 추출
+        user_question = ""
+        tool_contents = []
+        for msg in state_messages:
+            if isinstance(msg, HumanMessage):
+                user_question = msg.content  # 마지막 HumanMessage를 사용
+            elif isinstance(msg, ToolMessage) and msg.content:
+                tool_contents.append(msg.content[:2000])
+
+        if not user_question:
+            raise RuntimeError("No user question found in state")
+
+        combined_results = "\n\n---\n\n".join(tool_contents[-3:])
+        model = self._create_model()
+        messages = [
+            SystemMessage(
+                content="사용자 질문과 검색 결과를 바탕으로 답변하세요. "
+                "추가 도구 호출 없이 바로 답변만 생성하세요."
+            ),
+            HumanMessage(
+                content=f"질문: {user_question}\n\n검색 결과:\n{combined_results}"
+            ),
+        ]
+
+        fallback_tokens = _estimate_tokens(messages)
+        print(
+            f"[RAG] Fallback LLM call: question={user_question[:80]}, "
+            f"tool_results={len(tool_contents)}, tokens={fallback_tokens}",
+            flush=True,
+        )
+        async for chunk in model.astream(messages):
+            if chunk.content:
+                yield chunk.content
+
+    def _get_or_create_evidence_reflection(self):
+        """EvidenceReflection 미들웨어 인스턴스를 생성하거나 기존 인스턴스 반환."""
+        if self._evidence_reflection is None:
+            self._evidence_reflection = _create_evidence_reflection_middleware_class()()
+        return self._evidence_reflection
+
+    def _get_or_create_rag_grounding(self):
+        """RagGrounding 미들웨어 인스턴스를 생성하거나 기존 인스턴스 반환."""
+        if self._rag_grounding is None:
+            self._rag_grounding = _create_rag_grounding_middleware_class(
+                constraint_text=self._grounding_constraint
+            )()
+        return self._rag_grounding
+
+    def _get_or_create_table_confirmation(self):
+        """TableConfirmation 미들웨어 인스턴스를 생성하거나 기존 인스턴스 반환."""
+        if self._table_confirmation is None:
+            self._table_confirmation = _create_table_confirmation_middleware_class(
+                self._table_score_threshold,
+                self._excluded_table_names,
+                mode=self._table_confirm_mode,
+            )()
+        return self._table_confirmation
+
+    def _rebuild_agent(self, temperature: float = 0.0):
+        """temperature를 변경하여 agent를 재생성."""
+        self._agent = None
+        self._ensure_agent(temperature=temperature)
+
+    def _ensure_agent(self, temperature: float = 0.0):
+        """create_agent로 agent graph 생성 (lazy)."""
+        if self._agent is not None:
+            return
+
+        from langchain.agents import create_agent
+        from langchain.agents.middleware import (
+            ModelRetryMiddleware,
+            SummarizationMiddleware,
+        )
+
+        model = self._create_model(temperature=temperature)
+        tools = self._create_tools()
+        system_prompt = (
+            self._system_prompt_override
+            if self._system_prompt_override
+            else self._build_system_prompt()
+        )
+
+        create_kwargs: Dict[str, Any] = dict(
+            model=model,
+            tools=tools,
+            system_prompt=system_prompt,
+            middleware=[
+                _create_dynamic_system_prompt_middleware_class(
+                    self._dynamic_prompt_holder
+                )(),
+                _create_developer_role_middleware_class()(),
+                _create_strip_content_on_toolcall_middleware_class()(),
+                _create_tool_call_dedupe_middleware_class()(),
+                _create_snapshot_answer_middleware_class()(),
+                self._get_or_create_evidence_reflection(),
+                self._get_or_create_rag_grounding(),
+                _create_context_compression_middleware_class()(),
+                *(
+                    [self._get_or_create_table_confirmation()]
+                    if self._table_score_threshold
+                    else []
+                ),
+                ModelRetryMiddleware(
+                    max_retries=3,
+                    backoff_factor=1.5,
+                    initial_delay=0.3,
+                    max_delay=30.0,
+                    on_failure=_on_llm_retry_failure,
+                ),
+                SummarizationMiddleware(
+                    model=model,
+                    trigger=("tokens", 90000),
+                    keep=("messages", 15),
+                    summary_prompt=(
+                        "아래 대화 기록에서 가장 중요하고 관련성 높은 정보를 추출하세요.\n"
+                        "반드시 한국어로 작성하세요.\n\n"
+                        "다음 섹션별로 정리하세요:\n\n"
+                        "## 세션 목표\n"
+                        "사용자의 주요 목표나 요청은 무엇인가?\n\n"
+                        "## 핵심 요약\n"
+                        "대화에서 도출된 중요한 결론, 검색 결과, 결정 사항을 기록하세요.\n\n"
+                        "## 다음 단계\n"
+                        "세션 목표 달성을 위해 남은 작업은 무엇인가?\n\n"
+                        "추출한 요약만 출력하세요. 다른 텍스트를 추가하지 마세요.\n\n"
+                        "<messages>\n{messages}\n</messages>"
+                    ),
+                ),
+                _create_summary_to_system_middleware_class()(),
+            ],
+        )
+        if self._checkpointer is not None:
+            create_kwargs["checkpointer"] = self._checkpointer
+        self._agent = create_agent(**create_kwargs)
+
+    async def stream_response(
+        self,
+        user_message: str,
+        history_messages: Optional[List[Dict[str, str]]] = None,
+        file_context: Optional[str] = None,
+        thread_id: Optional[str] = None,
+        phase_system_prompt: Optional[str] = None,
+        block_tools: bool = False,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """Agent 응답을 스트리밍. SSE 호환 청크 yield.
+
+        Args:
+            history_messages: 첫 turn에만 전달 (checkpointer 미사용 또는 서버 재시작 후).
+                checkpointer가 state를 유지하면 None으로 전달해 중복 방지.
+            thread_id: checkpointer용 thread ID. conversation_id 사용 권장.
+            block_tools: True이면 tool call을 차단 (simple 모드).
+            phase_system_prompt: 이 호출에만 적용할 시스템 프롬프트 오버라이드.
+                None이면 생성 시 지정한 system_prompt_override 또는 기본값 사용.
+                DynamicSystemPromptMiddleware가 before_model에서 SystemMessage를 교체.
+
+        Yields:
+            {"content": str, "done": False} — LLM 토큰
+            {"status": str, "icon": str, "done": False} — 도구 호출 상태
+        """
+        self._dynamic_prompt_holder[0] = phase_system_prompt
+        self._ensure_agent()
+
+        # 턴 시작: 미들웨어 상태 리셋
+        if self._evidence_reflection is not None:
+            self._evidence_reflection.reset()
+
+        from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+
+        # 메시지 구성
+        messages = []
+        if history_messages:
+            for m in history_messages:
+                if m["role"] == "user":
+                    messages.append(HumanMessage(content=m["content"]))
+                else:
+                    messages.append(AIMessage(content=m["content"]))
+
+        if file_context:
+            messages.append(HumanMessage(content=f"[참고 컨텍스트]\n{file_context}"))
+
+        messages.append(HumanMessage(content=user_message))
+
+        # 사용자 원본 메시지 저장 (enterprise 키워드 체크용)
+        try:
+            from jupyter_ext.agent.langchain_tools import set_last_user_message
+
+            set_last_user_message(user_message)
+        except Exception:
+            pass
+
+        config: Dict[str, Any] = {"recursion_limit": 100}
+        if thread_id:
+            config["configurable"] = {"thread_id": thread_id}
+
+        # ── simple 모드: agent 그래프 우회, 모델 직접 호출 ──
+        if block_tools:
+            try:
+                # checkpointer에서 이전 대화 로드
+                existing_msgs: list = []
+                if self._checkpointer and thread_id:
+                    try:
+                        _state = await self._agent.aget_state(config)
+                        existing_msgs = list(_state.values.get("messages", []))
+                    except Exception:
+                        pass
+
+                # 시스템 프롬프트 + 기존 대화 + 새 메시지
+                sys_prompt = (
+                    phase_system_prompt
+                    or self._system_prompt_override
+                    or self._build_system_prompt()
+                )
+                llm_messages = [SystemMessage(content=sys_prompt)]
+                for m in existing_msgs:
+                    if m.type != "system":
+                        llm_messages.append(m)
+                llm_messages.extend(messages)
+
+                model = self._create_model()
+                response_text = ""
+                async for chunk in model.astream(llm_messages):
+                    if chunk.content:
+                        response_text += chunk.content
+                        yield {"content": chunk.content, "done": False}
+
+                # checkpointer state 업데이트 (대화 연속성 유지)
+                if self._checkpointer and thread_id and response_text:
+                    try:
+                        update_msgs = list(messages) + [
+                            AIMessage(content=response_text)
+                        ]
+                        await self._agent.aupdate_state(
+                            config, {"messages": update_msgs}
+                        )
+                    except Exception as _upd_err:
+                        print(
+                            f"[RAG] simple mode state update failed: {_upd_err}",
+                            flush=True,
+                        )
+            except Exception as e:
+                print(f"[RAG] simple mode error: {e}", flush=True)
+                yield {
+                    "content": f"응답 생성 중 오류가 발생했습니다: {e}",
+                    "done": False,
+                }
+            return
+
+        input_dict = {"messages": messages}
+
+        # 디버그: checkpointer state 확인
+        if self._checkpointer and thread_id:
+            try:
+                _dbg_state = await self._agent.aget_state(config)
+                _dbg_msgs = _dbg_state.values.get("messages", [])
+                print(
+                    f"[RAG] stream_response: thread={thread_id[:16]}... "
+                    f"input_msgs={len(messages)} "
+                    f"checkpoint_msgs={len(_dbg_msgs)} "
+                    f"agent_id={id(self._agent)}",
+                    flush=True,
+                )
+            except Exception:
+                pass
+
+        content_started = False
+        tool_call_count = 0
+        _rag_search_count = 0  # rag_search 호출 횟수
+        _l2_search_count = 0  # search_l2_table 호출 횟수
+        _MAX_RAG_SEARCH = 5
+        _MAX_L2_SEARCH = 5
+        _MAX_TOOL_CALLS = 30  # 전체 tool 호출 상한 (무한 루프 방어)
+        _pending_tool = False  # parallel tool call 방어: 첫 번째만 처리
+        _current_call_id = ""  # tool_call ↔ tool_result 매핑용
+        _current_tool_name = ""  # on_tool_start에서 저장, on_tool_end 로깅에 사용
+        _current_run_id = ""  # on_tool_start의 run_id (on_tool_end 매칭용)
+        _logged_call_ids: set = set()  # 이미 로깅한 call_id 추적 (중복 방지)
+        _content_buffer: list[str] = []  # LLM 턴별 content 버퍼 (할루시네이션 방지)
+        _tool_processing = False  # tool call 실행 후 LLM 응답 대기 상태
+        _stream_had_error = False  # 스트리밍 중 에러 발생 여부 (temperature retry 조건)
+
+        # Raw LLM 로깅 (핫리로드: 매 요청마다 config 확인)
+        _raw_logging = _is_raw_logging_enabled()
+        _raw_log_path: Optional[Path] = None
+        if _raw_logging:
+            _raw_log_path = _get_raw_log_path()
+            _append_log(
+                _raw_log_path,
+                {
+                    "type": "user_request",
+                    "timestamp": datetime.now().isoformat(),
+                    "thread_id": thread_id,
+                    "system_prompt": self._system_prompt_override
+                    or self._build_system_prompt(),
+                    "user_message": user_message,
+                    "history_count": len(history_messages) if history_messages else 0,
+                    "has_file_context": bool(file_context),
+                    "file_context": file_context[:500] if file_context else None,
+                    "input_messages": [
+                        {"role": m.type, "content": m.content} for m in messages
+                    ],
+                },
+            )
+
+        print(f"[RAG] user_message: {user_message[:200]}", flush=True)
+
+        try:
+            async for event in self._agent.astream_events(
+                input_dict, version="v2", config=config
+            ):
+                kind = event.get("event", "")
+
+                # 디버그: chain/model 시작/종료 이벤트 로깅
+                if kind in (
+                    "on_chain_start",
+                    "on_chain_end",
+                    "on_chat_model_start",
+                    "on_chat_model_end",
+                    "on_llm_start",
+                    "on_llm_end",
+                    "on_tool_start",
+                    "on_tool_end",
+                ):
+                    evt_name = event.get("name", "")
+                    _evt_extra = ""
+                    # LangGraph 종료 시 content_started 상태 로깅
+                    if kind == "on_chain_end" and evt_name == "LangGraph":
+                        _evt_extra = (
+                            f" content_started={content_started}"
+                            f" tool_processing={_tool_processing}"
+                            f" tool_calls={tool_call_count}"
+                            f" buf={len(_content_buffer)}"
+                        )
+                    print(
+                        f"[RAG] EVENT: {kind} name={evt_name}{_evt_extra}",
+                        flush=True,
+                    )
+
+                if kind in ("on_chat_model_stream", "on_llm_stream"):
+                    chunk = event.get("data", {}).get("chunk")
+                    if chunk and hasattr(chunk, "content") and chunk.content:
+                        # GPT-OSS harmony 특수 토큰 + 인용 마커 필터링
+                        text = chunk.content
+                        if _HARMONY_TOKEN_RE.search(text) or _CITATION_MARKER_RE.search(
+                            text
+                        ):
+                            text = _strip_harmony_tokens(text)
+                            if not text:
+                                continue
+
+                        # 매 LLM 턴마다 버퍼링: tool call 오면 폐기, 안 오면 flush
+                        _content_buffer.append(text)
+
+                elif kind in ("on_chat_model_end", "on_llm_end"):
+                    output = event.get("data", {}).get("output")
+                    has_tc = bool(
+                        output and hasattr(output, "tool_calls") and output.tool_calls
+                    )
+                    buf_len = len(_content_buffer)
+                    buf_preview = (
+                        "".join(_content_buffer)[:80] if _content_buffer else ""
+                    )
+                    # LLM 응답 내용 로깅
+                    output_content = ""
+                    if output and hasattr(output, "content"):
+                        output_content = output.content or ""
+                    print(
+                        f"[RAG] chat_model_end: has_tool_calls={has_tc} "
+                        f"buf={buf_len} "
+                        f"output_len={len(output_content)} "
+                        f"preview={buf_preview!r}",
+                        flush=True,
+                    )
+                    # 빈 응답 감지 (buffer 0, tool_calls 0, output 0)
+                    if not _content_buffer and not has_tc and not output_content:
+                        print(
+                            "[RAG] WARNING: LLM returned empty response",
+                            flush=True,
+                        )
+                    # tool call이 있는 턴: 버퍼 폐기 (할루시네이션)
+                    # tool call이 없는 턴: 버퍼 flush (최종 답변)
+                    if _content_buffer and has_tc:
+                        print(
+                            f"[RAG] discarding content with tool_calls: "
+                            f"{buf_len} chunks",
+                            flush=True,
+                        )
+                        _content_buffer.clear()
+                    elif _content_buffer:
+                        # SummarizationMiddleware 출력 감지 → 폐기 + 상태 메시지
+                        joined = "".join(_content_buffer)
+                        _SUMMARY_PATTERNS = (
+                            "SESSION",
+                            "## Summary",
+                            "## Intent",
+                            "## Artifacts",
+                            "## Next",
+                            "## 세션 목표",
+                            "## 핵심 요약",
+                            "## 다음 단계",
+                            "Here is a summary",
+                        )
+                        if any(
+                            joined.lstrip().startswith(p) for p in _SUMMARY_PATTERNS
+                        ):
+                            print(
+                                f"[RAG] discarding summarization output: {len(joined)} chars",
+                                flush=True,
+                            )
+                            _content_buffer.clear()
+                            if _tool_processing:
+                                _tool_processing = False
+                                yield {"tool_processing_end": True, "done": False}
+                            yield {"summarizing": True, "done": False}
+                        else:
+                            # tool call 후 LLM 응답 시작 → tool_processing 해제
+                            if _tool_processing:
+                                _tool_processing = False
+                                yield {"tool_processing_end": True, "done": False}
+                            # 버퍼 합쳐서 인용 마커 제거 후 flush
+                            _joined_buf = "".join(_content_buffer)
+                            if _CITATION_MARKER_RE.search(_joined_buf):
+                                _joined_buf = _CITATION_MARKER_RE.sub("", _joined_buf)
+                            if _joined_buf.strip():
+                                content_started = True
+                                yield {"content": _joined_buf, "done": False}
+                            _content_buffer.clear()
+
+                    # Raw LLM 로깅: LLM turn 종료 시 전체 응답 기록
+                    if _raw_log_path:
+                        output = event.get("data", {}).get("output")
+                        log_entry: Dict[str, Any] = {
+                            "type": "llm_response",
+                            "timestamp": datetime.now().isoformat(),
+                            "thread_id": thread_id,
+                        }
+                        if output and hasattr(output, "content"):
+                            _llm_content = output.content or ""
+                            log_entry["content"] = (
+                                _llm_content[:3000] if _llm_content else None
+                            )
+                            log_entry["content_length"] = len(_llm_content)
+                        if output and hasattr(output, "tool_calls"):
+                            tc = output.tool_calls
+                            if tc:
+                                log_entry["tool_calls"] = [
+                                    {"name": t.get("name"), "args": t.get("args")}
+                                    for t in tc
+                                ]
+                            else:
+                                log_entry["tool_calls"] = []
+                        _append_log(_raw_log_path, log_entry)
+
+                elif kind == "on_tool_start":
+                    # tool call 발생: 버퍼에 쌓인 할루시네이션 content 폐기
+                    if _content_buffer:
+                        print(
+                            f"[RAG] discarding buffered hallucination: "
+                            f"{len(_content_buffer)} chunks",
+                            flush=True,
+                        )
+                        _content_buffer.clear()
+                    content_started = False
+
+                    # parallel tool call 방어: 이미 tool 실행 중이면 스킵
+                    if _pending_tool:
+                        print(
+                            f"[RAG] parallel tool call skipped: {event.get('name', '')}",
+                            flush=True,
+                        )
+                        continue
+                    _pending_tool = True
+                    tool_call_count += 1
+                    tool_name = event.get("name", "")
+                    tool_input = event.get("data", {}).get("input", {})
+
+                    # 전체 tool 호출 상한 초과 시 강제 종료
+                    if tool_call_count > _MAX_TOOL_CALLS:
+                        print(
+                            f"[RAG] MAX_TOOL_CALLS ({_MAX_TOOL_CALLS}) reached, stopping",
+                            flush=True,
+                        )
+                        yield {
+                            "status": f"도구 호출 횟수 제한({_MAX_TOOL_CALLS}회)에 도달하여 중단합니다.",
+                            "done": True,
+                        }
+                        return
+
+                    _current_call_id = f"call_{tool_call_count}"
+                    _current_tool_name = tool_name
+                    _current_run_id = event.get("run_id", "")
+                    if _raw_log_path:
+                        _append_log(
+                            _raw_log_path,
+                            {
+                                "type": "tool_call",
+                                "call_id": _current_call_id,
+                                "timestamp": datetime.now().isoformat(),
+                                "thread_id": thread_id,
+                                "tool_name": tool_name,
+                                "tool_input": tool_input
+                                if isinstance(tool_input, dict)
+                                else str(tool_input),
+                                "call_num": tool_call_count,
+                            },
+                        )
+
+                    # rag_search 과도한 호출 방어
+                    if "rag_search" in tool_name:
+                        _rag_search_count += 1
+                        if _rag_search_count > _MAX_RAG_SEARCH:
+                            print(
+                                f"[RAG] rag_search call #{_rag_search_count} "
+                                f"blocked (max={_MAX_RAG_SEARCH})",
+                                flush=True,
+                            )
+                            _pending_tool = False
+                            continue
+
+                    # search_l2_table 과도한 호출 방어
+                    elif "search_l2_table" in tool_name:
+                        _l2_search_count += 1
+                        if _l2_search_count > _MAX_L2_SEARCH:
+                            print(
+                                f"[RAG] search_l2_table call #{_l2_search_count} "
+                                f"blocked (max={_MAX_L2_SEARCH})",
+                                flush=True,
+                            )
+                            _pending_tool = False
+                            continue
+
+                    print(
+                        f"[RAG] tool_start (call #{tool_call_count}): "
+                        f"{tool_name} {str(tool_input)[:200]}",
+                        flush=True,
+                    )
+                    _start_status = qa_tool_start_status(tool_name, tool_input)
+                    if _start_status:
+                        yield {**_start_status, "done": False}
+
+                elif kind == "on_tool_end":
+                    # run_id가 on_tool_start와 일치하지 않으면 무시 (이벤트 뒤섞임 방지)
+                    _end_run_id = event.get("run_id", "")
+                    if _current_run_id and _end_run_id != _current_run_id:
+                        continue
+                    _pending_tool = False  # 다음 tool call 허용
+                    tool_name = event.get("name", "")
+                    output = event.get("data", {}).get("output", "")
+                    if hasattr(output, "content"):
+                        output = output.content
+
+                    _end_status = qa_tool_end_status(
+                        tool_name, output, event.get("data", {}).get("input", {})
+                    )
+                    print(
+                        f"[RAG] tool_end: {tool_name} "
+                        f"{(_end_status or {}).get('status', '')}",
+                        flush=True,
+                    )
+                    if _end_status:
+                        yield {**_end_status, "done": False}
+                        # tool 실행 완료 → LLM이 결과 분석 중 상태
+                        if not _tool_processing:
+                            _tool_processing = True
+                            yield {"tool_processing": True, "done": False}
+
+                    # Raw LLM 로깅: 모든 tool의 result 기록 (call_id로 매핑)
+                    # 이미 로깅한 call_id는 건너뜀 (중복 on_tool_end 방지)
+                    if (
+                        _raw_log_path
+                        and _current_call_id
+                        and _current_call_id not in _logged_call_ids
+                    ):
+                        _output_parsed: Any = output
+                        if isinstance(output, str):
+                            try:
+                                _output_parsed = json.loads(output)
+                            except (json.JSONDecodeError, TypeError):
+                                _output_parsed = output
+                        _append_log(
+                            _raw_log_path,
+                            {
+                                "type": "tool_result",
+                                "call_id": _current_call_id,
+                                "timestamp": datetime.now().isoformat(),
+                                "thread_id": thread_id,
+                                "tool_name": _current_tool_name or tool_name,
+                                "output": _output_parsed,
+                            },
+                        )
+                        _logged_call_ids.add(_current_call_id)
+
+        except TableConfirmationNeeded:
+            raise  # Athena handler에서 catch하도록 전파
+        except Exception as e:
+            import traceback
+
+            _stream_had_error = True
+            err_msg = str(e)
+            print(f"[RAG] ERROR: {err_msg}", flush=True)
+            traceback.print_exc()
+
+            if "recursion limit" in err_msg.lower():
+                print("[RAG] Recursion limit — attempting final LLM call", flush=True)
+                if not content_started:
+                    # 그래프 state에서 메시지를 가져와 LLM 직접 호출
+                    try:
+                        async for chunk in self._fallback_llm_call(config):
+                            content_started = True
+                            yield {"content": chunk, "done": False}
+                    except Exception as fallback_err:
+                        print(
+                            f"[RAG] Fallback LLM call failed: {fallback_err}",
+                            flush=True,
+                        )
+                        yield {
+                            "content": "검색 결과를 바탕으로 답변을 준비했으나 "
+                            "처리 한도에 도달했습니다. 질문을 더 구체적으로 "
+                            "해주시면 정확한 답변을 드릴 수 있습니다.",
+                            "done": False,
+                        }
+            else:
+                # content가 이미 일부 출력된 경우만 에러 안내 표시
+                # (content_started=False이면 아래 retry 로직에서 처리)
+                if content_started:
+                    yield {
+                        "content": f"\n\n> 문제가 발생했습니다. {err_msg}\n> 잠시 후 다시 시도해 주세요.",
+                        "done": False,
+                    }
+
+        # 스트림 종료 후 content가 없으면 처리
+        if not content_started:
+            _reason = (
+                "stream ended without content after tool_end"
+                if _tool_processing
+                else "empty response without tool calls"
+            )
+
+            if _stream_had_error:
+                # LLM/vLLM 에러 발생 → temperature 올려서 재시도
+                print(
+                    f"[RAG] WARNING: {_reason} (had error) — retrying with higher temperature",
+                    flush=True,
+                )
+                _retry_temp = 0.1
+                while not content_started and _retry_temp <= 0.9:
+                    print(
+                        f"[RAG] Retrying with temperature={_retry_temp:.1f}", flush=True
+                    )
+                    self._rebuild_agent(temperature=_retry_temp)
+                    try:
+                        async for chunk in self._agent.astream(
+                            {"messages": messages}, config, stream_mode="updates"
+                        ):
+                            for _node_name, _node_val in chunk.items():
+                                if _node_name == "__interrupt__" or _node_val is None:
+                                    continue
+                                _msgs = (
+                                    _node_val.get("messages", [])
+                                    if isinstance(_node_val, dict)
+                                    else []
+                                )
+                                for _msg in _msgs:
+                                    if (
+                                        hasattr(_msg, "content")
+                                        and _msg.content
+                                        and _msg.type == "ai"
+                                        and not getattr(_msg, "tool_calls", None)
+                                    ):
+                                        content_started = True
+                                        yield {"content": _msg.content, "done": False}
+                    except Exception as retry_err:
+                        print(
+                            f"[RAG] Retry failed (temp={_retry_temp:.1f}): {retry_err}",
+                            flush=True,
+                        )
+                    _retry_temp += 0.1
+
+                if not content_started:
+                    print("[RAG] All temperature retries failed", flush=True)
+                    yield {
+                        "content": "LLM 호출 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요.",
+                        "done": False,
+                    }
+                # temperature를 0으로 복원
+                self._rebuild_agent(temperature=0.0)
+            else:
+                # 에러 없이 빈 응답 → fallback LLM 호출
+                print(
+                    f"[RAG] WARNING: {_reason} — attempting fallback LLM call",
+                    flush=True,
+                )
+                try:
+                    async for chunk in self._fallback_llm_call(config):
+                        content_started = True
+                        yield {"content": chunk, "done": False}
+                except Exception as fallback_err:
+                    print(f"[RAG] Fallback LLM call failed: {fallback_err}", flush=True)
+                    yield {
+                        "content": "응답 생성에 실패했습니다. 다시 시도해주세요.",
+                        "done": False,
+                    }