Token Lab검색

신뢰할 수 있는 Agent 작업: 타임아웃·재시도·복구

전자상거래 환불을 승인된 의도부터 대사된 결과까지 추적합니다. 영속 상태, 멱등성, 재시도 예산을 설명하고 응답 유실과 재시작을 로컬 코드로 검증합니다.

출처 및 버전 정보
이 글의 목차

1. 기다림을 포기해도 환불은 성공했을 수 있다

고객이 주문 7의 25달러 환불을 요청합니다. 모델이 작업을 제안하고 정책 서비스가 승인하며 결제 제공자가 수락합니다. 그러나 Agent가 성공을 저장하기 전에 응답이 사라집니다. 단순한 구현은 실패라고 보고 다른 환불을 만듭니다. 두 번의 추론이 모두 타당해도 실행 경계에서 업무 오류가 생깁니다. 목표는 대화상 성공이 아니라 불확실한 전달 과정에서도 하나의 승인된 의도를 유지하는 것입니다.

부수 효과는 외부 상태를 변경하고, 확인 응답은 호출자에게 증거를 전달합니다. 응답 부재가 효과 부재를 증명하지 않습니다. 멱등성은 같은 식별된 의도의 반복 제출이 추가 효과를 만들지 않는 계약입니다. 영속성은 명시한 장애 모델에서 상태가 살아남는 성질입니다. 영속 로그도 중복 결제를 정확히 기록할 수 있습니다. 선수 지식은 DB 트랜잭션, 요청·응답, 접근 제어입니다. 로컬 트랜잭션이 원격 HTTP 호출까지 자동으로 포함하지는 않습니다.

이 글은 티켓 생성, 재고 예약, 승인된 환불 Agent에 적용됩니다. 읽기 검색은 최신성과 예산이 필요하지만 보통 결제식 효과 대사는 필요 없습니다. 되돌릴 수 없고 멱등성과 상태 조회도 없는 작업은 사람의 조사나 통합 재설계가 필요합니다. 아키텍처는 독자적인 참고 설계이며 코드는 두 로컬 DB만 사용하고 실제 결제·모델 API를 호출하지 않습니다.

2. 계획 권한과 실행 권한을 분리한다

계획기는 도구 이름과 인수를 제안합니다. 결정적인 게이트가 스키마, 테넌트, 주문 소유권, 금액, 승인 만료를 검사합니다. 승인 전에 금액을 정수 최소 단위로 정규화합니다. 2500센트는 25달러이며 실제 통합에는 통화도 필요합니다. 승인을 작업 ID, 정규화 인수 해시, 정책 버전에 묶습니다. 금액 변경은 새 승인 대상이고 동일 의도 재시도는 원래 ID를 유지합니다.

실행기는 보내기 전에 의도를 영속 저장합니다. 효과의 권위 있는 기록은 제공자가 소유합니다. 대사기는 제공자를 조회하고 검증된 증거로만 로컬 상태를 진행시킵니다. UI는 대기, 확인, 불명, 거절을 구분합니다. 도구 출력이 다음 구매 권한을 부여하지 않습니다. 새 변경 요청은 유효 권한을 다시 검사하며 이전 작업 상태를 읽는 권한은 별도입니다.

로컬 DB와 원격 제공자의 트랜잭션은 독립적이고 사이에 네트워크가 있습니다. Outbox는 로컬 의도와 발송 레코드를 함께 저장하고 적어도 한 번 전달할 수 있지만 원격 효과를 같은 원자적 커밋에 넣지 못합니다. 모든 변경 요청은 실행 게이트를 통과합니다. 대사는 상태를 읽고 증거를 남길 뿐 몰래 보상 작업을 발행하지 않습니다.

독자 참고 설계: 실선은 요청·결과, 점선은 기록·상태 조회이며 두 트랜잭션은 독립적입니다.
독자 참고 설계: 실선은 요청·결과, 점선은 기록·상태 조회이며 두 트랜잭션은 독립적입니다. 원본 크기로 보기

3. 불확실성은 예외 문자열이 아니라 상태다

발송 전에 PREPARED를 저장합니다. SUBMITTED는 요청이 나갔을 가능성이지 수락 증명이 아닙니다. 의도와 일치하는 확인으로 SUCCEEDED에 도달합니다. 응답 유실이나 발송 뒤 장애는 UNKNOWN 또는 대사할 SUBMITTED로 남깁니다. REJECTED에는 확정적 거절이 필요하며 타임아웃은 그런 증거가 아닙니다. 미발견 응답도 가시성 지연과 진행 중인 요청을 고려해야 합니다. 같은 키 재전송이 안전하려면 명시적 멱등 계약이 필요합니다.

