선박 체선료(Demurrage) 비용을 최소화하기 위한 에이전트 기반 선석 할당기 및 대기열 스케줄러 구축기

의존성 기반 멀티 에이전트 시뮬레이션을 통한 해상 항만 혼잡 최적화

선박 체선료(Demurrage) 비용을 최소화하기 위한 에이전트 기반 선석 할당기 및 대기열 스케줄러 구축기

요약 (TL;DR)

이 문서는 글로벌 무역의 주요 병목 현상인 해상 항만 혼잡 및 선박 스케줄링 문제를 해결하기 위해 제가 수행한 개인적인 실험에 대한 기록입니다. 제가 관찰한 바에 따르면, 항만들은 전통적으로 동적인 체선료(Demurrage) 페널티나 물리적인 선박 제약 조건을 고려하지 못하는 경직되고 선형적인 선입선출 (FCFS, First-Come-First-Served) 배차 로직에 의존하고 있습니다. 이 문제를 연구하기 위해 저는 AnchorFlow-AI라는 이름의 모듈형 Python 시뮬레이션 엔진을 구축했습니다. 이 시스템은 특화된 에이전트들이 협력하여 선석 접안 통과를 스케줄링하고 공유 자원(예인선 및 도선사)을 관리하는 의존성 기반 멀티 에이전트 (Multi-Agent) 배차 최적화기를 구현합니다. 시뮬레이션된 기상 악화 및 장비 고장 상황에서, 저의 에이전트 기반 조정 프레임워크는 FCFS 기준점과 비교했을 때 선박 대기 시간을 16.4% 감소시켰으며, 체선료(Demurrage) 페널티를 480,000달러(USD) 이상 절감했습니다. 코드베이스는 검증을 위해 GitHub에 공개되어 있습니다.

서론 (Introduction)

글로벌 공급망은 해상 항만의 효율성에 달려 있지만, 항만 운영은 여전히 심각한 지연에 취약한 상태로 남아 있습니다. 물류 운영을 관찰해 온 제 경험에 따르면, 컨테이너선, 건화물선(dry bulk carriers), 그리고 Suezmax급 유조선의 스케줄링은 여전히 정적인 스프레드시트나 기본적인 스케줄링 규칙을 사용하여 관리되는 경우가 많습니다. 짙은 안개로 인해 항만 채널이 폐쇄되거나 선석 크레인(berth crane)에 기계적 결함이 발생하면, 항만 운영 스케줄러는 조합론적 악몽(combinatorial nightmare)에 직면하게 됩니다. 입항 선박의 경로를 재설정하고, 크레인 작업 팀을 재배치하며, 항만 도선사(harbor pilots)나 예인선(tugboats)의 일정을 재조정하는 작업에는 동적이고 다각적인 트레이드오프(trade-offs)가 필요합니다.

제가 이 글을 쓴 이유는 Prompt-Agent-Skill 프레임워크가 이러한 조정(coordination) 문제를 해결할 수 있는지 조사하고 싶었기 때문입니다. 제 생각에 물류 분야에서 지능형 시스템을 활용하는 가장 영향력 있는 방법은 단순한 자동화된 계획(automated planning)이 아니라, 능동적인 전달 오케스트레이션(active delivery orchestration)입니다. 저는 선박 에이전트(vessel agents), 선석 할당 에이전트(berth allocation agents), 그리고 자원 이동 에이전트(resource transit agents)가 수십억 달러 규모의 비즈니스 문제를 해결하기 위해 실시간으로 협력하는 시뮬레이션을 설계하고 싶었습니다.

이 연구를 엄격하고 투명하게 유지하기 위해, 저는 단일 노트북에서 실행되는 독립적인 Python 시뮬레이터를 구축했습니다. 외부 클라우드 의존성이나 호스팅된 데이터베이스를 피하는 대신, 데이터 처리를 위해 NumPy와 Matplotlib을 사용하는 순수 Python 모듈을 작성하는 방식을 선택했습니다. 이 실험적 기술서에서는 제가 내린 수학적 및 구조적 설계 결정에 대해 상세히 설명하고, 코드베이스를 섹션별로 살펴보고, 에이전트 기반 최적화 도구(agentic optimizer)의 결과를 전통적인 스케줄링 정책과 비교합니다.

