AI 에이전트가 프로덕션 API를 사용하기 전에 신뢰성 계층(Reliability Layer)이 필요한 이유

AI 에이전트 데모는 사랑받기 쉽습니다. 모델은 목표를 받고, 도구를 선택하며, API를 호출하고, 유용한 결과를 반환합니다. 이 전체 루프는 화이트보드에 담을 수 있습니다.

하지만 프로덕션 시스템은 훨씬 관대하지 않습니다. 같은 에이전트가 이제 만료된 자격 증명(expired credentials), 중복 요청(duplicate requests), 속도 제한(rate limits), 부분적 실패(partial failures), 변경되는 스키마(changing schemas), 느린 의존성(slow dependencies), 모호한 사용자 의도(ambiguous user intent), 그리고 되돌릴 수 없는 행동들을 처리해야 합니다. 이 지점에서 모델은 더 이상 전체 시스템이 아닙니다. 그것은 신뢰성 문제 안에 있는 하나의 의사 결정 구성 요소일 뿐입니다.

BrewApps에서 AI 기반 제품과 소프트웨어 시스템을 구축하면서, 저는 특히 유용한 디자인 원칙 하나를 발견했습니다. 바로 모델이 프로덕션 API를 직접 호출하도록 두지 않는 것입니다. 모든 중요한 도구와 모델 사이에 신뢰성 계층을 배치해야 합니다.

신뢰성 계층(Reliability Layer)이란 무엇인가요?

신뢰성 계층은 에이전트로부터 제안된 도구 호출을 받아 유효성을 검사하고, 정책을 적용하며, 안전하게 실행하고, 발생한 내용을 기록하는 결정론적 서비스입니다. 모델은 행동을 제안할 수 있지만, 이 계층이 그 행동이 실제 시스템에 도달할지 여부와 방법을 결정합니다.

흐름은 다음과 같습니다:

• 모델이 구조화된 액션 요청(structured action request)을 생성합니다.
• 신뢰성 계층이 엄격한 스키마를 기준으로 요청의 유효성을 검사합니다.
• 정책 검사(Policy checks)가 해당 행동이 허용되는지, 승인이 필요한지, 아니면 거부되어야 하는지를 결정합니다.
• 실행기(executor)는 Idempotency, 타임아웃(timeouts), 재시도(retries), 속도 제한 처리를 추가합니다.
• 결과는 모델에 반환되기 전에 정규화됩니다(normalized).
• 전체 시도는 감사 추적(audit trail)에 기록됩니다.

이 경계는 확률론적 추론(probabilistic reasoning)에 결정론적 운영 환경을 제공합니다.

1. 모든 도구 호출을 신뢰할 수 없는 제안으로 취급하기

모델은 컨텍스트에서 행동을 선택하는 데 능숙하지만, 여전히 누락된 필드, 유효하지 않은 식별자(invalid identifiers), 지원되지 않는 값, 또는 기술적으로 스키마와 일치하지만 비즈니스 규칙을 위반하는 요청을 생성할 수 있습니다.

저는 좁고 버전이 지정된 도구 계약(narrow, versioned tool contracts)을 선호합니다. send_email이라는 이름의 도구는...

너무 광범위합니다. 더 안전한 계약은 초안 작성(drafting)과 전송(delivery)을 분리하고 목적지를 명시적으로 만듭니다. 예를 들어, create_email_draft는 위험도가 낮을 수 있는 반면, send_email_draft는 확인된 초안 ID와 승인 토큰을 필요로 합니다.

검증은 두 번 이루어져야 합니다. 첫째, 형태를 검증합니다: 타입(types), 필수 필드(required fields), 허용 값(permitted values), 길이 제한(length limits). 둘째, 의미를 검증합니다: 이 사용자가 해당 레코드의 소유자인지, 상태 전환이 합법적인지, 목적지가 범위 내에 있는지. 모델은 요청을 다르게 표현함으로써 이러한 확인 절차를 우회할 수 없어야 합니다.

2. 재시도(Retries) 추가 전에 비멱등성(Idempotency) 설계하기

재시도는 필수적이지만, 멱등성이 없는 재시도는 중복 결제, 중복 티켓, 반복 이메일 또는 여러 데이터베이스 레코드를 생성할 수 있습니다.

모든 쓰기 작업(write operation)은 모델 외부에서 생성된 멱등성 키(idempotency key)를 받아야 합니다. 저는 보통 워크플로우 인스턴스, 액션 유형, 논리적 단계로부터 이를 파생시킵니다. 신뢰성 계층(reliability layer)은 첫 번째 결과를 저장하고 동일한 키가 다시 나타날 때 이를 반환합니다.