세 장애 창이 있습니다. 로컬 의도 커밋 전에는 발송 금지입니다. 커밋 후 발송 전이라면 같은 작업을 재개합니다. 제공자 커밋 후 로컬 성공 커밋 전이라면 조회하거나 같은 중복 제거 작업을 반복합니다. 매번 새 UUID를 만들면 마지막 창의 정체성이 끊깁니다. 영속 업무 ID에서 키를 만들거나 효과보다 앞선 독립적인 영속 단계에서 생성 키를 저장합니다.

취소는 가능한 미래 작업을 멈출 뿐 완료된 효과를 되돌리지 않습니다. 취소와 환불 커밋이 경합하면 대사 결과를 표시하고 구제 조치를 새로운 승인 작업으로 취급합니다. 보상은 원자적 롤백이 아닙니다. LangGraph의 현재 문서도 노드 재실행과 외부 효과를 분리하고 확인 부재를 불명으로 봅니다. 구현 버전을 고정해야 하며 본 예제는 프레임워크 의존성이 없습니다.

4. 멱등성의 소유자·범위·보존 기간

제공자는 테넌트와 작업 ID를 고유 키로 사용하고 의도 해시, 결과, 보존 정책을 저장할 수 있습니다. 중복 제거와 효과는 해당 시스템 안에서 원자적으로 처리되어야 합니다. 클라이언트가 조회한 뒤 보호 없이 쓰면 두 worker가 동시에 부재를 확인하고 둘 다 실행할 수 있습니다. 예제는 고유 키와 트랜잭션을 쓰며 실제 제공자는 동등한 계약을 명시해야 합니다.

원시 prompt 해시나 모델이 만든 tool-call ID만을 업무 정체성으로 쓰지 마세요. 공백만 바뀌어도 해시는 달라지고 의도적인 동일 금액 두 환불은 구별해야 합니다. 검증된 인수를 정규화하되 ID와 해시를 분리합니다. 예제는 주문과 정수 센트만 사용하지만 운영에서는 통화, 계정, 작업 유형, 스키마 버전도 넣습니다. 같은 키의 다른 해시는 충돌이지 이력을 덮어쓸 이유가 아닙니다.

보존 기간은 보장의 한계입니다. Stripe API v1은 응답 재사용, 인수 불일치 검사, 최소 24시간 이후 키 삭제를 설명하며 API v2의 실패 처리는 다릅니다. 일반적인 보장으로 확대하면 안 됩니다. 복구 시간이 중복 제거 기간을 넘으면 자동 변경을 중지하고 영속 업무 ID로 대사해야 합니다. 필요하면 간단한 이력 표식이나 업무 장부를 보존하며 키에 민감한 개인정보를 넣지 않습니다.

5. 마감 시각과 재시도 예산으로 과부하를 막는다

Timeout은 한 번의 대기를, deadline은 전체 작업을 제한합니다. 잔여 예산 R은 D에서 현재 t를 뺀 시간입니다. 최종 기록과 응답을 위해 F초를 남깁니다. 대기 b와 시도 제한 T에 대해 b+T+F가 R 이하여야 시작할 수 있습니다. 독자 예제에서 30초 중 18초 경과, F=2, T=4입니다. 8초 대기는 총 14초라 남은 12초에 못 들어가고, 2초 대기는 총 8초라 가능합니다. 프로세스 안에서는 단조 시계, 서비스 사이에서는 제한된 잔여 시간을 사용합니다.

분류 후 재시도합니다. 잘못된 인수, 권한 거절, 확정적 업무 거절은 일시적 통신 장애가 아닙니다. 일시 오류에는 횟수 제한, 지터를 넣은 지수 백오프, 공유 예산, 의존 서비스 동시성 제한을 사용합니다. 아래 full jitter 식에서 i는 0부터 시작하고 base와 cap은 초이며 0과 해당 상한 사이의 균등 지연을 선택합니다. 지터는 시각을 분산할 뿐 허용 횟수를 줄이지 않습니다.

