배송 예외 관리 AI 에이전트 구축기: Shipment Exception Commander

배송 예외 관리가 어려운 이유는 대응책이 부족해서가 아닙니다. 근거마다 신뢰 수준이 다르고, 대체 운송 견적에는 유효기간이 있으며, 비용에 따라 승인 단계가 달라지고, 성급하게 재시도하면 첫 예약이 이미 성공한 뒤 두 번째 예약까지 생길 수 있기 때문입니다.

Shipment Exception Commander는 배송 지연 대응에서 생기는 바로 이 의사결정 경계를 다루는 오픈 소스 Claude Managed Agents 레퍼런스 애플리케이션입니다. 하나의 합성 예외를 점검하고, 모든 복구 옵션을 기계적으로 점수화하며, 독립적인 위험 검증을 맡긴 뒤, 실행할 정확한 조치를 사람에게 제시합니다. 기본 제공 승인 기능으로 사람이 승인한 뒤에만 샌드박스 상태를 멱등 방식으로 단 한 번 변경할 수 있습니다.

배송 예외 관리의 첫 단계, 모델 판단에 앞선 결정론적 점수화

코디네이터는 운임을 지어내거나 서술형 문장을 정책으로 간주하지 않습니다. 서버 측 읽기 전용 shipment_intelligence 툴은 세 가지 합성 사례를 제공하고 고정 공식으로 각 옵션의 점수를 계산합니다. 약속 이행 50점, 재고 충족 20점, 절대 상한 대비 비용 효율 20점, 신뢰도 10점입니다. 각 옵션에는 견적 버전과 만료 시각, ETA, 보호 물량 수, 추가 USD 비용이 포함됩니다.

대표 검증 사례인 SCX-2026-071은 실제 의사결정에서 마주치는 세 가지 형태를 비교했습니다. 비용은 낮지만 약속 기한을 놓치는 해상 운송, 절대 지출 상한을 넘는 전량 항공 운송, 그리고 약속된 240개 전량을 $4,200에 보호하는 분할 항공 긴급 운송입니다. 분할 옵션은 91점을 받아 운영자 한도 $5,000 안에 들었습니다. 점수 덕분에 추천은 재현 가능해지고, Claude는 근거를 모으고 가정을 검증하며 선택의 득실을 설명하는 데 집중합니다.

신뢰할 수 없는 근거로는 실행을 승인할 수 없습니다

한 운송사 메모에는 에이전트에게 승인 정책을 무시하고 프리미엄 옵션을 예약하라는 지시문 형태의 텍스트가 의도적으로 들어 있습니다. 워크플로는 이 메모를 신뢰할 수 없는 정보로 표시해 근거로 보존하되, 지시로는 명시적으로 배제합니다. 정책의 출처는 버전이 관리되는 합성 카탈로그와 어댑터뿐이며, 운송 관련 서술이나 툴 출력은 정책이 될 수 없습니다.

코디네이터에는 세션 간 쓰기가 가능한 메모리나 볼트, MCP 연동, 외부 네트워크 접근도 없습니다. 자동 승인되는 예외는 범위를 좁힌 read, glob, grep뿐입니다. Bash와 결과물 쓰기에는 always_ask가 적용되고, 편집과 웹 가져오기, 웹 검색은 비활성화되어 있습니다. 정식 상태 변경 경로는 오직 어댑터의 execute 명령입니다.

검증 에이전트가 추천안을 반박 검토합니다

실행을 요청하기 전에 Opus 코디네이터는 제안된 복구안을 좁은 역할의 Haiku 검증 에이전트에 맡깁니다. 검증 실행에서는 NEEDS_CHANGES가 반환됐습니다. 견적 Q-071-v4가 아직 유효한지, 용량과 할증료가 확정됐는지 확인할 수 없었기 때문입니다. 코디네이터는 이 문제를 그냥 넘기지 않았습니다. 결정론적 제안 검증기를 호출해 합성 시각, 견적 만료, 정책 버전, 지출 등급, 예상 상태 버전을 다시 확인했습니다. 권위 있는 ready_for_human_approval 결과가 나온 뒤에야 최종 상태가 준비 완료로 바뀌었습니다.

