실전 AI 에이전트 구축 — Soul·Skills·Config 설계 패턴

'AI 에이전트를 만드는 것'은 모델을 고르는 일이 아니다

해양 감시 플랫폼 Skylight의 AI 에이전트 'Shippy'는 실시간 위성 데이터를 분석해 어선 불법 조업, 환경보호구역 침해 같은 사건을 감지합니다. 순찰 선박이 잘못된 방향으로 수백 킬로미터를 이동하면 막대한 자원이 낭비되고 인명 피해도 생길 수 있습니다. 따라서 이 팀이 가장 먼저 직면한 문제는 '어떤 모델을 쓸까'가 아니라 **'이 시스템을 어떻게 신뢰할 수 있게 만들까'**였습니다.

2026년 7월 공개된 기술 블로그에서 Skylight·Allen AI(Ai2) 팀은 실전에서 검증된 에이전트 설계 패턴을 상세히 공개했습니다. 같은 날 IBM 리서치도 모델 라우팅(Model Routing, 작업별 최적 모델 선택)에 대한 반직관적 실험 결과를 발표했습니다. 두 결과 모두 AI 개발을 공부하는 학생과 개발자에게 즉시 적용 가능한 교훈을 담고 있습니다.

AI 에이전트의 세 가지 구성 요소

Soul(영혼): 시스템 프롬프트로 행동 경계를 정한다

Soul은 에이전트의 페르소나와 행동 경계를 정의하는 시스템 프롬프트입니다. Shippy의 경우 두 가지 명시적 금지 항목이 있습니다.

• 법적 판단 금지: 선박이 법을 위반했는지 여부는 사람이 판단하는 영역
• 데이터 범위 초과 추측 금지: 데이터가 뒷받침하지 않는 내용은 생성하지 않음

중요한 점은 이 경계가 파인튜닝(Fine-tuning, 모델 미세 조정)이 아닌 시스템 프롬프트에 명시된다는 것입니다. 프롬프트로 관리하면 감사(Audit)가 가능하고 수정도 쉽습니다.

학생 활용 팁: 자신만의 AI 에이전트를 만들 때, 에이전트가 '하면 안 되는 것'을 시스템 프롬프트에 구체적으로 명시하세요. 이것이 안전한 에이전트의 출발점입니다.

Skills(기술): 마크다운 파일로 버전 관리되는 능력

Shippy의 Skills는 Claude Code·Codex 같은 코딩 도구와 동일한 agent-skills 스펙을 따릅니다. 구조화된 메타데이터(Frontmatter)가 있는 일반 마크다운 파일로 관리되어 버전 관리·수정·검토가 용이합니다.

현재 Shippy의 주요 Skills:

• Skylight API로 선박 이벤트·데이터 조회
• 배타적 경제수역(EEZ)·해양보호구역(MPA) 경계 조회
• 선박 궤적 데이터 해석
• 대화 응답에서 Skylight 지도 딥링크 생성

Config(설정): 모델 교체는 코드 수정이 아닌 설정 변경

Soul과 Skills는 Docker 이미지로 빌드됩니다. 어떤 모델을 사용할지(현재는 Claude Opus 4.6), 어떤 에이전트 프레임워크를 쓸지는 모두 Config로 관리합니다. 모델을 교체해도 에이전트 로직은 변경되지 않습니다.

비결정론적 에이전트에 결정론적 도구를 붙이다

Shippy 팀이 겪은 가장 큰 문제 중 하나는 에이전트가 Skylight API를 직접 호출할 때 발생하는 버그였습니다.

• 페이지네이션(Pagination, 데이터 분할 로드) 오류로 결과가 조용히 누락
• 좌표 인코딩 오류
• 필터 타입 오해로 잘못된 데이터 반환

해결책은 목적별 CLI(Command Line Interface, 명령줄 인터페이스)를 만드는 것이었습니다. 에이전트는 skylight events search 같은 단순한 명령 하나만 실행하고, 인증·페이지네이션·구조화된 출력은 CLI가 처리합니다.