세 계층이 각 세 번 시도하면 최악에 말단 호출 27번이 됩니다. 재시도 소유자를 하나로 정하거나 전체 트리를 예산화합니다. 독립 실패 확률 0.2, 최대 세 번이면 기대 시도는 1+0.2+0.04=1.24입니다. 상관된 과부하는 독립 가정을 깨뜨립니다. 이 추정이 실패해도 예산은 증폭을 제한해야 합니다. gRPC의 마감 전파와 별도로 애플리케이션이 만든 작업도 취소에 협력해야 합니다.

식의 b_0는 기본 지연, b_max는 상한, i는 0부터 시작하는 재시도 번호, A는 시도 수, m은 최대 횟수, p는 독립적인 각 시도의 실패 확률입니다. A와 m은 개수이고 p는 무차원이며 기대값은 최초 시도를 포함합니다.

6. 영속 실행과 관측 가능성은 다른 역할이다

체크포인트는 제어 상태, 도구 장부는 식별된 효과, 감사는 승인자와 근거, trace는 시도·큐·지연을 기록합니다. 서로 대체할 수 없습니다. LangGraph는 스레드 체크포인트와 스레드 간 store를 구분합니다. 메모리 예제는 장애 영속성을 보장하지 않습니다. 재생 경계에서 모델 출력과 결정을 저장해 확률적 계획기가 같은 승인 도중 다른 작업을 발명하지 않도록 합니다.

작업 ID, 테넌트, 의도 해시, 승인 버전, 시도 ID, deadline, 원격 참조, 전이, 비식별화 오류 유형을 기록합니다. 한 업무 작업에 여러 네트워크 시도가 있을 수 있습니다. UNKNOWN 수와 수명, 승인 의도당 효과 수, 충돌률, 재시도 증폭, 대사 완료 시간을 관찰합니다. 나중에 환불이 확인되면 앞선 통신 타임아웃을 환불 실패로 세지 않습니다. 로그와 보존 정책에도 개인정보 보호가 필요합니다.

여러 실행기는 lease로 소유권을 관리하고 대상이 지원하면 fencing 세대를 사용합니다. Lease 만료가 이전 worker를 죽이지는 않습니다. Fencing이나 제공자 멱등성이 없으면 이전 worker가 여전히 행동할 수 있습니다. 로컬 mutex는 분산 배제가 아닙니다. 본 코드는 단일 실행기와 트랜잭션 제공자 모델이며 분산 lease, 지역 간 전환, 실제 권한 서비스를 구현하지 않습니다.

7. 계약을 지키는 최소 복구 방법을 고른다

읽기는 마감 안에서 반복하고 낡은 데이터를 표시합니다. 상태 조회가 있는 멱등 변경은 먼저 대사하고 유효 승인 아래 같은 키로 반복합니다. 조회 없이 중복 제거만 있으면 재전송으로 결과를 회수할 수 있는지는 보존과 오류 계약에 달렸습니다. 비멱등이고 신뢰할 상태도 없으면 멈추고 사람이 조사합니다. 재시도로 없는 계약을 만들 수 없습니다.

긴 단계, 타이머, 사람 승인이 많으면 workflow engine이 유용하지만 단일 로컬 순수 계산에는 과합니다. Outbox는 로컬 발송, saga는 업무 보상을 다룹니다. 어떤 것도 임의 외부 API를 exactly-once로 만들지 않습니다. 환불 사례에서는 이메일로 성공을 추론하거나 즉시 역지급하기보다 읽기 전용 대사기가 안전합니다.

남은 문제는 키 만료, 대사 중 제공자 장애, 상태 스키마 변경, 늦은 콜백, 이벤트 역순, 여러 지역의 소유권입니다. 의도 스키마를 버전 관리하고 종결 증거를 남기며 담당자가 명확한 수동 큐를 정의하세요. 운영 합격 기준은 각 불확실성 창의 안전한 행동이며 무장애 약속이 아닙니다. 아래 검증은 제한된 일부이며 결제 통합 인증이 아닙니다.

메커니즘보호 대상보장하지 않는 것
체크포인트워크플로 상태외부 효과 exactly-once
Outbox로컬 의도·발송 기록제공자 간 원자적 커밋
멱등 키동일 의도 중복 제거무기한 보존·권한
대사원격 결과 증거원격 API 가용성

실습과 검증

