내결함성

내결함성 (Fault tolerance)

속도 제한, 재시도, 폴백, 오류 처리로 딥 에이전트를 복원력 있게 만드세요.

내결함성 미들웨어는 문제가 발생해도 딥 에이전트가 계속 실행되게 해줘요. 모든 오류를 같은 방식으로 처리해서는 안 됩니다: 일시적 실패(네트워크 타임아웃, 속도 제한)는 자동으로 재시도하고, LLM이 복구할 수 있는 오류(나쁜 도구 출력, 파싱 실패)는 모델에 다시 피드백하며, 인간 입력이 필요한 오류는 에이전트를 일시 중지해야 합니다.

출처: 문서

본문

오류 처리 전략 (Error handling strategies)

오류 유형마다 다른 처리 전략이 필요합니다:

아래 섹션에서 각 전략을 코드 예시와 함께 다룹니다.

일시적 오류 (Transient errors): 네트워크 문제와 속도 제한을 자동으로 재시도하도록 재시도 미들웨어를 추가하세요. 모델 호출과 도구 호출은 각각 지수 백오프가 있는 자체 재시도 미들웨어가 있습니다:

import { createAgent, modelRetryMiddleware, toolRetryMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool, fetchUrlTool],
  middleware: [
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});

사용자 해결 가능 (User-fixable): 필요할 때(계정 ID, 주문 번호, 명확화 등) 일시 중지하고 사용자에게 정보를 수집하세요. interrupt_on을 사용해 특정 도구 호출 전에 에이전트를 일시 중지합니다:

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [sendEmailTool, deleteRecordTool],
  interruptOn: {
    send_email: true,
    delete_record: true,
  },
});

전체 휴먼 인 더 루프 가이드는 휴먼 인 더 루프를 참고하세요.

프로바이더 중단 (Provider outage): 기본 모델 프로바이더가 완전히 다운되면 ModelFallbackMiddleware로 대체 모델로 전환하세요:

import { createAgent, modelFallbackMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool],
  middleware: [
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

과도한 호출 (Excessive calls): 제한이 없으면 혼란스러운 에이전트가 같은 도구 호출을 반복하거나 수백 번의 모델 호출을 만들어 몇 분 안에 LLM API 예산을 태울 수 있습니다. 실행당 모델 호출과 도구 실행 모두에 상한을 설정하세요:

import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  tools: [searchTool],
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});

예상치 못한 (Unexpected): 디버깅을 위해 그대로 전파하세요. 처리할 수 없는 것은 잡지 마세요. 이 패턴은 JavaScript SDK의 커스텀 미들웨어에도 적용됩니다.

속도 제한 (Rate limiting)

리소스 사용을 제한하는 두 가지 상호 보완적인 방법이 있습니다: 모델 프로바이더에 대한 요청 속도 제어와 실행당 총 호출 수 상한.

프로바이더 속도 제한: 채팅 모델 프로바이더는 주어진 시간에 만들 수 있는 호출 수에 제한을 둡니다. 요청이 만들어지는 속도를 제어하려면 rate_limiter로 모델을 초기화하세요.

호출 상한 (Call limits): 제한이 없으면 혼란스러운 에이전트가 같은 도구 호출을 반복하거나 수백 번의 모델 호출을 만들어 몇 분 안에 LLM API 예산을 태울 수 있습니다. 실행당 모델 호출과 도구 실행 모두에 상한을 설정하세요:

import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});

run_limit으로 단일 호출 내에서 호출을 상한(매 턴마다 초기화)하세요. thread_limit으로 전체 대화에 걸쳐 호출을 상한(체크포인터 필요)하세요. 전체 구성은 ModelCallLimitMiddleware와 ToolCallLimitMiddleware를 참고하세요.

재시도 (Retries)

일시적 실패(네트워크 타임아웃, 속도 제한)는 자동으로 재시도해야 합니다. 모델 호출과 도구 호출은 각각 지수 백오프가 있는 자체 재시도 미들웨어가 있습니다:

import {
  createAgent,
  modelRetryMiddleware,
  toolRetryMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    // Retry model calls on rate limits, timeouts, and 5xx errors
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    // Retry specific tools that hit external APIs (not all tools)
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});

ToolRetryMiddleware를 모든 것을 재시도하는 대신 특정 도구로 범위를 한정하세요. 실패한 파일시스템 read_file은 재시도해도 이점이 없지만, 타임아웃된 웹 검색은 이점이 있을 것입니다. 전체 구성은 ModelRetryMiddleware를 참고하세요.

폴백 (Fallbacks)

기본 모델 프로바이더가 완전히 다운되면 폴백 미들웨어가 대체 모델로 전환합니다:

import {
  createAgent,
  modelFallbackMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.6-flash",
  middleware: [
    // If the primary model is fully down, fall back to an alternative
    modelFallbackMiddleware("gpt-5.5"),
  ],
});

전체 구성은 ModelFallbackMiddleware를 참고하세요.

오류 처리 (Error handling)

도구가 실행 중 예외를 발생시키면 기본적으로 에이전트 실행이 중단됩니다. ToolErrorMiddleware는 JavaScript SDK에서 아직 제공되지 않습니다.

더 알아보기

• 이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
• GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.