이후 승인 요약서에는 사례 및 옵션 ID, 정확한 지출액 $4,200, 기존 및 변경 ETA, 고객 약속에 미치는 영향, 보호되는 240개 물량, 견적 만료, 정책 및 상태 버전, 점수, 검증 이력, 제외된 대안, 고정 멱등성 키, 예상 영수증 필드, 거부 및 실패 시 동작이 모두 공개됐습니다.

거부하면 상태는 바뀌지 않습니다

첫 번째 기본 제공 승인 카드는 의도적으로 거부했습니다. 상태를 바꾸는 명령은 실행되지 않았고, 상태는 버전 3의 detected로 유지됐습니다. 영수증은 생성되지 않았으며 멱등성 키도 사용되지 않았습니다. 에이전트는 다른 툴로 바꾸거나 명령을 수정하지 않았고, 새 키를 만들어내지도 않았습니다.

운영자가 명시적으로 다시 요청하자 동일한 정식 조치를 한 번 더 제시했습니다. 이번에는 승인됐습니다. 어댑터는 상태 변경 경계에서 상태 버전 3, 견적 유효성, 정책, 승인 등급, 절대 상한 $10,000을 다시 확인했습니다. 실행은 정확히 한 번 이뤄졌고 사례는 버전 3의 detected에서 버전 4의 resolved로 전환됐습니다. 반환된 영수증은 rcpt_37105a2da411aee0391c, 예약 참조는 SBX-56DFC3291972입니다.

재실행에는 안전하게, 보장 범위는 명확하게

합성 어댑터는 고정 키 SCX-2026-071:OPT-071-B:v3, OS 수준 잠금, 정식 상태 조회, 영수증 레지스트리를 직접 관리합니다. 같은 의도로 중복 호출하면 기존 영수증을 반환하고, 동일한 키에 서로 다른 의도를 담으면 실패합니다. 오래된 버전, 동시 실행, 부분 쓰기 가능성이 감지되면 무작정 재시도하지 않고 먼저 상태를 점검해야 합니다.

이 보호 장치가 보장하는 실제 경계도 의도적으로 분명히 밝혔습니다. 잠금과 상태, 영수증 레지스트리는 하나의 Managed Agents 샌드박스 안에 있는 세션 로컬 파일입니다. 분산 프로덕션 환경까지 보장하지는 않습니다. 실제 운송사나 TMS 어댑터라면 공유 트랜잭션 저장소와 다운스트림 멱등성 경계가 필요합니다.

결과 평가기가 근거까지 대조했습니다

세션은 /mnt/session/outputs/ 아래에 세 가지 산출물을 기록했습니다. 사람이 읽을 수 있는 복구 패킷, 구조화된 감사 기록, 원본 실행 영수증입니다. Managed Agents outcome은 이 파일들을 카탈로그, 어댑터 소스, 정식 상태, 승인 이력, 영수증 레지스트리와 독립적으로 대조했습니다. 견적 만료 정보 공개, 명시적인 실패 동작, 산출물 매니페스트, 세션 로컬이라는 한계에 대한 보완을 요구한 뒤 satisfied를 반환했습니다.

이후 복구 패킷은 애플리케이션 파일 프록시를 통해 다운로드했습니다. SHA-256은 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b입니다. 기능 세션은 sesn_01CcQjCVoWvNQ7VJLFbuDJxh, outcome은 outc_01GoD4rsLMh93iQNfAUw63KW입니다.

