GuidesOneMux

LangGraph 도구 호출: 실행 제한과 실패 복구

무제한 실행 대신 재시도 예산, 사람의 승인, 명시적인 복구 경로를 사용하는 LangGraph 프로덕션 운영 에이전트를 구축하는 방법을 알아봅니다.

AI

요약 · TL;DR

프로덕션 운영 에이전트가 무한정 재시도하거나 부작용을 일으키는 작업을 무작정 반복하게 두어서는 안 됩니다. LangGraph는 실행을 일시 중지하는 그래프와 영속성 모델을 제공하며, 워크플로에는 재시도 예산, 멱등성 규칙, 에스컬레이션 경로, 복구 상태를 정의해야 합니다. HumanInTheLoopMiddleware를 사용하면 위험한 도구 호출을 통제하고, 승인·수정·거부 또는 직접 응답 후 체크포인트에서 실행을 재개할 수 있습니다.

핵심 요점

  • 재시도 여부를 결정하기 전에 일시적 오류와 영구 오류를 구분하세요.
  • 도구별 재시도 예산과 그래프 수준의 단계 제한을 모두 적용해 실행 범위를 제한하세요.
  • 프로덕션 리소스를 생성·삭제·수정하는 도구에는 멱등성 키를 사용하세요.
  • 파괴적이거나 외부에 영향을 미치는 작업은 사람의 승인을 받도록 하세요.
  • 워크플로가 중단되더라도 처음부터 다시 시작하지 않도록 그래프 상태를 저장하세요.
목차 (9)

설계 결정: 자동으로 재시도할까, 의도적으로 복구할까?

프로덕션 워크플로 운영에서 가장 안전한 기본 원칙은 “모든 실패를 재시도한다”가 아닙니다. 다음 원칙을 따르세요.

  1. 일시적일 가능성이 있는 오류만 재시도합니다.
  2. 명시적으로 정한 적은 횟수만큼만 시도합니다.
  3. 재시도 한도에 도달했거나 결과가 불분명한 작업은 복구 상태로 전환합니다.
  4. 비용이 크거나 되돌리기 어려운 부작용을 일으킬 수 있는 작업은 승인받도록 합니다.

LangGraph는 이러한 결과를 하나의 거대한 에이전트 루프 안에 감추지 않고 그래프 상태로 표현할 수 있어 적합합니다. 모델은 도구 호출을 제안할 수 있지만, 호출을 안전하게 실행·재시도·에스컬레이션·건너뛸지 여부는 결정론적 코드가 판단합니다.

아래 예시는 참고용 패턴입니다. 테스트를 거친 애플리케이션이 아니며, 정확한 API는 설치된 LangGraph 및 LangChain 버전에 따라 다를 수 있습니다.

사전 준비

다음 항목이 필요합니다.

  • Python 및 호환되는 LangGraph와 LangChain 패키지.
  • 선택한 통합을 통해 도구 호출을 지원하는 채팅 모델.
  • 명시적인 입력 스키마와 예측 가능한 오류 유형을 갖춘 도구.
  • 체크포인터. 실험에는 InMemorySaver를 사용할 수 있습니다. 프로덕션에서는 AsyncPostgresSaver 또는 MongoDBSaver 같은 영속 체크포인터를 사용하도록 LangGraph 문서에서 권장합니다.
  • 각 워크플로 실행에 사용할 안정적인 thread_id.

모델에 프로덕션 자격 증명에 대한 제한 없는 접근 권한을 부여하지 마세요. 권한 부여, 검증, 멱등성, 재시도 정책은 도구나 미들웨어에서 처리하세요.

실행 범위가 제한된 재시도 가능 도구 정의

첫 번째 안전장치는 작업 자체에 적용해야 합니다. 다음 예시는 분류된 일시적 오류만 재시도하고, 재시도 예산을 소진하면 구조화된 결과를 반환합니다.

from dataclasses import dataclass
from typing import Literal

class TransientOperationError(Exception):
    pass

class PermanentOperationError(Exception):
    pass

@dataclass
class OperationResult:
    status: Literal["succeeded", "needs_recovery", "failed"]
    attempts: int
    message: str