이것은 에이전트들이 종종 시간 초과(timeout) 후에 확실성을 잃기 때문에 중요합니다. API 호출에 8초가 걸리고 연결이 7초에 끊어지면, 에이전트는 해당 액션이 실패했는지 아니면 응답만 손실되었는지 알 수 없습니다. 무작정 재시도하는 것은 위험합니다. 멱등성 키를 사용하여 이전 시도를 조회하는 것이 안전합니다.

3. 읽기(Read), 초안(Draft), 커밋(Commit) 액션 분리하기

모든 도구가 동일한 위험을 지니는 것은 아닙니다. 제품 카탈로그를 읽는 것과 구독을 변경하는 것은 다릅니다. 비공개 초안을 생성하는 것은 이를 게시하는 것과 다릅니다.

실용적인 분류는 다음과 같습니다:

읽기(Read): 외부 상태를 변경하지 않고 정보를 검색합니다.초안(Draft): 검토를 위해 되돌릴 수 있는 객체를 생성합니다.커밋(Commit): 외부적이거나 되돌리기 어려운 영향을 야기합니다.

이러한 분류는 승인(approvals), 로깅(logging), 재시도 동작(retry behavior)을 제어해야 합니다. 읽기 작업(Read operations)은 종종 자동으로 실행될 수 있습니다. 초안(Draft) 작업은 보통 눈에 보이는 검토가 필요합니다. 커밋(Commit) 작업은 정확한 페이로드와 목적지에 연결된 새로운 권한 부여를 요구해야 합니다.

핵심은 시스템 프롬프트뿐만 아니라 코드 레벨에서 이러한 구분을 강제하는 것입니다.

4. 모든 동작에 시간 예산 할당하기

에이전트는 의존성(dependency)이 단순히 느릴 때 정지된 것처럼 보일 수 있습니다. 명시적인 예산(budgets) 없이는 하나의 실패한 서비스가 전체 워크플로우 창을 소모할 수 있습니다.

저는 각 도구 호출(tool call)에 마감 시한을, 그리고 각 워크플로우에는 더 큰 종단 간(end-to-end) 예산을 할당합니다. 실행기(executor)는 재시도가 유용할 충분한 시간이 남아 있을 때만 재시도할 수 있습니다. 느린 작업은 작업 큐(job queue)로 이동하여 작업 ID를 반환하고, 에이전트는 열려 있는 요청을 유지하는 대신 나중에 상태를 확인할 수 있게 합니다.

타임아웃(Timeouts) 역시 분류되어야 합니다. 연결 타임아웃은 재시도가 가능할 수 있습니다. 유효성 검사 실패는 그렇지 않습니다. 속도 제한(rate limit)은 제공업체의 재시도 지침을 존중해야 합니다. 권한 오류는 워크플로우를 중지하고 개입을 요청해야 합니다.

이러한 구분들은 에이전트가 하나의 오류를 동일한 호출의 폭풍으로 바꾸는 것을 방지합니다.

5. 모델을 위해 오류 정규화하기

원시 API 오류(Raw API errors)는 추론 시스템이 아닌 개발자를 위해 작성되었습니다. 이들은 구조가 다양하고, 관련 없는 구현 세부 정보가 노출되며, 때로는 사용자 데이터를 포함합니다.

신뢰성 계층은 실패를 INVALID_INPUT, NOT_AUTHORIZED, RATE_LIMITED, DEPENDENCY_TIMEOUT, 그리고 CONFLICT와 같은 작은 오류 어휘(error vocabulary)로 번역해야 합니다. 각 응답은 해당 작업이 재시도하기에 안전한지, 그리고 다음에 어떤 정보가 필요한지를 알려야 합니다.

정규화된 오류는 모델에게 다음과 같이 말할 수 있습니다: 요청이 실행되지 않았고, 재시도가 도움이 되지 않을 것이며, 사용자는 두 개의 유효한 계정 ID 중 하나를 선택해야 한다. 이는 스택 트레이스(stack trace)보다 훨씬 더 실행 가능한 정보입니다.

6. 승인을 구체적이고 단기적으로 만들기

6. 승인을 구체적이고 단기적으로 만들기

“이메일 전송 가능”과 같은 일반적인 승인은 너무 광범위합니다. 승인은 사용자가 검토한 정확한 동작, 목적지 및 콘텐츠로 범위가 지정되어야 합니다. 또한 빠르게 만료되고 페이로드(payload)가 변경되면 사용할 수 없어야 합니다.

더 높은 위험을 가진 워크플로우의 경우, 저는 2단계 패턴을 사용합니다. 에이전트가 표준 미리보기(canonical preview)를 준비하고, 시스템은 이 미리보기의 해시(hash)에 바인딩된 승인 토큰을 발급합니다. 커밋 엔드포인트는 최종 페이로드(payload)가 여전히 일치하는 경우에만 해당 토큰을 수락합니다.