[

]

이 글은 무엇에 관한 것인가요?

1. 이 글은 항만 혼잡(port congestion)과 체선료(demurrage) 비용을 완화하기 위해 구축된 에이전트 기반 해상 시뮬레이션 플랫폼인 AnchorFlow-AI의 설계 및 구현을 상세히 다룹니다.
2. Prompt-Agent-Skill 디자인 패턴을 물류 오케스트레이션(logistics orchestration)을 위한 기능적인 멀티 에이전트 조정 루프(multi-agent coordination loop)로 어떻게 변환했는지 설명합니다.
3. 체선료 누적률(demurrage accumulation rates)을 기반으로 정박 대기열(anchorage queues)을 동적으로 평가하기 위해 설계한 수학적 트리아지 가중치(mathematical triage weight) 공식을 기술합니다.
4. 개별 스킬(skills)이 항만 환경 내에서 어떻게 관리, 검증 및 실행되는지 보여주며 전체 소스 코드를 살펴봅니다.
5. 동일한 기상 및 기계적 장애 시퀀스 하에서 FCFS(First-Come, First-Served) 방식과 에이전트 기반 스케줄링(Agentic scheduling) 실행 결과에 대한 비교 데이터 분석을 제시합니다.

기술 스택 (Tech Stack)

1. Python 3.12: 시뮬레이터, 에이전트 로직 및 실행 CLI를 구현하는 데 사용된 핵심 프로그래밍 언어입니다.
2. NumPy & Pandas: 통계적 이벤트 생성, 데이터 조작 및 지표 계산에 활용되었습니다.
3. Matplotlib: 시뮬레이션 로그를 컴파일하고 비교 성능 차트를 출력하는 데 사용되었습니다.
4. Rich: 명령줄 인터페이스(CLI)에서 상세한 ASCII 지표 테이블을 포맷팅하고 렌더링하기 위해 통합되었습니다.

읽어야 하는 이유

1. 에이전트 기반 디자인 패턴(agentic design patterns)을 운영 연구(operational research)에 적용하는 방법을 탐구하고 있다면, 이 PoC(Proof of Concept)는 자원 할당을 위한 구체적인 멀티 에이전트 프레임워크를 제공합니다.
2. 물류 분야에서 선형 대기 모델(linear queuing models)의 한계를 이해하고 싶다면, 비교 데이터 차트가 지연 전파(delay propagation)를 명확하게 시각화하여 보여줍니다.
3. 재현성(reproducibility)을 중요하게 생각한다면, 전체 프로젝트가 정적 시드(static seed)를 사용하여 로컬에서 실행되도록 구조화되어 있어, 직접 시뮬레이션을 실행하고 결과를 검증할 수 있습니다.
4. 저의 관점에서 이 글은 동적 스케줄링(dynamic scheduling)에 수반되는 트레이드오프(trade-offs)를 정직하게 살펴보고, 휴리스틱 모델(heuristic models)이 실패하고 에이전트 기반 모델(agentic models)이 성공하는 지점을 정확히 보여줍니다.

