로브 (Lovv) Agent 명세서

문서 버전: v0.15

문서 상태: 검토 중 (Review)

기준 문서: 요구사항 명세서 v1.7, 서비스 흐름 명세서 v0.2, 데이터 수집 계획서 v0.7, 데이터베이스 설계 명세서 v0.5, 기술 명세서 v0.3, API 명세서 v0.2

상세 정본: supplemental/langgraph_flow.md, supplemental/intent_agent.md, supplemental/candidate_evidence_agent.md, supplemental/candidate_evidence_baseline_comparison.md, supplemental/planner_agent.md, supplemental/agent_harness_design.md

[PRD 반영 v0.1 — 대화형 빌더] 일정 생성 단계를 자동 배치에서 사용자 주도 HITL 반경 루프로

전환한다(소도시 선정까지는 유지). 주요 변경: ① Candidate Evidence 3층 분해(공유 코어 + 도시선정

1회 + 반경 Provider 루프, 게이트 city｜radius) ② Intent action 어휘(PICK·REPLACE_PLACE·

EXCLUDE·FILTER·DONE) + Profile Agent 분리·Lock ③ Planner = Geo-Filter(동선=선택 순서)

④ 결정론 Supervisor·스텝 병렬 fan-out 유지. 근거·상세: ../98_prd/interactive_builder_prd.md.

1. 문서 개요

1.1 목적

본 문서는 로브 추천 Agent의 공개 정본이다. Agent는 단일 LLM 호출이 아니라 Intent_Agent가 사용자 의도와 조건을 정리하고, Supervisor_Router가 상태 기반으로 전문 Agent와 결정적 Skill을 호출하는 멀티스텝 파이프라인으로 동작한다.

정본의 범위는 다음과 같다.

• 사용자 자연어, 온보딩 선호, 지도 진입 조건을 추천 가능한 상태로 구조화한다.
• 한국/일본 소도시와 장소 evidence 후보를 검색·점수화하고 Planner가 사용할 후보 패키지를 구성한다.
• 축제 날짜, 일정 구성, 추천 근거, 최종 응답의 안전성을 검증한다.
• AgentCore Runtime, Memory, Gateway, Policy, Observability에 연결 가능한 상태·노드·도구 계약을 정의한다.

1.2 설계 원칙

2. Agent 목표

3. Agent 입력

4. Agent 출력

API 응답에서는 externalLinks를 links 객체로 직렬화한다. Agent 내부 상태와 문서 본문은 링크 생성 책임을 명확히 하기 위해 externalLinks라는 논리명을 사용하되, /recommendations 응답 계약은 API 명세의 links.map, links.staySearch를 따른다. recommendationReasons, itineraryFlowReason, confidence, user_notice, festivalDateVerifications는 API 명세의 explainability와 최상위 검증 필드로 매핑한다.

5. 파이프라인

Intent_Agent는 조건 파싱을 내장한 entry node다. Condition_Parser_Agent는 별도 물리 노드로 두지 않고 Intent_Agent의 논리 책임으로 통합한다. 이후 Supervisor_Router가 fulfilled_matrix와 구조화 조건을 기준으로 Candidate_Evidence_Agent를 호출한다. Candidate_Evidence_Agent는 기존 Polymorphic_Retriever_Agent와 Ranker_Agent의 책임을 통합해 장소 evidence 검색, 도시/장소 점수화, Planner 입력 후보 패키지 구성을 수행한다. 목적지와 후보 장소 패키지가 구성된 뒤에는 Planner_Agent가 일정 생성, 설명 생성, 최종 출력 검증을 통합 담당한다.

5.1 Agent 구성도

5.2 파이프라인 단계

6. UnifiedAgentState

LangGraph 그래프 전역 상태다. 구현 기준은 Python 3.12 TypedDict이며 상세 정본은 supplemental/langgraph_flow.md를 따른다.