이러한 설계는 사용자가 승인한 내용과 시스템이 실제로 전송하는 내용 사이에 우발적인 이탈(drift)로부터 사용자들을 보호합니다.

7. “왜?”에 답하는 감사 추적(Audit Trail) 구축하기

전통적인 로그는 API 호출이 발생했다는 사실만 보여줄 뿐, 에이전트가 왜 그것을 선택했는지 보여주지 못할 때가 많습니다. 유용한 디버깅을 위해서는 워크플로우 ID, 도구 이름, 정제된 인자(sanitized arguments), 정책 결정(policy decision), 승인 참조(approval reference), 재시도 방지 키(idempotency key), 타이밍, 제공업체 응답(provider response), 그리고 최종 정규화 결과(final normalized result)를 기록해야 합니다.

숨겨진 추론이나 불필요한 개인 데이터를 저장하는 것은 피해야 합니다. 목표는 감시가 아니라 운영상의 추적 가능성입니다. “사용자가 구독 A의 취소를 요청했고, 정책상 확인이 필요했으며, 확인 토큰이 검증됨”과 같은 간결한 결정 요약만으로도 충분한 경우가 많습니다.

이 기록은 사용자가 예상치 못한 동작을 보고하거나 제공업체가 문서와 다르게 작동할 때 매우 귀중해집니다.

8. 성공적인 경로(Happy Path)뿐 아니라 실패 시퀀스 테스트하기

개별 도구에 대한 단위 테스트(Unit tests)는 필요하지만, 에이전트의 실패는 보통 시퀀스에서 발생합니다. 첫 번째 호출은 성공하고, 응답은 손실되며, 재시도(retry)는 속도 제한을 받고, 자격 증명(credentials)이 새로 고쳐지고, 최종 상태는 모호해집니다.

저는 장애 주입(fault injection)을 통해 워크플로우를 테스트합니다. 여기에는 지연된 응답, 잘못된 페이로드, 중복 요청, 오래된 상태(stale state), 만료된 토큰, 제공업체 서비스 중단(provider outages), 그리고 상충되는 업데이트가 포함됩니다. 또한 기록된 추적을 새로운 프롬프트와 모델 버전에 대해 재실행하여 도구 선택 동작에 변화가 생기는지 확인합니다.

가장 가치 있는 테스트는 종종 간단합니다. 시스템이 중대한 동작이 최대 한 번만 발생했음을 증명할 수 있는지 여부입니다.

프로덕션을 위한 실질적인 최소 조건

에이전트를 실제 쓰기(write) API에 연결하기 전에, 저는 적어도 다음과 같은 통제 장치가 필요합니다:

• 모든 도구에 대한 엄격하고 버전 관리되는 스키마(schema).
• 서버 측 권한 부여 및 비즈니스 규칙 검증.
• 모든 쓰기에 대한멱등성(Idempotency).
• 명시적인 시간 초과(timeout) 및 제한된 재시도(retry).
• 읽기, 초안, 커밋 위험 수준.
• 중대한 변경에 대한 동작별 승인.
• 정규화되고 재시도 인식 오류 응답.
• 상관관계 ID가 포함된 정리된 감사 로그(audit logs).
• 비상 정지 스위치(Kill switches) 및 도구별 속도 제한(rate limits).
• 출시 전 실패 시퀀스 테스트.

이러한 통제 장치 중 어느 것도 데모를 더 인상적으로 만들지는 못합니다. 하지만 이 모든 것이 합쳐져 에이전트가 사용할 만큼 신뢰할 수 있게 만듭니다.

모델은 제안하고; 시스템은 보장해야 한다

많은 초기 에이전트 아키텍처의 핵심적인 실수는 모델에게 소프트웨어 인프라에 속하는 책임을 지우는 것입니다. 프롬프트는 신중함을 장려할 수는 있지만, 멱등성(idempotency), 권한 부여(authorization), 트랜잭션 경계(transaction boundaries), 또는 감사 가능성(auditability)을 보장할 수는 없습니다.

프로덕션 에이전트는 책임이 명확하게 분리될 때 가장 잘 작동합니다. 모델은 의도를 해석하고, 계획하며, 동작을 제안합니다. 신뢰성 계층(reliability layer)이 불변 조건(invariants)을 강제합니다. API가 진실의 원천(source of truth)으로 남아 있습니다. 인간은 판단과 결과가 만나는 순간에 승인합니다.

그러한 분리는 에이전트의 유용성을 떨어뜨리지 않습니다. 오히려 우리가 이 에이전트를 유용한 작업에 신뢰할 수 있게 만드는 것입니다.