LightHouse · AI 기반 실시간 데이터 연동형 물류·항만 문서 에이전트

팀 LightHouse · 부산대학교 클라우드 AI PBL / AWS 프로젝트 라이브: https://d3kqsmoqig928k.cloudfront.net

단순 챗봇·OCR이 아니라 보안이 강제된 문서 수집 → 다중 전문 에이전트의 근거 기반 판단 → 종합 판정 → 사람 승인·감사로 이어지는 물류 화물 심사·관리 멀티에이전트 운영 시스템이다. 수작업 중심의 물류 문서 검토를 자동화해 업무 속도를 높이고 데이터 보안을 강화한다.

대상 문서 (3종)

문서	핵심 정보
B/L (Bill of Lading)	선적자·수하인·선박·항만·컨테이너 번호
Commercial Invoice	거래처·품목·단가·총액·통화·Incoterms
Packing List	품목·수량·박스 수·중량·부피

3종은 같은 화물에 대해 교차 검증이 가능하며, 불일치를 잡아내는 것이 검토 시나리오의 핵심 가치다.

아키텍처

• 진입/인증: 사용자(브라우저) → CloudFront(웹앱) → Cognito User/Identity Pool → IAM 임시 자격증명 → Bedrock Supervisor Agent 직접 호출(API Gateway 미사용).
• 자동 수집(ingest): 파일 업로드 → S3(Raw) 이벤트 → Lambda: OCR(Textract) → PII 마스킹(Comprehend) → 번역(Translate) → Bedrock 유형분류·필드매핑 → DynamoDB. 고위험은 S3(Quarantine) 격리. 에이전트 도구가 아니라 에이전트 진입 전 도는 결정론 파이프라인이라 LLM이 마스킹을 건너뛸 수 없다.
• 오케스트레이션: Supervisor + 협업자 3(A Document / B Regulation / C Realtime). 각 에이전트가 도구를 선택·조합하고, 복합 요청은 Supervisor가 결과를 모아 종합 판정한다.
• 보안·운영: Secrets Manager(실시간 API 키), Guardrails·Macie(계획), SNS(관리자 알림), CloudWatch/CloudTrail.

에이전트 구성 (Supervisor + 3 Subagent)

Supervisor는 A/B/C 상위 라우팅을 담당하며, "이 화물 지금 출고해도 되나" 같은 복합 요청은 여러 협업자를 호출해 종합 판정(출고 진행 / 보완 후 진행 / 보류 + 위험도 + 차단·보완 사유 + 권장 조치 + Agent 타임라인)한다.

에이전트	도구	설명
A · Document Agent	query_documents / list_documents	건 단위·보유 문서 목록 조회 (수집이 저장한 마스킹 데이터)
	generate_document	자연어 요청 + 기존 데이터로 문서 자동 작성 (HTML 미리보기·PDF)
	cross_check_documents	B/L↔Invoice↔Packing 교차검증·누락 판정
B · Regulation Agent	lookup_regulation	OpenSearch 규정 RAG 검색 (최신성·출처 역할 필터, 근거·적용조건 포함)
	verify_compliance_checklist	업로드된 CI·PL·B/L의 추출 필드와 규정 근거를 대조해 pass/fail/warning
	compare_regulations	동일 문서 계열의 과거·최신 원문 발췌 비교(시행일 구간 정합). 이력 부족 시 추정 안 함
C · Realtime Agent	fetch_realtime	항만·기상·통관·ETA 신호 조회. 미구성/실패 시 추정·참고용 라벨값
	fetch_exchange_and_customs_rates	시장 환율과 공식 관세환율을 별도로 조회
	assess_logistics_impact	실시간 신호를 일정·통관·비용 위험 및 권고 조치로 변환

핵심 기능 (구현·배포됨)

