exAichatbot_agent/kakaoChatbotSkill-chatbot2.0-agent

kakaoChatbotSkill — 카카오/웹 진입(Web) 서비스

한국도로공사 챗봇의 진입 계층(Web) 입니다. 카카오 오픈빌더 웹훅과 웹앱(chatbotApp)의 요청을 받아 Agent(RAG /agent/chat) 로 위임하고, 응답을 카카오/웹 UI로 조립합니다.

운영: 128.200.100.61:8083 (DMZ 웹 서버, nginx 뒤) 운영 모드: agent.mode=agent — WAS·RAG는 모드 분기 없이 Agent tool API와 /agent/chat를 제공합니다. 전체 구조: ../SYSTEM_ARCHITECTURE.md · Agent 상세: ../docs/AGENT_ARCHITECTURE.md 콜백 구현: CALLBACK_구현_정리.md 최종 갱신: 2026-07-10

---

1. 역할

책임	설명
카카오 웹훅 수신	/kakao/skill (폴백 블록 발화)
웹앱 수신	/web/ask(JSON), /web/ask/stream(SSE) — chatbotApp
오케스트레이션 위임	RAG /agent/chat 호출
WEB domain tool 제공	/internal/tools/data-portal (WAS 역호출 전용, GASSTATION·BRAND_SHOP·REST_AREA_FOOD_LIST)
UI 조립	Agent 응답 → SimpleText·ListCard·BasicCard·QuickReply·fareBreakdown

핵심 원칙: 정책(fetchOwner/uiType/needsClarification)은 WAS+YAML이 결정하고, Skill은 진입·위임·UI 표현만 담당합니다.

---

2. 요청 흐름

flowchart TD
    K[카카오 오픈빌더] -->|/kakao/skill| SC[SkillController]
    APP[chatbotApp/브라우저] -->|/web/ask, /web/ask/stream| WC[WebChatController]

    SC --> RB[ResultBuilder → KakaoIntentApp]
    WC --> WS[WebChatService] --> RB

    RB --> RAG[RagAgentClient → RAG :28012 /agent/chat]

    ITC[InternalToolController /internal/tools/data-portal] --> IDP[InternalDataPortalToolService → data.ex.co.kr]
    WAS2[WAS tool execute, agent WEB tool] -->|역호출| ITC

    RAG --> UI[buildLlmAgentOutputs + SkillResponseWebExtractor]
    UI --> OUT([카카오 SimpleText/카드 · WebAskResponse])

• Agent 모드: Skill → RAG /agent/chat 1회. WEB domain 데이터는 WAS가 /internal/tools/data-portal로 역호출해 가져옵니다.

---

3. 진입 API

Method	URL	구현	용도
POST/GET	/kakao/skill (/oakak/skill 별칭)	SkillController	카카오 폴백 블록
POST	/web/ask	WebChatController → WebChatService	웹 JSON 응답 (WebAskResponse)
POST	/web/ask/stream	WebChatController	SSE 스트리밍 (chatbotApp)
POST	/internal/tools/data-portal	InternalToolController	WAS→Skill WEB tool (내부 전용, X-Internal-Tool-Key)

---

4. 주요 구현 파일

파일	책임
controller/SkillController.java	카카오 웹훅 진입
response/build/ResultBuilder.java	intent → 핸들러 라우팅
response/build/KakaoIntentApp.java	카카오 fallback 블록, Agent 호출, 카드 UI 조립, buildLlmAgentOutputs
service/RagAgentClient.java	RAG POST /agent/chat 클라이언트
web/WebChatController.java·WebChatService.java	/web/ask(+stream) → Agent 호출 및 웹 응답 매핑
web/SkillResponseWebExtractor.java	SkillResponse → 웹 DTO(ListCard·quickReplies·fareBreakdown)
api/InternalToolController.java	WAS→Skill internal API
service/InternalDataPortalToolService.java·DataPortalService.java	WEB tool data.ex.co.kr 조회
config/AgentProperties.java	agent.mode, fallback-legacy, agent.chat.url
config/InternalToolProperties.java	internal.tool.api-key

---

5. 설정 (jar 옆 application.yml)

agent:
  mode: agent
  fallback-legacy: true       # 장애 대응용 fallback 설정
  chat:
    url: http://172.16.180.130:28012/agent/chat
    timeout-ms: 100000
internal:
  tool:
    api-key: ${INTERNAL_TOOL_API_KEY}   # WAS↔Skill 내부 인증(3서비스 동일)

방화벽: 172.16.180.130 → 128.200.100.61:8083 (WAS→Skill WEB tool), 128.200.100.61 → 172.16.180.130:28012(Skill→RAG)·:8086(Skill→WAS).

---

6. botId · 세션 정책

채널	botId	이력·pending
카카오	userRequest.user.id (사용자별 고정)	24h 내 동일 사용자 이력·pending 이어짐
웹(chatbotApp)	sessionStorage 랜덤(web-...) — 대화마다 새 botId(무상태)	새 대화는 이력·pending 없음

• 카카오↔웹은 세션을 연계하지 않고, 웹은 대화마다 새 botId로 시작해 과거 대화를 복원하지 않습니다. 상세: ../SYSTEM_ARCHITECTURE.md.
• pending(되묻기)은 Agent 모드에서 RAG(MongoDB agent_pending) 가 소유하며 Skill은 무상태입니다. Skill은 query + botId만 RAG로 전달합니다.

---

7. 관련 문서

문서	내용
../SYSTEM_ARCHITECTURE.md	전체 구조·API·포트·세션 정책
../docs/AGENT_ARCHITECTURE.md	Agent 모드 상세·방화벽
CALLBACK_구현_정리.md	카카오 콜백(5초 초과 응답) 구현
../chatbotApp/README.md	웹앱 UI·/web/ask 연동