Python 3.11+ 표준 라이브러리만 필요합니다. python3 agent-action-recovery.py 를 실행하세요. 키·네트워크·실제 효과·난수가 없습니다. 임시 SQLite 두 파일이 Agent와 제공자를 분리하며 중복 제거와 환불 모델만 제공자 트랜잭션에서 함께 커밋합니다. 예상값은 PASS와 effects=3; duplicate-effects=0입니다. shop의 다른 두 작업과 다른 테넌트의 한 작업입니다. 응답 유실, 재개, 인수 충돌, 쓰기 권한 만료, 원격 커밋 뒤 장애, 중복 전달을 assert합니다. 실제 IAM, 강제 종료, 네트워크, 환불 한도는 검증하지 않습니다. 같은 장애 위치에서 새 ID로 재제출하는 기준선을 만들어 추가 효과를 확인한 후 안정 ID로 복원하세요. 입력과 장애 위치를 동일하게 유지하고 운영 전에 지연 가시성, 제공자 오류, 예산 소진, 동시 실행을 추가하세요.

agent-action-recovery.py
python3 agent-action-recovery.py
Python 3.11+
"""Python 3.11+, standard library. Local teaching model; never contacts a provider."""
import hashlib
import json
import sqlite3
import tempfile
from pathlib import Path


def connect(path):
    db = sqlite3.connect(path)
    db.execute('PRAGMA synchronous=FULL')
    return db


def fingerprint(order, cents):
    if type(cents) is not int or cents <= 0:
        raise ValueError('positive integer cents required')
    return hashlib.sha256(json.dumps([order, cents], separators=(',', ':')).encode()).hexdigest()


class Provider:
    """One transactional SQLite database models the external system's contract."""
    def __init__(self, path):
        self.db = connect(path)
        self.db.executescript('''
        CREATE TABLE IF NOT EXISTS refunds (
          tenant TEXT, op TEXT, digest TEXT, cents INTEGER,
          PRIMARY KEY (tenant, op));
        ''')

    def submit(self, tenant, op, digest, cents):
        # Atomic deduplication + effect, not a client-side check-then-act.
        with self.db:
            self.db.execute('BEGIN IMMEDIATE')
            old = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
                                  (tenant, op)).fetchone()
            if old and old[0] != digest:
                raise ValueError('provider key conflict')
            if not old:
                self.db.execute('INSERT INTO refunds VALUES (?,?,?,?)',
                                (tenant, op, digest, cents))
        return {'state': 'succeeded', 'digest': digest}

    def status(self, tenant, op):
        row = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
                              (tenant, op)).fetchone()
        return None if row is None else {'state': 'succeeded', 'digest': row[0]}

    def count(self):
        return self.db.execute('SELECT COUNT(*) FROM refunds').fetchone()[0]


class AgentExecutor:
    def __init__(self, path, provider):
        self.db, self.provider = connect(path), provider
        self.db.execute('''CREATE TABLE IF NOT EXISTS operations (
          tenant TEXT, op TEXT, digest TEXT, order_id TEXT, cents INTEGER,
          state TEXT, PRIMARY KEY(tenant,op))''')
        self.db.commit()

    def state(self, tenant, op):
        row = self.db.execute('SELECT state FROM operations WHERE tenant=? AND op=?',
                              (tenant, op)).fetchone()
        return row[0] if row else None

    def mark(self, tenant, op, state):
        with self.db:
            self.db.execute('UPDATE operations SET state=? WHERE tenant=? AND op=?',
                            (state, tenant, op))

    def execute(self, tenant, op, order, cents, *, authorized, lose_ack=False,
                crash_after_provider=False):
        digest = fingerprint(order, cents)
        row = self.db.execute('SELECT digest,state FROM operations WHERE tenant=? AND op=?',
                              (tenant, op)).fetchone()
        if row and row[0] != digest:
            raise ValueError('same operation ID with different intent')
        if row and row[1] == 'succeeded':
            return 'succeeded'
        if not row:
            if not authorized:
                return 'blocked'
            with self.db:
                self.db.execute('INSERT INTO operations VALUES (?,?,?,?,?,?)',
                                (tenant, op, digest, order, cents, 'prepared'))
        # Reconcile first, even if permission to create a new effect has expired.
        # This demo assumes a separate permission to inspect this tenant's status.
        result = self.provider.status(tenant, op)
        if result:
            if result['digest'] != digest:
                raise ValueError('status intent mismatch')
            self.mark(tenant, op, 'succeeded')
            return 'succeeded'
        if not authorized:
            return 'blocked'
        # A missing status alone is NOT proof of no effect. Safe repeat here depends
        # on Provider.submit's durable atomic idempotency contract, with no expiry.
        self.mark(tenant, op, 'submitted')
        self.provider.submit(tenant, op, digest, cents)
        if crash_after_provider:
            raise RuntimeError('injected crash after provider commit')
        if lose_ack:
            self.mark(tenant, op, 'unknown')
            return 'unknown'
        self.mark(tenant, op, 'succeeded')
        return 'succeeded'