설계하기 (Let's Design)

항만 물리 및 자원 토폴로지 (Port Physical & Resource Topology)

제 관점에서는 항만 혼잡 (port congestion)을 모델링하기 위해 물리적 인프라와 공유 통항 자원 (shared transit resources)에 대한 고충실도 (high-fidelity) 표현이 필요합니다. 저는 항만 토폴로지 (port topology)를 세 가지 별개의 엔티티, 즉 정박 대기 구역 (anchorage waiting areas), 선석 (berths), 그리고 항만 통항 자원 (harbor transit resources)을 중심으로 구조화했습니다.

1. 정박 대기열 (Anchorage Queue): 선박이 도착 시 닻을 내리는 지정된 해상 대기 구역입니다. 선박이 정박 대기열에 머무는 동안, 용선 계약 (charterparty agreement)에 따라 체선료 (demurrage costs)가 발생합니다.
2. 선석 (Berths): 화물 작업이 이루어지는 전용 독 (dock) 공간입니다. 각 선석은 전장 (LOA, Maximum Length Over All) 및 최대 흘수 (Maximum Draft Depth)를 포함한 고유한 물리적 사양을 가집니다. 14미터의 흘수를 가진 Suezmax 탱커는 수심이 10미터인 피더 컨테이너 선석 (feeder container berth)에 접안할 수 없습니다. 또한, 각 선석은 사용 가능한 갠트리 크레인 (gantry cranes)의 수에 따라 서로 다른 하역 속도 (discharge rates)를 나타냅니다.
3. 공유 통항 자원 (Shared Transit Resources): 입항 및 출항 이동에는 두 가지 핵심 자원이 필요합니다. 선박을 안내하는 항만 도선사 (harbor pilot)와 접안 기동을 보조하는 예인선 (tugboats) 함대(통상 선박당 2척)입니다. 도선사와 예인선의 수가 제한되어 있기 때문에, 통항 작업 (transit operations)은 주요한 운영 병목 현상 (operational bottleneck)을 나타냅니다.

Prompt-Agent-Skill 프레임워크

저는 스케줄링 최적화 도구 (scheduling optimizer)를 Prompt-Agent-Skill 패턴을 중심으로 구조화했습니다. 이 패턴은 불투명하고 단일한 (monolithic) 에이전트 방식에서 벗어나, 에이전트의 행동을 엄격한 입출력 검증 규칙에 의해 제어되는 원자적이고 재사용 가능한 실행 블록 (skills)으로 분해합니다.

1. Triage Agent (TriageAnchorageQueue Skill): 이 에이전트는 정박 대기열 (anchorage queue)을 모니터링하는 역할을 담당합니다. 선박을 선입선출 (first-come-first-served) 방식으로 처리하는 대신, 각 선박의 체선료율 (demurrage rate)과 경과 대기 시간을 평가하여 동적 가중치 (dynamic weight)를 계산합니다. 이 스킬 (skill)은 정렬된 우선순위 목록을 출력합니다.
2. Berth Allocator Agent (MatchBerths Skill): 이 에이전트는 우선순위가 지정된 선박을 가용 선석 (berth)에 매칭합니다. 선박의 물리적 크기나 흘수 (draft) 제약 조건을 위반하는 선석을 필터링합니다. 그 후 예상 화물 하역 시간 (cargo discharge times)과 선석 활용도 (berth utilization)를 기반으로 호환 가능한 매칭에 점수를 부여합니다.
3. Transit Agent (VerifyTransitResources Skill): 이 에이전트는 리소스 풀 (resource pools)을 확인합니다. 통항 시간대 (transit window)를 승인하기 전에 최소 한 명의 도선사 (pilot)와 필요한 수의 예인선 (tugboat)이 사용 가능한 상태인지 확인합니다.
4. Operations Coordinator Agent: 이 에이전트는 오케스트레이터 (orchestrator) 역할을 합니다. 단계별 로직을 실행하고, 다른 에이전트들을 호출하며, 리소스를 할당하고, 동적인 중단 상황 (dynamic disruptions)을 처리합니다.

동적 중단 처리 (Dynamic Disruption Handling)

정적 스케줄링 알고리즘의 주요 한계는 실시간 이벤트에 적응하지 못한다는 점입니다. 본 설계에서는 에이전트 시스템 (agentic system)의 자가 치유 (self-healing) 능력을 테스트하기 위해 항만 중단 (Port Disruption) 모델을 구현했습니다.

1. 기상 방해 (Weather Interruptions): 짙은 안개나 높은 너울 (high swells)은 항만 수로를 폐쇄할 수 있습니다. 수로 폐쇄 중에는 모든 입항 및 출항 통항이 차단되어, 활동 중인 선박은 선석에 갇히거나 도착하는 선박은 정박지 (anchorage)에서 대기해야 합니다.
2. 기계적 결함 (Mechanical Failures): 선석의 크레인 고장은 시간당 하역율 (discharge rate)을 감소시킵니다 (예: 50% 감소).
3. 자가 치유 루프 (Self-Healing Loop): 중단이 발생하면, Operations Coordinator Agent는 즉시 활성 스케줄을 무효화하고 전체 대기열 분류 (queue triage)를 트리거합니다. Triage Agent는 업데이트된 지연 예측치를 사용하여 체선료 위험 가중치 (demurrage risk weights)를 재계산하며, 이를 통해 통항 시간대가 다시 열리는 즉시 비용이 높은 선박이 우선순위를 갖도록 보장합니다.

본격적으로 시작해 봅시다

코드베이스는 article_ouput_tobe_deleted_after_article_done/AnchorFlow-AI/ 아래에 모듈형 Python 패키지로 구성되어 있습니다. 아래에서는 각 파일을 살펴보고, 설계 방식을 설명하며, 제가 내린 기술적 결정들을 강조하겠습니다.

1단계: 항만 제약 조건 정의 (src/config.py)

먼저 설정(configuration) 모듈을 작성하는 것으로 시작했습니다. 하드코딩된 상수(hardcoded constants)를 피하기 위해 모든 물리적 및 운영 매개변수를 중앙 집중화하고자 했습니다.

"""
AnchorFlow-AI를 위한 항만 설정 사양.
선석(berths), 선박(vessels), 예인선/도선사(tugs/pilots)에 대한 물리적 및 운영 한계를 정의합니다.
...

기능: 이 모듈은 시뮬레이션되는 모든 항만 인프라에 대한 스키마(schema)와 데이터 매개변수를 정의합니다. PortConfig 데이터 클래스(dataclass)는 다양한 길이 및 수심 제한을 가진 3개의 선석을 채우고, 서로 다른 화물 범위와 시간당 체선료(demurrage fees, 시간당 $1,200에서 $6,000 사이)를 가진 4가지 범주의 선박을 등록하며, 초기 리소스 풀(도선사 2명 및 예인선 4척)을 정의합니다.

이렇게 구조화한 이유: 기본 스키마에 영향을 주지 않으면서 매개변수 탐색(parameter sweeps) 중에 설정 인스턴스를 쉽게 복사하고 수정할 수 있도록, 기본 팩토리 메서드(default factory methods)를 포함한 Python dataclasses를 사용하기로 했습니다. 이 구조는 정적 타이핑(static typing) 지원을 제공합니다.

배운 점: 초기 설계에서는 선석 치수를 라우팅 로직(routing logic)에 직접 하드코딩했습니다. 이는 다양한 항만 토폴로지(topologies)를 테스트할 때 빠르게 관리 불가능한 상태가 되었습니다. 물리적 한계를 스케줄링 로직으로부터 분리함으로써, 알고리즘 파일을 수정하지 않고도 리소스 수 감소(예: 도선사 파업 시뮬레이션)가 전체 체선료 누적에 어떤 영향을 미치는지 테스트할 수 있었습니다.

2단계: 선박 상태 및 체선료 모델링 (src/vessel.py)

다음으로, 각 선박의 물리적 속성과 운영 상태를 추적하기 위해 Vessel 클래스를 구현했습니다.

"""
항만 시뮬레이션 내 화물선(cargo vessels)을 나타내는 Vessel 클래스.
물리적 사양, 상태 전이(state transitions) 및 체선료(demurrage) 지표를 추적합니다.
...

기능 설명: 이 모듈은 선박의 상태 머신(state machine)을 정의합니다. VesselState 열거형(enum)은 5개 단계에 걸친 선박의 진행 상황을 추적합니다. Vessel 클래스는 도착, 접안 및 출항 타임스탬프를 유지하며, 회항 시간(turnaround time)과 대기 시간(waiting time)을 계산하기 위한 속성(properties)을 제공합니다. 또한 누적된 체선료를 계산하기 위한 update_demurrage 메서드를 포함하고 있습니다.