또한 CLI 출력은 파이프(Pipe)가 아닌 로컬 JSON 파일로 저장됩니다. 대용량 결과가 버퍼 한계를 초과하거나 jq 같은 후속 도구를 망가뜨리는 문제를 원천 차단하는 방식입니다.

핵심 원칙: 에이전트(비결정론적)가 건드리는 외부 도구(결정론적)를 계층적으로 설계하면, 각 계층을 독립적으로 테스트할 수 있습니다.

모델 라우팅: 분류 문제가 아닌 최적화 문제

IBM 리서치는 동일한 CodeAct 에이전트로 417개 작업을 수행하며 Claude Sonnet 4.6과 GPT-4.1을 비교했습니다.

토큰 단가만 보면 GPT-4.1이 저렴해야 했지만 실제로는 Sonnet이 절반 가격이었습니다. 이유는 **캐싱(Caching)**이었습니다. 에이전트 워크로드는 여러 단계에 걸쳐 동일한 컨텍스트를 재사용합니다. Sonnet의 낮은 캐시 읽기 단가가 추론 단계 수의 불리함을 상쇄했습니다.

라우팅의 세 가지 함정

1. 비용 = 모델 단가가 아니다
캐시 히트율, 서빙 인프라 상태, 워크로드 패턴이 실제 비용을 결정합니다.

2. 복잡도 = 프롬프트 난이도가 아니다
"이 계약서 요약해줘"는 쉬워 보이지만 실제로는 검색·컴플라이언스 체크·다단계 리파인먼트가 필요할 수 있습니다. 라우팅 시점에 작업의 실제 난이도를 파악하기 어렵습니다.

3. 지연 = 모델 크기가 아니다
하드웨어 상태, 캐시 웜업 여부, 엔드포인트 부하가 응답 시간에 더 큰 영향을 미칩니다.

IBM의 결론은 명확합니다: 라우팅은 '어떤 모델이 이 작업에 최선인가'를 묻는 분류 문제가 아니라, 비용·품질·지연을 동시에 최적화하는 시스템 최적화 문제입니다. 최적화 기반 라우터는 난이도 기반 라우터 대비 동일 정확도에서 비용을 21% 절감했습니다.

에이전트 평가: 모델이 아닌 전체 시스템을 테스트하라

Shippy 팀은 기존 벤치마크가 실제 워크플로우에서의 에이전트 동작을 측정하지 못한다고 판단해 자체 평가 시스템을 구축했습니다.

• 도메인 전문가가 시나리오와 채점 기준을 작성
• 각 작업에 가중치 부여 (예: 어업 이벤트 쿼리 → 데이터 정확도 최우선)
• LLM 심사관이 0~1 점수와 이유를 함께 제시
• 실제 라이브 데이터 환경에서 특정 버전 빌드를 테스트

최근 실행에서 발견된 개선점:

• 순찰 계획 작업에서 에이전트가 전술적 권고까지 넘어서는 경우
• 경계 단순화로 인한 이벤트 누락
• 에이전트가 존재하지 않는 CLI 명령을 생성한 사례

각 실패는 다음 Skills 개선으로 직접 연결됩니다.

학생·개발자를 위한 실천 가이드

1. Soul·Skills·Config 구조 채택: 사이드 프로젝트 AI 에이전트를 만들 때도 이 세 레이어를 명확히 분리하세요. 모델 교체와 능력 추가가 훨씬 쉬워집니다.

2. 도구를 결정론적으로 설계: LLM이 API를 직접 호출하게 두지 말고, 목적별 래퍼 함수나 CLI를 만들어 에이전트에게 단순한 인터페이스만 노출하세요.

3. 모델 비용 직접 측정: 토큰 단가만 보지 말고 실제 워크로드로 총 비용을 측정하세요. 캐싱 패턴에 따라 결과가 뒤집힐 수 있습니다.

4. 자체 평가 파이프라인 구축: 사용하려는 도메인에 특화된 테스트 케이스를 만들고, 모델/프롬프트 변경 시마다 실행하세요.

GitHub에서 OpenClaw(에이전트 프레임워크), Harbor(평가 프레임워크) 오픈소스를 직접 살펴보면 실제 구현 방식을 확인할 수 있습니다.