from typing import TypedDict, List, Dict, Any, Optional

        class UnifiedAgentState(TypedDict):
            # --- 대화/컨텍스트 (Intent_Agent 소유) ---
            messages: List[Dict[str, str]]            # 전체 멀티턴 백로그 (Supervisor에 미전달)
            conversation_summary: str                 # 롤링 요약 (백로그 토큰 bound)
            turn_index: int                           # 현재 사용자 턴 번호
            session_id: str                           # 세션 식별자
            recommendation_request_id: Optional[str]  # MySQL 추천 요청/결과 원장 연결 키
            agent_run_id: Optional[str]               # DynamoDB Agent 실행 trace 연결 키

            # --- Intent → Supervisor handoff payload ---
            extracted_inputs: Dict[str, Any]          # country, travelMonth, travelYear, tripType, theme, entryType, includeFestivals
            user_preferences: List[str]               # RAG/검색용 선호 문장 (의도 관련성 명확분만)
            onboarding_themes: List[str]              # 장기 선호 (온보딩 1~3개)
            chat_extracted_themes: List[str]          # 자연어에서 추출된 테마
            active_required_themes: List[str]         # 필수 충족 대상 (온보딩+자연어 병합, 최대 3)
            theme_priority: Dict[str, str]            # 테마별 high|normal|low
            soft_preferences: List[str]               # quiet, scenic_view 등 랭킹 가산 조건
            cleaned_raw_query: str                    # 반영 가능 조건만 남긴 원문
            theme_queries: Dict[str, str]             # 테마별 벡터 검색 쿼리
            soft_preference_query: str                # 분위기 통합 쿼리
            unsupported_conditions: List[str]         # RAG 미전달, user_notice 대상
            backup_themes: List[str]                  # active 3개 초과 시 밀려난 온보딩 테마
            user_location: Optional[Dict[str, float]] # API userLocation을 Intent adapter가 정규화한 내부 좌표
            user_notice: Optional[str]                # 예외 안내 문구
            excluded_themes: List[str]                # 명시적 거부 테마

            # --- 라우팅 제어 (Supervisor 소유) ---
            next_node: str
            fulfilled_matrix: Dict[str, str]          # 테마/단계별 X|O|△|N/A
            target_region: Optional[str]              # 하위 호환용 지역 상태. 신규 흐름은 selected_city/candidate_evidence_package를 우선 사용
            validation_retry_count: int               # 검증 실패 재시도 카운터 (상한 2)

            # --- 수집/생성물 (Worker/Skill 누적) ---
            candidate_evidence_package: Optional[Dict[str, Any]]  # Candidate_Evidence_Agent 출력
            raw_collected_data: List[Dict[str, Any]]  # 하위 호환용 수집 데이터, 기상 경향 등
            festival_verifications: List[Dict[str, Any]]  # Festival_Verifier 결과 JSON
            selected_destination: Optional[Dict[str, Any]]
            itinerary: Optional[Dict[str, Any]]
            recommendation_reasons: Optional[List[str]]
            confidence: Optional[float]

상태 정책:

• messages 원문은 Memory에만 두고 Supervisor에 통째 전달하지 않는다.
• conversation_summary와 최근 N턴만 Intent_Agent 입력으로 사용한다.
• fulfilled_matrix는 X, O, △, N/A만 사용한다.
• validation_retry_count 상한은 2회다.
• unsupported_conditions는 RAG 검색 조건으로 전달하지 않고 user_notice와 외부 검색 링크로 분리한다.
• recommendation_request_id는 MySQL 추천 요청/결과 원장과 연결되는 추적 키다.
• agent_run_id는 DynamoDB lovv_agent_runs의 Agent 실행 trace와 연결되는 추적 키다.
• agent_run_id, recommendation_request_id, session_id는 원문 대화 없이 상태 요약과 장애 분석 로그를 연결하기 위한 최소 식별자로만 사용한다.

7. 단계별 명세

7.1 Intent_Agent

온보딩은 장기 선호, 자연어는 현재 여행 의도로 본다. active theme는 최대 3개를 기본으로 하며, 자연어가 강하게 요구한 테마가 온보딩보다 우선한다.

현재 단계의 Intent Agent 구현 기준은 supplemental/intent_agent.md를 따른다. 핵심 산출물은 supplemental/candidate_evidence_agent.md의 입력 계약에 맞춘 candidate_evidence_input이며, Intent Agent는 도시 검색·점수화·일정 생성을 수행하지 않는다.

7.2 Supervisor_Router

fulfilled_matrix 기호 규격은 8.2를 단일 출처로 사용한다.

7.3 Candidate_Evidence_Agent