def run():
    with tempfile.TemporaryDirectory() as folder:
        root = Path(folder)
        provider = Provider(root / 'provider.sqlite')
        client = AgentExecutor(root / 'agent.sqlite', provider)
        assert client.execute('shop', 'refund-1', 'order-7', 2500,
                              authorized=True, lose_ack=True) == 'unknown'
        assert provider.count() == 1
        client.db.close()
        client = AgentExecutor(root / 'agent.sqlite', provider)
        assert client.execute('shop', 'refund-1', 'order-7', 2500,
                              authorized=False) == 'succeeded'
        assert provider.count() == 1
        try:
            client.execute('shop', 'refund-1', 'order-7', 3000, authorized=True)
            raise AssertionError('changed intent accepted')
        except ValueError:
            pass
        assert client.execute('shop', 'refund-2', 'order-8', 500,
                              authorized=False) == 'blocked'
        try:
            client.execute('shop', 'refund-3', 'order-9', 700,
                           authorized=True, crash_after_provider=True)
        except RuntimeError:
            pass
        assert client.state('shop', 'refund-3') == 'submitted'
        client.db.close()
        client = AgentExecutor(root / 'agent.sqlite', provider)
        assert client.execute('shop', 'refund-3', 'order-9', 700,
                              authorized=True) == 'succeeded'
        # Direct duplicate delivery exercises provider-side atomic deduplication.
        d = fingerprint('order-9', 700)
        provider.submit('shop', 'refund-3', d, 700)
        assert provider.count() == 2
        # Distinct tenant namespace: same op is a different operation.
        assert client.execute('shop-2', 'refund-3', 'order-9', 700,
                              authorized=True) == 'succeeded'
        assert provider.count() == 3
        client.db.close()
        provider.db.close()
    print('PASS: lost acknowledgement, restart, conflict, expired permission, crash window, duplicate delivery, tenant namespace')
    print('effects=3; duplicate-effects=0; no network; deterministic; no random seed needed')


if __name__ == '__main__':
    run()

독자 면접 연습·기업 실제 문제가 아님

타임아웃이 환불 실패 증명이 아닌 이유는?

힌트

커밋과 전달을 나누세요.

답과 분석

응답 없이도 효과가 존재합니다. 불명 상태를 저장하고 대사하며 새 의도를 만들지 않습니다.

체크포인트가 exactly-once를 보장하나요?

힌트

두 트랜잭션 경계를 찾으세요.

답과 분석

아닙니다. 외부 효과 뒤 노드가 다시 실행될 수 있으므로 원자적 멱등 계약이나 신뢰할 대사가 필요합니다.

승인 만료는 조회도 막나요?

힌트

읽기와 변경 권한을 구분하세요.

답과 분석

새 변경은 막지만 별도의 유효 조회 권한으로 대사할 수 있습니다. 예제는 그 권한을 가정하며 응답이 승인을 갱신하지 않습니다.

반복이 다시 위험해지는 조건은?

힌트

보존·인수·범위를 보세요.

답과 분석

중복 제거 만료, 키나 의도 변경, 계약 범위 이탈입니다. 대체 키를 만들지 말고 멈춰 대사합니다.

채점: 1—개념 정의, 2—불확실성 식별, 3—실행과 설명, 4—장애 대조, 5—보존·권한·동시성 경계.

예측, 검증, 근거 기록

답을 보기 전에 결과를 예측하세요. 연습 후 차이와 전이 테스트를 기록합니다. 로컬에 저장되며 언어판 간 공유됩니다.

학습 기록 열기 / 내보내기 / 지우기 →

수학 검토 범위는 강의별로 기록합니다. 논문의 실증 재현 인증은 아닙니다. 의심되는 오류를 노트에 남겨 주세요. 검토 범위

참고 자료와 추가 학습

다음: Agent 스케줄링