• Supervisor 종합판정 — 복합 요청에서 A/B/C를 실제로 병렬 호출해 판정 카드 생성 (라이브 trace 검증 완료).
• 규정 RAG — OpenSearch Knowledge Base + 실제 규정 코퍼스(관세법·대외무역법·WTO·WCO·UNCITRAL·RCEP·IPEF 등), 출처·시행일 인용.
• 실시간 실연동 — Secrets Manager로 KMA(기상·특보)·해수부(항만)·UNI-PASS(HS·관세율·요건·통관)·관세환율 연결. 라이브 실패 시 명시 라벨된 추정값.
• 승인/반려 + 감사 — set-review-status(불변 감사 이벤트·낙관적 락·EventBridge). IAM 그룹 reviewer(저위험)/review-admin(고위험·보류).
• 가입 승인 자동화(SES) — PostConfirmation → 관리자 승인 메일 → 원클릭 approve/reject → approved 그룹 편입.
• 대화 영속화 — DynamoDB per-user 격리(Cognito Identity LeadingKeys), 브라우저 localStorage 폴백.
• 문서 라이브러리 + 완전삭제 — 원본/생성문서 열람·다운로드·삭제(S3 삭제 → document-cleanup이 DynamoDB 레코드까지 정리).
• 프론트 최적화 — 로고 WebP, AWS SDK 동적 import(초기 번들 제외), 벤더 청크 분리, 배포 후 stale 청크 self-heal.

아키텍처 원칙

• 오케스트레이터: Supervisor Agent + 도구 세트 기반 Subagent 3개 (Step Functions·API Gateway·GuardDuty 미사용).
• Lambda는 Action Group 실행 계층(S3/DynamoDB·KB·외부 API 접근) + 자동 수집·정리 트리거로만 사용.
• 보안은 결정론 인프라로 강제(PII 마스킹은 LLM 밖 파이프라인, S3/DynamoDB 유저별 격리).
• 상세: docs/architecture.md · 종합판정 설계: docs/supervisor-synthesis.md · 보안 계층 설계(Guardrails·Macie, 후속): docs/security-design.md · 변경 이력: docs/build-log.md · 시연 시나리오: docs/demo-scenario.md

폴더 구조

lighthouse-agent/
├─ docs/           문서 (architecture, build-log, supervisor-synthesis, demo-scenario, assets/)
├─ frontend/       React + Vite 웹앱 (대화 워크스페이스 · Cognito · 결과 패널 · 라이브러리)
├─ backend/
│  ├─ lambdas/     document-ingest·document-cleanup / query·list·generate·cross-check-documents
│  │               lookup·compare-regulations·verify-compliance-checklist
│  │               realtime-fetch·fetch-exchange-customs-rates·assess-logistics-impact
│  │               set-review-status·notification-preferences·access-request-created/decision
│  └─ shared/      공통 유틸 (Bedrock 어댑터·스키마 검증·DynamoDB·Secrets)
├─ infra/          CFN/SAM (auth·hosting·storage·review-audit·access-approval) + bedrock/ 배포 스크립트
├─ agents/         Bedrock Agent 설정 (supervisor, subagents, action-groups)
├─ knowledge-base/ 규정 코퍼스(PDF/MD + 메타데이터) — OpenSearch KB 소스
├─ schemas/        표준 문서 JSON 스키마 (3종)
└─ sample-data/    데모용 세트 (normal / mismatch)

기술 스택

• 인증: Cognito(User/Identity Pool), IAM
• AI/오케스트레이션: Bedrock Agents(Supervisor+3), Knowledge Bases(OpenSearch RAG), (Guardrails 계획)
• 문서 처리: Textract(OCR), Comprehend(PII), Translate, Bedrock(분류·매핑)
  • 확장 여지: OCR 단계는 Upstage Document Parse/OCR로 교체 가능한 어댑터(OCR_PROVIDER)
• 실시간: Secrets Manager + 공공 API(KMA·해수부·UNI-PASS·관세청·관세환율)
• 저장소: S3(Raw/Processed/Quarantine/Frontend), DynamoDB(문서·대화·리뷰이벤트), OpenSearch(벡터)
• 처리/배포: Lambda(Python 3.12), CloudFront, plain CFN + SAM, boto3 배포 스크립트
• 프론트: React + Vite (대화형 워크스페이스)
• 보안·운영(계획): Macie, Bedrock Guardrails, Security Hub

팀

팀원	역할
신승훈	PM / AI·Backend (OCR·문서비교·Agent 흐름·종합판정)
이경윤	Security / Cloud Security (인증·IAM·탐지·감사·SES 승인)
홍정기	AI / Full Stack (프론트·API·RAG·실시간 연동·라이브러리)