Candidate Evidence Agent의 기본 로직:

• Intent_Agent가 구조화한 active_required_themes, cleaned_raw_query, soft_preference_query, 내부 user_location(API userLocation에서 정규화), destinationId를 입력으로 받는다.
• active_required_themes는 deterministic metadata gate와 theme coverage 계산에 사용한다. 단, 현재 단계에서 미식·노포는 restaurant 후보 조회가 아니라 선택 도시 기준 맛집 검색 링크 요구로 Planner에 전달한다.
• cleaned_raw_query와 soft_preference_query는 장소 evidence 검색의 별도 query channel로 사용한다.
• Scoring Tool은 도시/장소 점수, 테마 커버리지, 테마 균형, 거리/일수 가능성, 후보 충분성을 계산한다.
• Planner fallback 지연을 줄이기 위해 최종 일정 필요 수보다 넉넉한 관광지 recommended_places와 reserve_places를 반환한다.
• 복수 테마 선택 시 theme quota와 balance audit을 적용해 특정 테마 후보로 쏠리지 않게 한다.
• unsupported_conditions는 검색 조건으로 전달하지 않는다.

검색 인덱스 계약:

Candidate Evidence Agent는 S3 vector metadata filter로 국가·도시·테마·월·콘텐츠 유형을 1차 제한하고, Lambda 관계 탐색 보조 기능으로 도시·축제·테마·장소 관계를 확장한 뒤 MySQL 원장 또는 DynamoDB 정규화 문서의 확정 필드로 후보를 재검증한다. S3 vector 결과만으로 장소 존재, 축제 일정, 운영 여부를 확정하지 않는다.

7.4 Festival_Verifier_Agent

캐시 TTL:

confirmed 축제만 일정에 직접 배치한다. tentative는 안내 문구 또는 후보 정보로만 사용한다. 축제 포함 요청에서는 모든 후보를 웹 검증하지 않고, Candidate Evidence Agent가 구성한 상위 도시/축제 후보 K곳(기본 2~3곳)만 검증한다. includeFestivals=false이면 Festival Verifier를 건너뛰고 festival 매트릭스 항목을 N/A로 둔다.

7.5 Planner_Agent

Planner Agent의 상세 정본은 supplemental/planner_agent.md를 따른다. supplemental/itinerary_flow.md는 PlanDraft, 수정 흐름, 대체 일정 아이디어를 담은 초안 문서로 유지하되 구현 기준은 supplemental/planner_agent.md를 우선한다.

추천 이유와 동선 설명은 다음 세 축을 중심으로 작성한다.

반영하기 어려운 조건은 user_notice로 분리한다. 숙박 품질, 가격, 예약 가능 여부, 실시간 혼잡도, 실시간 운영 여부는 확정 추천 근거로 쓰지 않는다.

7.6 Validation Skill

Planner Agent 내부에서 LLM 의미 검증 전에 결정적으로 검사한다.

7.7 Planner 의미 검증

검증 실패 시 validation_retry_count를 증가시킨다. 2회 미만이면 Supervisor가 실패 카테고리별 결정 규칙으로 분기한다. 2회에 도달하면 안전 폴백 응답으로 종료한다.

8. 도구 및 Skill

8.1 사용 도구/Skill

8.2 fulfilled_matrix 규격

표준 키는 evidence, festival, planning으로 고정한다. Supervisor는 X 항목을 아래 우선순위로 처리한다. evidence는 기존 retrieval/ranking을 통합한 Candidate Evidence Agent 구간이며, 장소 evidence 검색, 도시/장소 scoring, primary/reserve 후보 패키징을 포함한다. planning은 일정 생성, 설명 생성, 결정적/의미 검증을 포함한 Planner Agent 구간이다.

멀티턴에서 사용자가 명시 거부를 번복하면 Matrix Transition Skill이 N/A → X 전이를 수행한다. 확신이 낮으면 전이하지 않고 추가 질문을 생성한다.

Matrix Transition Skill의 표준 전이는 아래를 따른다. needs_clarification=true는 사용자 응답이 필요한 상태이므로 Supervisor가 Planner를 호출하지 않고 END_WAIT_USER로 종료한다.

9. Bedrock 및 AgentCore 매핑