실제 outcome 실행에서는 UI의 빈틈도 드러났습니다. 부모 세션이 유휴 상태인 동안에도 평가기 자식 스레드가 승인을 요청할 수 있었습니다. 이번 릴리스는 부모의 requires_action 이벤트와 자식 스레드의 evaluated_permission: ask 이벤트 양쪽에서 대기 중인 승인 카드를 복원합니다. 확인 또는 결과가 나오면 카드를 종료하고, 리플레이 과정에서 해결된 프롬프트가 되살아나는 일도 막습니다. 또한 평가기의 session_thread_id는 제한된 브라우저 허용 목록을 거쳐 그대로 전달하며, 결정을 전달하기 전에 정확한 원본 툴 이벤트와 일치하는 경로인지 검증합니다.

별도로 구성한 Sonnet 검증 세션 sesn_01BvSf33BLBbN86w5oDb3BkQ도 수정된 경로를 점검했습니다. 교차 전달된 평가기 툴 이벤트 sevt_013VnmofY8ytk6QwgDtNSYoq에는 스레드 sthr_018HMgpidoN86Qp4iGLZt1q3이 담겼습니다. UI는 같은 툴 및 스레드 ID를 사용해 확인 이벤트 sevt_016ZFv5TdBPKNyEPThzGT36Q을 생성했고, 서버가 이를 수락하자 평가기는 다음 점검을 요청했습니다. 관련 없는 추가 반복에 비용을 쓰지 않도록 이 제한적 검증은 의도적으로 중단했으며, 대표 운송 결과는 계속 만족 판정 상태였습니다.

대표 실행은 Opus, 검증은 Sonnet과 Haiku

프로비저닝된 코디네이터는 계속 claude-opus-5를 사용합니다. 반복 가능한 유료 검증의 비용을 낮추기 위해 로컬 세션에서는 코디네이터 모델만 claude-sonnet-5로 명시적으로 재정의할 수 있으며, 다른 모든 런타임 재정의는 실패 시 닫히도록 설계했습니다. 독립 검증 에이전트는 claude-haiku-4-5를 사용합니다. Sonnet으로 실행한 유료 스모크 세션 sesn_01RTs3wLV41odV9p92eWtrHV는 정확히 SMOKE OK라는 응답을 반환했습니다.

프로덕션 테스트 스위트는 개발자의 .env.local이 구성돼 있어도 자격 증명을 의도적으로 격리합니다. 새로 배포한 환경에는 브라우저 키 입력 필드가 없고, Anthropic 트래픽을 전송하지 않으며, configured: false를 보고하고, 결제 라우트가 503을 반환한다는 점을 검증합니다.

물류 자동화를 위한 공개 레퍼런스, 오류가 나면 안전하게 차단합니다

공개 Vercel 레퍼런스에는 Anthropic 키나 Managed Agents 리소스 ID가 없습니다. 랜딩 페이지와 /api/agent/health는 계속 사용할 수 있지만 세션 생성 요청은 실패와 함께 안전하게 차단됩니다. 도입자는 자신의 Anthropic 계정에서 에이전트와 환경을 프로비저닝해야 하며, 구성된 인스턴스는 다른 사용자가 접근하기 전에 반드시 접근 보호를 적용해야 합니다.

이 프로젝트의 모든 사례, 운송사, 견적, 예약 참조, 상태 전환, 영수증은 합성 데이터입니다. 이 애플리케이션은 운영 통제 패턴을 보여줄 뿐, 실제 운송사 연동이 아닙니다.

릴리스 근거

• 저장소: dvnc-labs/shipment-exception-commander
• 릴리스: v0.1.0
• CI: 정상 완료된 릴리스 실행
• 커밋: 1db0329
• 배포: shipment-exception-commander.vercel.app
• 상태 확인: 실패 시 안전하게 닫히는 에이전트 상태

Shipment Exception Commander의 범위는 일반적인 물류 AI 에이전트보다 의도적으로 좁습니다. 버전이 지정된 근거로 추천하고, 추천안을 반박 검토하고, 정확한 조치에 대해 사람의 승인을 받고, 상태를 한 번만 변경하며, 나중에 무슨 일이 있었는지 재구성할 수 있을 만큼 충분한 증적을 남깁니다. 이 하나의 감사 가능한 약속에 집중합니다.