def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
    for attempt in range(1, max_attempts + 1):
        try:
            operation()
            return OperationResult("succeeded", attempt, "Operation completed")
        except PermanentOperationError as exc:
            return OperationResult("failed", attempt, str(exc))
        except TransientOperationError as exc:
            if attempt == max_attempts:
                return OperationResult(
                    "needs_recovery", attempt,
                    f"Retry budget exhausted: {exc}",
                )

    return OperationResult("needs_recovery", max_attempts, "No attempt was made")

실제 운영 환경에서는 재시도 전에 멱등성 키를 추가하세요. 배포 요청 후 타임아웃이 발생했다고 해서 배포가 이루어지지 않았다는 뜻은 아닙니다. 키 없이 재시도하면 중복 작업, 티켓, 결제 또는 변경 요청이 생성될 수 있습니다.

유용한 정책 표는 다음과 같습니다.

실패 유형자동 조치복구 조치
일시적인 네트워크 타임아웃재시도 예산 내에서 재시도작업 ID와 함께 에스컬레이션
요청 제한제공자 지침에 따라 재시도워크플로를 대기열에 넣거나 연기
잘못된 인수재시도하지 않음에이전트에 검증 오류 반환
권한 오류재시도하지 않음권한을 요청하거나 중단
타임아웃 후 결과 불명무작정 반복하지 않음멱등성 키를 사용해 상태 확인

도구 호출과 사람의 승인 추가

LangChain의 create_agent는 내부적으로 LangGraph 실행을 사용합니다. 제공된 LangGraph 문서에서는 선택한 도구 호출을 중단하고 저장된 상태에서 재개할 수 있는 HumanInTheLoopMiddleware를 설명합니다.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="provider:model-name",
    tools=[inspect_job, restart_job, delete_artifact],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "inspect_job": False,
                "restart_job": {
                    "allowed_decisions": ["approve", "reject"]
                },
                "delete_artifact": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            interrupt_mode="per_call",
        ),
    ],
    checkpointer=InMemorySaver(),
)

이 구성에서는 점검 작업은 검토 없이 진행하고, 재시작 및 삭제 작업은 결정을 위해 일시 중지합니다. approve는 원래 인수를 그대로 실행하고, edit은 실행 전에 인수를 변경하며, reject는 호출을 건너뛰고 거부 피드백을 에이전트에 반환합니다. 문서에서는 “사용자에게 묻기” 도구로 동작하는 respond도 설명합니다. 이 기능은 성공적인 도구 결과로 취급되므로 부작용을 일으키는 도구를 거부하는 데 사용해서는 안 됩니다.

프로덕션 환경에서는 인메모리 체크포인터를 영속 구현으로 교체하고, 안정적인 스레드 ID를 사용해 에이전트를 호출하세요.

config = {
    "configurable": {"thread_id": "ops-workflow-1842"}
}

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Inspect the failed job and restart it if safe.",
            }
        ]
    },
    config=config,
    version="v2",
)

버전 v2에서는 중단된 결과에 interrupts 컬렉션이 표시됩니다. 요청된 각 작업을 권한이 있는 검토자에게 보여준 뒤, 문서화된 Command 결정 형식으로 동일한 스레드를 재개하세요.

재시도와 승인을 올바른 순서로 배치

소스 문서에서는 중요한 미들웨어 규칙을 안내합니다. 호출별 검토를 사용할 때는 도구 재시도 또는 오류 처리 미들웨어보다 휴먼 인 더 루프 처리를 앞에 배치하세요. 그렇지 않으면 재시도로 인해 검토자에게 다시 승인을 요청하거나, 잘못된 응답을 도구 오류처럼 재시도할 수 있습니다.

의도된 순서는 다음과 같습니다.

  1. 모델이 도구 호출을 제안합니다.
  2. 정책에서 검토가 필요한지 확인합니다.
  3. 검토자가 호출을 승인·수정·거부합니다.
  4. 도구가 자체적인 제한된 재시도 정책에 따라 실행됩니다.
  5. 성공하면 에이전트로 돌아가고, 재시도 한도에 도달하면 복구 단계로 전환합니다.

중단에서 재개할 때 다시 실행되는 미들웨어에서는 부작용을 일으키지 마세요. 문서에서는 사람의 검토 단계 앞에 있는 미들웨어가 일시 중지 시점까지 다시 진입해도 안전해야 한다고 구체적으로 경고합니다.

재시도 대신 복구 상태 추가