AgentCore 하네스는 도메인 추론을 대체하지 않는다. 요청 정규화, graph compile/cache, model adapter, identity, runtime guard, redacted logging, entrypoint contract test는 하네스 책임으로 두고, Agent node·routing rule·prompt·schema·fallback behavior는 도메인 workflow의 정본으로 유지한다. 상세 책임 경계는 supplemental/agent_harness_design.md 2.2.1을 따른다.

Memory에는 다음 턴의 의도 해석과 재추천에 필요한 요약 상태만 저장한다. messages recent window, conversation_summary, fulfilled_matrix, city_anchor, festival_verifications summary, PlanDraft summary는 저장 후보지만, raw RAG result, raw web content, full candidate_evidence_package, embedding cache, secret, PII는 Memory와 log에 저장하지 않는다. 전체 candidate_evidence_package는 단일 실행 내부 payload로만 사용하고, 멀티턴 재추천에는 city/place id와 audit 요약만 남긴다.

LLM 호출은 Bedrock Converse API로 추상화한다. 본 정본은 특정 모델 ID나 Agent별 모델 tier 배정을 고정하지 않는다. 실제 모델 ID와 tier 배정은 Bedrock Converse adapter, 배포 환경 설정, 비용·지연·품질 평가 결과에 따라 결정한다. 임베딩은 Amazon Titan Text Embeddings V2 또는 Cohere Embed 계열을 후보로 두고, S3 vector 기능 기반 RAG 인덱스와 연동한다.

9.1 저장소 연결 원칙

Agent는 저장소별 책임을 넘지 않는다. MySQL 원장은 사용자에게 조회·저장·피드백으로 노출되는 최종 상태를 담당하고, DynamoDB는 TTL 기반 실행 상태와 로그성 데이터를 담당한다. S3 vector index는 검색 성능과 의미 재랭킹을 위한 파생 인덱스이며, 재색인과 복구는 MySQL, DynamoDB 정규화 문서, S3 Raw 원본을 기준으로 수행한다. Lambda 관계 탐색 보조 기능은 관계 탐색과 그래프 기반 후보 확장을 위한 파생 기능이며, 재적재와 복구는 DynamoDB 정규화 문서와 S3 Raw 원본을 기준으로 수행한다. Neptune은 3-hop 이상 임의 경로 탐색이나 대규모 실시간 그래프 쓰기가 필요해질 때의 고도화 승격 옵션으로 둔다.

10. 품질 검증 기준

테스트 하네스는 supplemental/agent_harness_design.md를 따른다. PR 단계는 결정적 L1/L2/L4 핵심 케이스를 우선하고, LLM 평가와 전체 trajectory 평가는 nightly 또는 릴리즈 게이트로 분리한다.

10.1 Candidate Evidence Agent 비교 검증

검색·후보 구성의 Baseline은 raw query similarity만 사용하는 단순 RAG로 정의한다. Ours는 동일한 hard-theme gate, 후보 예산, fallback 조건 위에 soft retrieval, 다요소 scoring, entropy balance, min quota와 soft max quota를 추가한다.

설계 차이와 현재 실험 근거는 supplemental/candidate_evidence_baseline_comparison.md를 따른다. 도시·관광지 검색 테스트 계획과 상세 결과의 정본은 ../10_test_plan/supplemental/candidate_evidence_search_test_plan.md, ../10_test_plan/supplemental/candidate_evidence_evaluation_results.md다.

11. 금지 사항

• 대화 로그 전문을 장기 저장하지 않는다.
• Supervisor에 전체 대화 로그, 웹 검색 원문, RAG 원문을 전달하지 않는다.
• Memory와 log에 raw RAG result, raw web content, full candidate_evidence_package, embedding cache, secret, PII를 저장하지 않는다.
• WeatherAPI 실시간 예보를 추천 후보 스코어링 기준으로 사용하지 않는다.
• 출처 없는 장소 정보를 확정 사실처럼 제시하지 않는다.
• 검증되지 않은 축제 날짜를 확정 일정처럼 제시하지 않는다.
• 한국 요청에 일본 목적지를 섞거나, 일본 요청에 한국 목적지를 섞지 않는다.
• 숙소를 직접 추천하지 않고 검색 링크만 제공한다.
• 검증 실패 결과를 최종 추천으로 반환하지 않는다.

12. 변경 이력