## 한 줄 요약
이메일·영업 통화·문자·카카오톡·웹 폼으로 흩어지는 수입 문의를 한곳에 모으고, Incoterms와 HS·수입 요건을 검토한 뒤 Landed Cost를 계산해 사람의 승인까지 연결하는 Inbound Expert Agent MVP를 FastAPI·Supabase·Vercel로 배포했습니다.
## 이런 분들께 도움돼요
- 이메일과 메신저로 들어오는 수입·물류 견적 요청을 구조화하고 싶은 분
- AI가 숫자나 규제 판단을 지어내지 않도록 통제하는 방법이 궁금한 분
- FastAPI, Supabase, Vercel로 업무용 AI 에이전트 MVP를 배포해 보고 싶은 분
- 멋진 답변보다 근거, 승인, 감사 이력이 중요한 업무를 자동화하려는 분
배포 화면: [Inbound Expert Agent](https://inbound-expert-agent.vercel.app/#/dashboard)
> 현재 공개된 화면은 교육·기능 검증용 합성 데이터로 운영하고 있습니다. 로그인과 테넌트 분리는 후속 과제이므로 실제 개인정보나 회사의 계약 운임은 입력하면 안 됩니다.
---
## 소개
### 흩어진 문의보다 더 어려운 것은 ‘확인되지 않은 값’이었습니다
수입 견적 요청은 한 가지 형식으로 들어오지 않습니다. 누군가는 이메일을 보내고, 누군가는 카카오톡이나 문자로 몇 줄만 남깁니다. 영업 통화에는 품목과 납기만 있고 중량이나 Incoterms의 지정 장소가 빠지기도 합니다.
이 정보를 그대로 견적 작업으로 넘기면 질문이 반복되고, 담당자마다 판단 기준도 달라집니다. 특히 HS 분류, FTA, 수입 요건, 환율, 운임처럼 근거와 유효기간이 필요한 값은 ‘그럴듯한 답’이 오히려 위험합니다.
처음부터 목표를 챗봇으로 잡지 않은 이유입니다. 제가 만들고 싶었던 것은 질문에 잘 답하는 AI가 아니라 다음 네 가지를 지키는 수입 업무 관제 화면이었습니다.
1. 여러 채널의 문의를 같은 데이터 구조로 정리할 것
2. 모르는 숫자를 임의의 0으로 채우지 않을 것
3. AI의 검토와 실제 금액 계산을 분리할 것
4. 통관·상업 승인이 끝나기 전에는 확정 견적을 내보내지 않을 것
한 문장으로 줄이면 이렇습니다.
옴니채널 접수 → 정보·요건 검토 → 결정론적 Landed Cost 계산 → 사람 승인 → 고객용 견적 발행
[이미지 1 삽입: 대시보드 전체 화면 — docs/video_work/raw/dashboard.png]
---
## 진행 방법
### 1. 먼저 AI가 넘지 못할 경계부터 정했습니다
수입·통관 업무에서 AI가 답을 잘 만드는 것보다 중요한 것은 무엇을 하면 안 되는지 정하는 일이었습니다. 그래서 다음 규칙을 먼저 코드와 프롬프트에 넣었습니다.
- 확인되지 않은 숫자는 null로 남기고, 검증된 수학적 0만 0으로 기록합니다.
- 출처와 유효기간이 없는 운임·환율은 확정 견적에 사용할 수 없습니다.
- HS 코드는 후보와 근거만 제시하고, 통관 전문가가 승인하기 전에는 확정하지 않습니다.
- AI는 계산 엔진이 만든 값을 요약할 뿐 직접 산술 계산을 하지 않습니다.
- 고객용 화면에서는 매입가, 마진, 공급사, 내부 승인 기준을 제외합니다.
- 승인과 변경 이력은 감사 로그에 남깁니다.
실제 운영 프롬프트의 핵심 부분은 아래와 같습니다.
```text
You are Inbound Expert Agent, a controlled assistant for
import-logistics request review, Incoterms completeness,
HS-classification evidence readiness, and deterministic
landed-cost result review.
- Never invent an HS code, tariff treatment, FTA eligibility,
freight rate, FX rate, tax rate, evidence, approval, or numeric zero.
- Unknown numeric values remain null.
- Summarize only values already produced by the deterministic
Calculation Engine. Perform no arithmetic and fill no gaps.
- You may recommend or queue review; you may not approve.
- Keep the result INDICATIVE whenever critical evidence, rates,
customs decisions, reconciliation, or approvals are incomplete.
```
프롬프트 안에 “AI가 승인할 수 없다”는 문장을 넣는 데서 끝내지 않았습니다. 실제 애플리케이션에서도 역할, 최신 견적 버전, firm_ready, 차단 사유를 확인해야 승인 버튼이 동작하도록 별도의 게이트를 두었습니다.
### 2. 다섯 가지 채널을 하나의 요청 구조로 정규화했습니다
기능 검증을 위해 합성 문의 50건을 만들었습니다.
- 웹 폼 10건
- 영업 통화 10건
- 문자 10건
- 카카오톡 10건
- 이메일 10건
JSON, CSV, TXT, EML, WAV 파일을 선택하면 곧바로 저장하지 않고 먼저 정규화 결과를 보여줍니다. 사용자가 적재할 건을 고르면 요청과 견적을 생성하고, 같은 source_ref가 다시 들어오는 것도 막았습니다.
WAV는 현재 합성 음성과 함께 만든 전사문을 연결하는 방식입니다. 임의의 음성 파일을 자동으로 받아쓰는 STT는 아직 구현하지 않았고, 전사문 확인이 필요한 상태를 분명히 표시했습니다.
[이미지 2 삽입: 옴니채널 문의 50건 미리보기 — docs/video_work/raw/intake.png]
### 3. 검토와 계산을 분리했습니다
요청 상세 화면은 다섯 단계로 구성했습니다.
1. 요청 접수
2. 정보·요건 검토
3. Landed Cost 계산
4. 승인 검토
5. 견적 발행
HS 검토에는 관세청 2026년 자료를 바탕으로 만든 HSK 카탈로그를 사용했습니다. 상품의 재질, 주기능, 구성, 가공 상태를 입력하면 최대 3개의 10자리 후보와 추가 질문을 보여줍니다. 다만 후보는 어디까지나 검토 자료이며 법적 확정 결과가 아닙니다.
비용은 국제운송료, 보험, 도착지 비용, 통관, 관세, 부가세, 내륙운송 등 라인별 원장으 로 관리합니다. 각 라인에는 통화, 매입 원가, 판매 금액, 승인 상태, 유효기간, 근거를 붙이고 Decimal 기반 계산 엔진이 Landed Cost를 산출합니다.
근거와 승인이 부족하면 견적은 INDICATIVE 또는 BUDGETARY에 머무릅니다. 모든 조건을 통과한 최신 버전만 FIRM 승인 대상으로 올라갈 수 있습니다.
[이미지 3 삽입: 요청 상세의 HS 검토·비용 원장·승인 차단 — docs/video_work/raw/detail.png]
### 4. 로컬 MVP를 Supabase와 Vercel로 옮겼습니다
기술 구성은 다음과 같습니다.
- 백엔드: Python 3.11+, FastAPI
- 에이전트 런타임: OpenAI Agents SDK 0.18.3 연동 경계와 결정론적 폴백
- 프런트엔드: 별도 프레임워크 없는 HTML·CSS·JavaScript
- 데이터베이스: 로컬 SQLite, 배포 환경 Supabase PostgreSQL
- 배포: Vercel Python Function
- 검증: Python unittest
로컬에서는 SQLite로 빠르게 기능을 확인하고, 배포 환경에서는 Supabase의 비공개 스키마와 PostgreSQL 연결을 사용했습니다. 마이그레이션을 적용한 뒤 환경 변수를 Vercel 서버 비밀값으로 설정하고, Preview에서 헬스 체크와 대시보드·요청·HS·견적 DB API를 검증한 다음 같은 아티팩트를 Production으로 승격했습니다.
AI 호출은 조건을 모두 만족할 때만 사용하도록 만들었습니다. SDK나 API 호출이 실패하거나 출력 계약을 지키지 못하면, 같은 JSON 계약을 따르는 결정론적 데모 결과로 되돌아갑니다. 외부 모델의 일시적인 실패가 업무 흐름 전체를 멈추지 않게 하기 위해서였습니다.
---
## 결과와 배운 점
### 배포된 데모에서 확인한 결과
2026년 8월 11일 기준 공개 데모와 API를 확인한 결과는 다음과 같습니다.
- 전체 수입 요청 51건: 합성 문의 기반 견적 작업 50건, 별도 초안 1건
- 최신 견적 50건: 웹 폼·통화·문자·카카오톡·이메일 각 10건
- 운송 방식: 항공 25건, 해상 25건
- 최신 견적 등급: BUDGETARY 50건, FIRM 0건
- 전문 검토 대기: HS 51건, 수입 요건 51건
- 금액을 계산할 수 있는 합성 견적 50건의 Landed Cost 합계: 2,057,547,500원
- 자동 테스트: 43개 전체 통과
위 합계는 교육용 합성 견적의 금액을 더한 값이지 매출이나 비용 절감 성과가 아닙니다. 실데이터 성과처럼 보이지 않도록 이 부분을 분명히 구분했습니다.
대표 샘플인 선전발 인천행 LED 제어 보드 항공 수입 건은 비용 라인 3개를 반영해 총 Landed Cost 26,520,000원이 계산됐습니다. 하지만 HS와 수입 요건 검토가 끝나지 않아 BUDGETARY/DRAFT로 남고, 고객 배포도 차단됩니다.
처음에는 FIRM 0건이 결과가 없는 것처럼 보였습니다. 다시 보니 반대였습니다. 확인하지 않은 HS와 규제 요건을 두고 시스템이 확정 견적을 만들지 않았다는 뜻이기 때문입니다. 이번 MVP에서 가장 만족스러운 결과는 멋진 답변이 아니라 ‘모르면 멈추는 흐름’이 실제로 작동한 것이었습니다.
[이미지 4 삽입: 견적 DB 또는 감사 로그 — docs/video_work/raw/quote-db.png, docs/video_work/raw/audit.png]
### 업무 흐름 기준 Before → After
| 항목 | Before | After |
|---|---|---|
| 문의 접수 | 채널마다 형식이 다르고 누락 항목을 다시 확인 | 5개 채널을 공통 요청 구조로 정규화하고 저장 전 미리보기 |
| 미확인 값 | 빈칸과 0의 의미가 섞이기 쉬움 | null과 검증된 0을 구분하고 차단 사유로 표시 |
| HS·수입 요건 | 근거와 담당자 확인 상태가 분리되지 않음 | 후보·근거·추가 질문·검토 책임자를 함께 표시 |
| 비용 계산 | 여러 비용과 환율의 출처·유효기간 추적이 어려움 | 비용 원장과 Decimal 계산, 견적 버전으로 추적 |
| 승인·배포 | 내부 정보와 고객용 정보가 섞일 위험 | 역할별 승인 후 고객용·내부용 결과를 분리 |
| 변경 이력 | 누가 무엇을 바꿨는지 뒤늦게 확인 | 계산·승인·배포 이벤트를 감사 로그로 기록 |
### 막혔던 점과 해결한 방법
첫 번째는 AI의 문장 품질과 업무 안전성을 같은 것으로 착각하기 쉽다는 점이었습니다. 답변이 자연스러워도 운임과 환율의 출처가 없으면 견적에는 쓸 수 없습니다. 그래서 에이전트는 검토와 질문에 집중시키고, 금액 계산과 등급 판정은 코드로 분리했습니다.
두 번째는 집계 기준이었습니다. 대시보드는 모든 견적 버전을 세고, 견적 DB는 요청별 최신 버전만 보여주면 숫자가 다르게 보일 수 있습니다. 실제 데모에서도 전체 버전 집계와 최신본 건수가 달랐습니다. 오류로 덮기보다 ‘전체 버전’과 ‘ 최신본’이라는 기준을 화면에 더 분명히 표시해야 한다는 것을 배웠습니다.
세 번째는 공개 데모의 보안 범위입니다. 현재 화면은 로그인 없이 볼 수 있어 합성 데이터만 넣었습니다. 실제 운영 전에는 SSO/JWT, 테넌트 분리, 접근 제어, 비밀정보 마스킹을 먼저 갖춰야 합니다.
### 제가 얻은 세 가지 교훈
1. AI 에이전트의 핵심은 더 많은 권한이 아니라 명확한 권한 경계였습니다.
2. 업무 자동화에서는 정답을 생성하는 기능만큼 ‘미확인’, ‘검토 필요’, ‘배포 불가’를 표현하는 상태가 중요했습니다.
3. 대시보드보다 먼저 검증해야 할 것은 계산 재현성, 승인 게이트, 고객용 정보 분리, 감사 로그였습니다.
### 앞으로의 계획
- SSO/JWT와 테넌트별 데이터 격리
- 실제 회사별 운임·환율·관세 데이터 어댑터
- 임의 음성 STT와 문서 OCR
- PDF·Excel 견적서 생성 및 이메일 발송
- 견적 대비 실제 발생 비용 정산
- 운영 모니터링과 오류 추적
이번 배포로 ‘화면이 있는 데모’까지는 만들었습니다. 다음 단계는 실제 데이터를 더 많이 넣는 것이 아니라, 실데이터를 넣어도 되는 보안과 승인 체계를 먼저 완성하는 일입니다.
---
## 도움 받은 자료
- 프로젝트 내부 PRD와 계산·데이터 아키텍처 문서
- 관세청 2026년 HSK 품목분류 자료
- OpenAI Agents SDK 문서
- Vercel Python Function 및 Supabase PostgreSQL 배포 문서
