우리는 가공되지 않은 물류 알림을 읽고 구조화된 분류(triage) 데이터를 반환하는 배송 예외 분석기(shipment exception analyzer)를 구축할 것입니다. 물류 팀은 매일 수백 개의 비구조화된 지연 통지, 항만 혼잡 업데이트, 운송업체 예외 사항을 처리합니다. 이 에이전트는 이러한 텍스트 뭉치를 심각도 점수와 권장 다음 단계가 포함된 구조화된 JSON으로 변환합니다.

필요한 사항

• Python 3.10 이상
• https://portal.oxlo.ai에서 발급받은 Oxlo.ai API 키
• OpenAI SDK: pip install openai

1단계: Oxlo.ai 클라이언트 설정

OpenAI SDK가 Oxlo.ai를 가리키도록 설정합니다. 저는 API 키를 환경 변수(environment variable)에 보관하지만, 빠른 테스트를 위해 직접 붙여넣을 수도 있습니다.

import os
from openai import OpenAI

...

2단계: 시스템 프롬프트(system prompt) 작성

시스템 프롬프트는 에이전트의 동작을 변경하기 위해 수정해야 하는 유일한 부분입니다. 이는 출력 스키마(output schema)와 어조를 정의합니다.

SYSTEM_PROMPT = """당신은 물류 예외 분석가입니다. 사용자의 가공되지 않은 알림을 읽고 정확히 다음 필드를 가진 JSON 객체를 반환하세요:
- shipment_id: string 또는 null
- exception_type: string, 예: "delay", "damage", "misroute", "customs_hold"
...

3단계: JSON 모드를 사용하여 구조화된 데이터 추출

단일 알림을 대상으로 에이전트를 테스트합니다. 저는 지시 사항을 안정적으로 따르는 Llama 3.3 70B를 사용하며, 출력이 기계가 읽을 수 있도록 JSON 모드(JSON mode)를 활성화합니다.

import json
from openai import OpenAI

...

4단계: 일일 알림 피드 배치 처리(Batch process)

실제 운영 환경에서는 수십 개의 알림을 한꺼번에 받게 됩니다. 이 루프는 각 알림을 Oxlo.ai로 보내고 결과를 수집합니다. Oxlo.ai는 요청 기반 요금제(request-based pricing)를 사용하므로, 알림이 수천 개의 토큰(token)이 포함된 긴 EDI 메시지인 경우에도 비용을 예측할 수 있습니다.

import json
from openai import OpenAI

...

실행하기

스크립트를 exception_agent.py로 저장하고, OXLO_API_KEY를 내보낸(export) 후, python exception_agent.py를 실행하세요. 첫 번째 알림은 다음과 유사한 JSON을 반환해야 합니다:

{
  "shipment_id": "MSCU1234567",
  "exception_type": "customs_hold",
...

다음 단계 (Next steps)

이 에이전트를 확장할 수 있는 두 가지 구체적인 방법이 있습니다. 첫째, 출력을 Slack 웹훅 (webhook)에 연결하여 중요한 알림이 운영 채널로 자동 전송되도록 설정하는 것입니다. 둘째, Oxlo.ai의 Qwen 3 32B로 교체하여 코드 변경 없이도 국제 운송업체의 다국어 알림을 처리하는 것입니다. 해당 플랫폼은 OpenAI SDK와 완전히 호환되기 때문에 가능합니다.