10장. 도구 호출은 말이 아니라 거래다

get_claim은 정보를 읽는다. execute_refund는 돈의 상태를 바꾼다. 둘을 같은 권한과 재시도 정책으로 다루면 위험하다. 도구 카탈로그에 다음 메타데이터를 둔다.

항목	예시
영향 등급	read, prepare, write, irreversible
승인 요구	없음, 금액 조건, 항상 사람 승인
멱등성 키	claim ID + release ID
타임아웃	2초
재시도	읽기 2회, 쓰기 자동 재시도 금지
감사 속성	도구 버전, 승인자, 결과 코드

ClaimOps는 prepare_refund만 실행한다. 실제 지급 시스템과 연결하려면 준비와 확정을 두 단계로 분리한다. 준비 단계는 금액·계좌·중복 여부를 검증하고 실행 계획을 만든다. 확정 단계는 사람 승인 토큰과 멱등성 키를 확인한 뒤 한 번만 수행한다.

도구 인수에는 고객 정보와 내부 식별자가 들어갈 수 있다. 관측 시스템에는 toolName, mode, 금액 구간, 결과 코드처럼 조사에 필요한 최소 속성만 남긴다. 원문은 업무 시스템의 접근 통제 아래 두고 트레이스에는 안전한 참조만 둔다.

쓰기 도구가 타임아웃되면 “실행되지 않았다”고 단정할 수 없다. 서버는 처리했지만 응답만 사라졌을 수 있다. 같은 환불을 다시 호출하기 전에 멱등성 키로 상태를 조회해야 한다. 에이전트에게 재시도를 맡기지 말고 도구 어댑터가 명시적 상태 기계를 구현한다.


PREPARED → APPROVED → EXECUTING → SUCCEEDED
                         ├→ UNKNOWN → RECONCILED
                         └→ FAILED

UNKNOWN을 바로 FAILED로 바꾸면 중복 실행이 생긴다. 조정 작업이 원 시스템에서 실제 결과를 조회해야 한다.

“고객 문제를 해결하기 위해 필요하면 환불하세요”는 도구 설명이 아니다. 언제 호출할 수 있는지, 최대 금액, 필요한 승인, 중복 방지와 실패 의미가 없다. 도구 설명은 모델에게 친절한 문장인 동시에 실행 계약이어야 한다.

AI 에이전트가 사고 치기 전에: 10장. 도구 호출은 말이 아니라 거래다