재시도 예산을 소진하면 워크플로 ID, 도구 이름, 시도 횟수, 멱등성 키, 마지막으로 확인된 오류가 포함된 운영 이벤트를 기록하세요. 그런 다음 다음 세 가지 경로 중 하나를 선택합니다.

  • 확인: 외부 시스템을 조회해 원래 작업의 성공 여부를 확인합니다.
  • 에스컬레이션: 다음 조치를 결정할 수 있도록 충분한 맥락을 제공해 운영자의 판단을 요청합니다.
  • 보정: 별도로 명시적인 승인을 받은 시정 작업을 실행합니다.

불완전한 오류 메시지를 바탕으로 모델이 보정 작업을 지어내도록 하지 마세요. 구조화된 상태 데이터를 제공하고 사용 가능한 도구를 제한하세요.

그래프 수준의 실행 제한은 두 번째 안전장치입니다. 설치된 LangGraph 버전에서 지원하는 제한을 설정하고, 제한에 도달하면 조용히 계속 진행하는 대신 복구 이벤트로 처리하세요. 이를 통해 모델과 도구의 반복 루프가 무제한 프로덕션 프로세스로 이어지는 것을 방지할 수 있습니다.

문제 해결 체크리스트

  • 워크플로가 처음부터 다시 시작됩니다: 영속 체크포인터를 사용하고 있는지, thread_id가 동일하게 유지되는지 확인하세요.
  • 거부한 작업이 여전히 실행됩니다: 재개 결정이 respond가 아니라 거부인지 확인하세요.
  • 검토 요청이 너무 많이 표시됩니다: 인수 기반 when 조건을 추가해 위험한 호출만 중단되도록 하세요.
  • 재시도로 작업이 중복됩니다: 멱등성을 추가하고, 결과가 불분명한 경우 재시도하기 전에 상태를 확인할 도구를 마련하세요.
  • 같은 검토 요청이 반복해서 표시됩니다: 미들웨어 순서를 점검하고, 재시도 처리가 승인 경계를 잘못 감싸지 않는지 확인하세요.
  • 수정된 호출이 예상과 다르게 동작합니다: 수정된 인수를 직접 검증하세요. 문서화된 응답 스키마는 형식을 설명하지만 비즈니스 안전성을 반드시 강제하는 것은 아닙니다.

결론

신뢰할 수 있는 LangGraph 운영 에이전트는 제약 없는 챗봇이 아니라 실행 범위가 제한된 워크플로입니다. 각 도구에 재시도 예산을 설정하고, 오류를 분류하며, 상태를 저장하고, 위험한 호출을 통제하고, 복구를 명시적인 분기로 구성하세요. 그러면 사람의 승인은 비상시의 임시방편이 아니라 워크플로의 통제된 체크포인트가 됩니다.

출처

FAQ

LangGraph는 실패한 도구 호출을 자동으로 모두 재시도하나요?

그렇다고 가정해서는 안 됩니다. 재시도 동작을 명시적으로 정의하고, 오류를 분류하며, 최대 시도 횟수를 적용하세요. 설치된 스택에서 도구 재시도 미들웨어를 사용할 수는 있지만, 설정과 동작은 해당 버전의 문서에서 확인해야 합니다.

사람의 승인을 받으려면 체크포인팅이 왜 필요한가요?

결정이 내려질 때까지 중단을 통해 실행을 일시 정지합니다. 체크포인터는 그래프 상태를 보존하므로 승인, 수정, 거부 또는 직접 응답 후 동일한 워크플로 스레드를 재개할 수 있습니다.

도구 호출은 언제 사람의 검토를 받아야 하나요?

프로덕션 상태를 변경하거나, 데이터를 삭제하거나, 외부로 메시지를 보내거나, 비용이나 범위가 불확실한 호출은 검토를 받도록 하세요. 권한과 출력 한도가 명확하다면 읽기 전용 점검은 자동으로 실행할 수 있는 경우가 많습니다.

재시도 예산을 소진한 다음에는 어떻게 해야 하나요?

복구 경로로 전환하세요. 외부 작업을 확인하거나, 운영자에게 에스컬레이션하거나, 별도로 승인된 보정 작업을 실행할 수 있습니다. 결과가 불확실한 작업을 무작정 반복하지 마세요.

관련 글