화면에는 '주문 A에 대해 100 위안 환불'이라고 표시되었고, 사용자가 동의했습니다. 하지만 실제로 실행될 때 도구가 받은 금액은 1,000 위안이었습니다.
시스템에 확인 버튼이 있더라도, 이번 실행은 통과되어서는 안 됩니다.
확인은 특정 도구를 영구적으로 허가하는 것이 아니라, 내용이 명확한 비즈니스 작업을 한 번 승인하는 것입니다.
본문은 Solon AI 도구 호출을 진입점으로 삼아 승인과 실행의 일관성에 대해 논합니다. 환불 프로세스는 가상의 애플리케이션 설계 예시이며, 프레임워크 내장 승인 기능이나 실제 운영 사례가 아닙니다. 본문은 실행 가능한 엔지니어링 코드를 제공하지 않습니다.
English summary — Approval must bind to an operation, not just a tool. Using Solon AI tool calling as the starting point, this article discusses server-side approval records, execution-time authorization, concurrency control, and recovery after ambiguous downstream outcomes. These are application design recommendations, not built-in framework guarantees.
1. 도구 등록과 비즈니스 권한을 분리하여 생각해야 합니다
Solon AI의 @ToolMapping 문서에 따르면, 일반 Java 메서드를 도구 정의로 매핑할 수 있습니다. @Param 또는 @Body를 포함하는 메서드 파라미터로부터 inputSchema를 생성하고, 반환 타입으로부터 outputSchema를 생성합니다.
도구 등록 문서는 또한 두 가지 범위(scope)를 구분합니다:
ChatModel을 구성할 때 defaultToolAdd를 통해 기본 도구를 추가하면, 매번 요청에 첨부됩니다.- 요청 옵션의
toolAdd를 통해 해당 요청에만 도구를 추가합니다.
'도구 추가'가 곧 매번 실행됨을 의미하지 않으며, 현재 사용자가 비즈니스 권한을 획득했음을 의미하지도 않습니다.
도구 인터페이스 문서에 따르면, 실제 함수는 애플리케이션 측에서 실행되고 그 결과를 모델에게 피드백합니다. 따라서 환불, 삭제, 게시 등 부작용(side effect)이 발생하기 전에, 애플리케이션은 여전히 다음을 판단해야 합니다: 현재 신원이 이 리소스에 대해 이번 작업을 수행할 권한이 있는가?
도구가 등록되고, 모델이 호출하려 하고, 사용자가 실행할 권한을 갖는 것은 세 가지 다른 일입니다.
2. 작업을 준비한 후 확인 요청을 해야 합니다
고위험 작업의 경우 '준비(Preparation)'와 '제출(Submission)' 두 단계로 분리할 수 있습니다.
준비 단계에서는 환불 부작용이 발생하지 않으며, 검증과 미리보기에만 사용되고 서버 측에 확인 대기 기록을 생성합니다.
| 기록 내용 | 용도 |
|---|
| 안정적인 비즈니스 작업 식별자, 작업 유형 | 단순히 도구 이름이 아닌 이번 비즈니스 작업을 식별합니다. |
| ... | |
| 이는 애플리케이션 측의 데이터 설계 권장 사항이며, Solon AI의 고정 필드는 아닙니다. | |
확인 인터페이스는 모델이 요약한
제출 단계에서는 다음 사항들을 재확인해야 합니다:
- 현재 실행 주체 및 위임 범위가 해당 작업을 허용하는지 여부;
- 사용자, 테넌트(tenant), 목표 리소스가 일치하는지 여부;
- 승인이 유효하고 취소되지 않았으며, 새로운 작업으로 중복 소비되지 않았는지 여부;
- 실제 제출 내용이 승인된 버전과 일치하는지 여부;
- 리소스의 현재 상태가 필수 선행 조건을 여전히 충족하는지 여부.
하지만 '상태 읽기 → 확인 → 일반 업데이트' 과정에서는 여전히 동시성(concurrency) 윈도우가 존재합니다. 두 요청이 동시에 '아직 실행되지 않음'을 볼 수 있습니다.
로컬의 핵심 상태는 트랜잭션 내 검증 및 업데이트, 버전 조건 업데이트, 고유 제약 조건 또는 적절한 잠금(locking)과 결합하여 확인하고, 작업 결과를 점검해야 합니다. 원격 리소스의 선행 조건은 다운스트림 시스템에서 해당 조건을 쓰기(write), 버전 검증 또는 예약(reservation) 기능을 제공받아야 합니다. 로컬 데이터베이스 트랜잭션만으로는 외부 결제 시스템을 자동으로 보호할 수 없습니다.
승인 소비와 실행 수령 역시 원자적 상태 전환(atomic state transition)으로 제어해야 합니다. '미소비' 여부를 먼저 독립적으로 확인한 다음, 별도로 '소비됨'으로 표시해서는 안 됩니다. 동일 작업의 복구 재시도와 새로운 환불 처리 생성은 명확하게 구분되어야 합니다.
5. 만료(Timeout)가 실패가 아니며, 충돌(Crash)로도 작업이 사라지면 안 된다
외부 결제 인터페이스에서 시간 초과가 반환될 경우, 이미 환불 처리가 접수되었을 수 있습니다. 이 경우 '처리 중/검증 대기' 상태를 기록하고, 조회나 정산(reconciliation)을 통해 결과를 확정해야 하며, 모델이 임의로 '실패' 또는 '성공'으로 채워 넣게 해서는 안 됩니다.
동일 작업의 재시도는 안정적인 비즈니스 작업 식별자 및 다운스트림 시스템의 Idempotency 식별자를 재사용해야 합니다. 동일한 식별자가 다른 금액을 가지고 전송될 경우, 조용히 실행하는 대신 거부되어야 합니다.
또한 다운스트림 시스템의 Idempotency 계약(contract)을 명확히 해야 합니다:
- Idempotency 키는 어느 계정 또는 인터페이스 범위에서 유효한가?
- 동일 키 요청의 매개변수 일치성을 검증하는가?
- 얼마나 보존되는가? 만료 후에도 재시도가 가능한가?
- 동시 동일 키 요청은 어떻게 처리되는가?
- 중복 제거(deduplication)가 실제 자금 부작용을 덮어쓰지 않는가?
'Idempotency 키를 가지고 있다'는 것이 영구적인 중복 방지를 보장하는 것은 아닙니다.
동시에 두 가지 충돌 윈도우를 고려해야 합니다:
- 로컬에서 작업을 수령했지만, 다운스트림 시스템에 요청하기 전에 충돌한 경우. 실행 의도를 영구화하고, 복구 가능한 작업 스캔 메커니즘 또는 트랜잭션 outbox 같은 방안이 필요하며, 작업이 영원히 멈춰서는 안 됩니다.
- 다운스트림 시스템에서 성공했지만, 로컬에 성공 기록을 남기기 전에 충돌한 경우. 복구 시에는 원래 비즈니스 식별자로 조회하고, 필요한 재시도는 반드시 기존 Idempotency 키를 재사용해야 하며, 새 키를 생성하여 다시 보내서는 안 됩니다.
outbox 자체가 메시지가 절대 중복되지 않음을 의미하지 않습니다. 소비자(consumer)와 다운스트림 시스템 모두 적절한 Idempotency 처리가 필요합니다. AWS의 outbox 가이드는 중복 메시지 문제에 대해 명확히 경고하고 있습니다.
이 설계는 중복 실행 위험을 제어하고 불확실한 결과를 복구하는 데 사용되며, 애플리케이션 간, 메시징 시스템 및 외부 서비스 전반의 exactly-once를 선언하지 않습니다. 구체적인 보장은 각 시스템의 트랜잭션과 Idempotency 계약에 의존합니다.
6. returnDirect는 반환 경로만 변경할 뿐, 승인 경계는 바꾸지 않는다
공식 웹사이트에서 제시하는 기본 경로는 다음과 같습니다:
returnDirect=false (기본값)
user -> llm -> tool -> llm -> user
true로 설정하면:
user -> llm -> tool -> user
변경되는 것은 도구 실행 완료 후의 결과를 모델이 다시 가공할지 여부일 뿐이며, 전체 요청이 모델을 우회하거나 승인, 비식별화(masking), 또는 Idempotency 스위치가 우회되는 것을 의미하지 않습니다.
두 경로 모두 출력을 제어하여 필요한 필드만 반환하고, 완전한 결제 응답, 자격 증명(credential) 또는 관련 없는 고객 자료는 노출해서는 안 됩니다. 성공 상태는 검증 가능한 비즈니스 흐름이나 다운스트림 시스템의 상태에서 나와야 하며, 모델이 추측하는 것이어서는 안 됩니다.
상용화 전, 반례로 설계를 도전하라
다음은 구현 대기 중인 테스트 제안이며, 이미 통과한 테스트 결과가 아닙니다. 격리 환경에서 가상의 주문 및 다운스트림 시뮬레이터를 사용하여 실제 결제를 사용하지 마십시오.
| 반례 | 검증해야 할 동작 |
|---|
| 100원 승인 후, 제출을 1,000원으로 변경 | 기존 승인 재사용 거부, 재확인 필요 |
| ... | |
| 필자가 모델이 '작업 성공'이라고 답변하는지만 봐서는 안 됩니다. 영구화 기록과 실제 부작용(side effect)을 확인해야 경계가 성립했는지 판단할 수 있습니다. | |
확인 버튼은 누군가가 동의를 표현했다는 것만 의미할 수 있습니다. 감사 추적(auditable)이 가능한 전체 흐름은 다음 질문에 답해야 합니다: 누가 어떤 권한으로, 어느 버전 내용을 승인했고, 최종적으로 무슨 일이 발생했으며, 결과 증거는 어디에 있는가.
Solon AI는 도구 매핑, 등록 및 애플리케이션 단 실행의 기본 메커니즘을 제공합니다. 이 메커니즘들을 비즈니스에 연결할 때, '승인된 것이 곧 실행된다'를 검증 가능한 제약 조건으로 만드는 것이
⚠️ [IMG:N]
승인된 후, 고위험 도구 작업의 매개변수나 리소스 상태가 변경될 경우 어떻게 처리하시나요? 디자인 선택과 절충점을 공유해 주세요. 실제 주문 정보, 자격 증명 또는 고객 자료는 게시하지 말아 주십시오.