---
title: "장시간 실행 AI 에이전트: 타임아웃, 재시도, 체크포인트 | BroadRouter"
description: "LLM 에이전트를 몇 시간씩 안정적으로 돌리는 법: 호출별 타임아웃, 멈춤을 감지하는 스트리밍, 안전한 재시도, 멱등적인 도구 부수 효과, 단계별 체크포인트."
url: https://broadrouter.com/ko/blog/long-running-agents-timeouts-retries/
lang: ko
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/blog/long-running-agents-timeouts-retries/) (2026-11-16 업데이트).

# 장시간 실행 에이전트: 버티는 타임아웃, 재시도, 체크포인트

BroadNet Inference 팀 · 4분 분량 · 게시 2026-11-14 · 업데이트 2026-11-16

모델 호출은 언제든 버릴 수 있는 것으로, 에이전트 상태는 영속적인 것으로 다루세요. 호출마다 타임아웃을 두고, 스트리밍으로 멈춤을 감지하며, 429, 5xx, 끊긴 스트림은 상한이 있는 백오프로 재시도하고, 부수 효과가 있는 도구에는 모두 멱등성 키를 주세요. 단계마다 메시지 목록을 저장하면 장애가 나도 처음이 아니라 마지막 체크포인트부터 재개합니다.

## 핵심 요약

-   OpenAI Python SDK는 기본적으로 10분 후 타임아웃되고 두 번 재시도합니다. 에이전트에서는 둘 다 명시적으로 설정하세요.
-   data \[DONE\] 전에 끝난 스트림은 불완전한 응답입니다. 이를 재시도하면 새로운 추론이 되며, 종량제에서는 다시 과금됩니다.
-   모델 호출은 재시도해도 안전합니다. 도구의 부수 효과는 멱등성 키가 없다면 안전하지 않습니다.
-   완료된 단계마다 체크포인트를 남기세요: 메시지 목록, 단계 번호, 완료된 부수 효과의 ID.
-   플랜 세션에서는 재시도에 추가 비용이 없지만, 실행되는 동안 하나뿐인 요청 슬롯을 차지합니다.

**이 페이지의 내용**

1.  에이전트가 몇 시간씩 돌면 무엇이 깨지나요?
2.  1\. 호출 하나에 얼마나 시간을 줘야 하나요?
3.  2\. 장시간 실행 에이전트에서 왜 스트리밍을 써야 하나요?
4.  3\. 무엇을 재시도해야 하나요?
5.  4\. 도구 호출을 어떻게 멱등적으로 만드나요?
6.  5\. 에이전트 체크포인트는 어떻게 남기나요?
7.  밤새 실행하기 전 체크리스트
8.  BroadNet Inference의 역할

5분 동안 도는 에이전트는 실패를 무시해도 됩니다. 5시간 동안 도는 에이전트는 타임아웃, 429, 끊긴 스트림, 그리고 아마 재시작까지 겪게 됩니다. 장시간 실행 에이전트에 관한 가이드는 대부분 워크플로 엔진을 권합니다. 꼭 필요하지 않을 수도 있습니다. 이 글은 평범한 에이전트 루프를 몇 시간씩 살려 두는 다섯 가지 습관을 OpenAI Python SDK 코드와 함께 다룹니다.

## 에이전트가 몇 시간씩 돌면 무엇이 깨지나요?

| 장애 | 증상 | 대응하는 습관 |
| --- | --- | --- |
| 멈추거나 느린 호출 | 몇 분 동안 응답 없음 | 호출별 타임아웃, 스트리밍 |
| 속도 제한 또는 과부하 | 429, 5xx | 백오프를 둔 상한 있는 재시도 |
| 끊긴 스트림 | `[DONE]` 전에 연결 종료 | 불완전한 것으로 보고 호출 재시도 |
| 중복 부수 효과 | 재시도 후 도구가 두 번 실행됨 | 멱등성 키 |
| 프로세스 장애 또는 배포 | 에이전트가 1단계부터 다시 시작 | 단계별 체크포인트 |

## 1\. 호출 하나에 얼마나 시간을 줘야 하나요?

OpenAI Python SDK의 README에 따르면 요청은 기본적으로 10분 후 타임아웃되고, 특정 오류는 두 번 재시도됩니다. 에이전트에서는 동작이 모르는 사이에 바뀌지 않도록 둘 다 직접 설정하세요.

```python
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)
```

타임아웃은 데이터로 정하세요. 하루 동안 모든 호출의 소요 시간을 기록하고, 성공한 호출 중 가장 느린 것보다 넉넉히 길게 잡으세요. 큰 프롬프트는 시작이 더 오래 걸리고, [추론 모델](https://broadrouter.com/ko/glossary/reasoning-tokens/)은 쓰기 전에 생각합니다. 속도가 초당 약 100토큰 수준이면 출력 토큰 8,000개만으로도 1분이 넘게 걸립니다. 계속 돌아가는 루프가 밤새 실행되지 않도록 **작업**마다 별도의 실제 시간 예산을 두세요.

## 2\. 장시간 실행 에이전트에서 왜 스트리밍을 써야 하나요?

[스트리밍](https://broadrouter.com/ko/glossary/streaming/)은 모델이 일하는 동안 신호를 줍니다. 스트리밍이 없으면 느린 호출과 끊긴 연결은 타임아웃이 걸릴 때까지 똑같아 보입니다. 스트리밍을 쓰면 청크가 도착하는 것을 볼 수 있고, 마지막 청크에서 토큰 사용량도 받을 수 있습니다.

BroadNet의 스트리밍 규칙: 문자 그대로 `data: [DONE]` 줄이 올 때까지 읽으세요. 그 전에 연결이 닫히면 응답은 불완전합니다. `X-Request-ID`를 기록한 다음 새 요청을 보낼지 결정하세요. [스트리밍 전체 가이드](https://broadrouter.com/ko/guides/streaming-chat-completions/)를 참고하세요.

```python
def call_streaming(messages, tools=None):
    parts, done = [], False
    stream = client.chat.completions.create(
        model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
        stream_options={"include_usage": True}, max_tokens=8000)
    for chunk in stream:
        if chunk.choices and chunk.choices[0].finish_reason:
            done = True
        if chunk.choices and chunk.choices[0].delta.content:
            parts.append(chunk.choices[0].delta.content)
    if not done:
        raise IncompleteStream()   # retry the whole call
    return "".join(parts)
```

이 스케치는 텍스트만 모읍니다. 도구 호출을 스트리밍한다면 `delta.tool_calls`도 인덱스별로 누적하세요.

## 3\. 무엇을 재시도해야 하나요?

SDK는 이미 연결 오류, 408, 409, 429, 5xx를 재시도합니다. 불완전한 스트림처럼 SDK가 볼 수 없는 것에 대해서만 그 위에 직접 재시도를 얹으세요.

1.  **재시도:** 연결 오류, 429, 5xx, 불완전한 스트림. 지터와 상한(예: 4회)을 둔 [지수 백오프](https://broadrouter.com/ko/glossary/exponential-backoff/)를 쓰세요.
2.  **재시도하지 말고 고치기:** 400, 401, 402, 403, 413, 422. 매번 똑같이 실패합니다. [오류 코드와 재시도 시점](https://broadrouter.com/ko/guides/errors-and-retries/)을 참고하세요.
3.  **재시도 예산은 호출별만이 아니라 작업별로도** 잡으세요. 10단계가 각각 네 번씩 재시도하면 추가 호출이 40번입니다.
4.  **재시도를 다 쓰면 페일오버하세요.** 실행이 제공업체 장애를 견뎌야 한다면 연결 오류, 5xx, 속도 제한 429를 두 번째 제공업체로 넘기세요. [LLM API 페일오버](https://broadrouter.com/ko/blog/llm-api-failover-fallback/)에서 클라이언트 코드와 서킷 브레이커를 보여 줍니다.

종량제에서는 재시도할 때마다 새로운 추론이 되어 다시 과금됩니다. 종량제 키는 분당 요청 30개, 동시 처리 4개까지 허용하므로, 재시도가 몰리면 금방 [속도 제한](https://broadrouter.com/ko/glossary/rate-limit/)에 걸립니다. [속도 제한 계산기](https://broadrouter.com/tools/llm-rate-limit-calculator/)로 에이전트에 여유가 얼마나 있는지 확인할 수 있습니다. 백오프는 [429 처리 글](https://broadrouter.com/ko/blog/handle-llm-api-429-rate-limits/)에서 자세히 다룹니다. [무제한 플랜](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)에서는 재시도에 추가 비용이 없지만, 실행되는 동안 세션의 하나뿐인 요청 슬롯을 차지합니다.

## 4\. 도구 호출을 어떻게 멱등적으로 만드나요?

모델 호출에는 부수 효과가 없습니다. 도구 호출에는 있을 수 있습니다. `send_invoice`가 실행된 뒤 단계가 저장되기 전에 에이전트가 죽으면, 재시작한 에이전트가 송장을 다시 보냅니다.

부수 효과가 있는 호출마다 작업과 단계에서 만든 [멱등성 키](https://broadrouter.com/ko/glossary/idempotency-key/)를 주고, 실행 전에 확인해서 이미 기록되어 있으면 호출을 건너뛰세요.

```python
def run_side_effect(task_id, step, call, store):
    key = f"{task_id}:{step}:{call.id}"
    if store.done(key):
        return store.result(key)       # already ran: return the saved result
    result = execute(call)             # pass key to the API if it supports one
    store.save(key, result)
    return result
```

결제와 메시징 API 중에는 멱등성 키 헤더를 받는 곳이 많습니다. 지원한다면 키를 그대로 넘기세요.

## 5\. 에이전트 체크포인트는 어떻게 남기나요?

완료된 단계마다 메시지 목록, 단계 번호, 부수 효과 키를 저장하세요. 시작할 때 최신 체크포인트가 있으면 불러옵니다.

```python
def save_checkpoint(path, step, messages):
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump({"step": step, "messages": messages}, f)
    os.replace(tmp, path)   # atomic on the same filesystem
```

임시 파일에 쓰고 이름을 바꾸면, 쓰는 도중에 장애가 나도 절반만 쓰인 체크포인트가 남지 않습니다. 아주 긴 세션이라면 **요약**도 체크포인트로 남기세요. 오래된 턴을 짧은 요약으로 바꾸면 재개한 에이전트가 거대한 기록을 다시 불러오지 않습니다. [DeepSeek V4.1 Flash](https://broadrouter.com/ko/models/deepseek-v4.1-flash/)의 1,048,576 토큰에서도 [컨텍스트 윈도](https://broadrouter.com/ko/glossary/context-window/) 안에 머물 수 있습니다.

## 밤새 실행하기 전 체크리스트

1.  클라이언트에 타임아웃과 `max_retries`를 명시적으로 설정.
2.  `include_usage`와 함께 스트리밍을 켜고, 불완전한 스트림은 재시도.
3.  작업별 재시도 예산과 실제 시간 한도.
4.  쓰기, 전송, 결제를 하는 모든 도구에 멱등성 키.
5.  단계마다 원자적으로 쓰는 체크포인트.
6.  단계 번호, 소요 시간, 토큰, `X-Request-ID`를 담은 로그.

여러 에이전트를 나란히 실행한다면 [정액제로 코딩 에이전트 병렬 실행하기](https://broadrouter.com/ko/blog/run-parallel-coding-agents-flat-rate/)와 [멀티 에이전트 구성의 비용](https://broadrouter.com/ko/blog/multi-agent-cost/)을 읽어 보세요.

## BroadNet Inference의 역할

BroadNet Inference는 표준 채팅 완성 스트리밍을 쓰고, 기록할 수 있는 `X-Request-ID` 헤더를 반환하며, 어떤 오류를 재시도해야 하는지 문서화하므로 위의 패턴이 그대로 작동합니다. 하루 종일 도는 에이전트라면 무제한 플랜이 세션당 월 $60 요금으로 DeepSeek V4.1 Flash의 토큰 계량을 없애 주므로 재시도가 무료가 됩니다. 다만 Meteor 1시간은 구매 후 1시간, Orbit 1주일은 7일 후에 끝나므로, 긴 작업은 그 기간 안에 끝나거나 갱신되는 Full Moon 세션으로 옮겨야 합니다. 플랜은 [inference.broadnet.ai/plans](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-long-running-agents-timeouts-retries&utm_content=body)에 있습니다.

관련 무료 도구 (영어)

-   [Agent run cost estimator](https://broadrouter.com/tools/agent-run-cost-estimator/) Context growth per step, total tokens and cost of one agent run, with a DeepSeek session comparison.
-   [LLM batch job planner](https://broadrouter.com/tools/llm-batch-job-planner/) Run time, binding limit, cost per model and the flat sessions needed to finish a big job by a deadline.
-   [Flat-rate vs per-token LLM cost calculator](https://broadrouter.com/tools/flat-rate-vs-per-token-calculator/) Break-even between an unlimited plan and paying per token, per agent.
-   [LLM rate limit and concurrency calculator](https://broadrouter.com/tools/llm-rate-limit-calculator/) Which limit binds first: RPM, TPM or concurrency, with Little's law.

[무료 도구 (영어)](https://broadrouter.com/tools/)

## 이 글의 용어

[멱등성 키(idempotency key)](https://broadrouter.com/ko/glossary/idempotency-key/)

멱등성 키(idempotency key)는 결제나 구매처럼 상태를 바꾸는 요청에 클라이언트가 붙이는 고유한 값으로, 보통 UUID 같은 무작위 ID입니다. 같은 요청이 같은 키로 다시 오면 서버는 작업을 두 번 수행하지 않고 처음 결과를 돌려줍니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[요청 타임아웃(request timeout)](https://broadrouter.com/ko/glossary/request-timeout/)

요청 타임아웃(request timeout)은 HTTP 클라이언트가 요청을 포기하기 전까지 서버를 기다리는 최대 시간입니다. 클라이언트는 보통 연결을 여는 연결 타임아웃과 데이터를 기다리는 읽기 타임아웃으로 나눕니다. 긴 답변은 시간이 걸리므로 LLM 호출에는 넉넉한 읽기 타임아웃이 필요합니다.

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[멀티 에이전트 시스템(multi-agent system)](https://broadrouter.com/ko/glossary/multi-agent-system/)

멀티 에이전트 시스템(multi-agent system)은 각자 프롬프트, 도구, 컨텍스트를 가진 여러 에이전트가 하나의 작업을 나눠 처리하는 LLM 애플리케이션입니다. 흔한 설계는 오케스트레이터-워커 방식으로, 리드 에이전트가 계획을 세우고 워커 에이전트를 병렬로 실행한 뒤 결과를 합칩니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

## 자주 묻는 질문

### 에이전트에서 LLM API 호출 타임아웃은 얼마로 설정해야 하나요?

정상적인 호출 중 가장 느린 것보다는 길고, 멈춘 호출을 잡아낼 만큼은 짧아야 합니다. OpenAI Python SDK의 기본값은 10분입니다. 많은 에이전트는 스트리밍과 함께 호출당 2~5분을 쓰고, 작업마다 별도의 실제 시간 한도를 둡니다.

### 에이전트는 어떤 LLM API 오류를 재시도해야 하나요?

연결 오류, 429, 5xx는 지터를 넣은 상한 있는 지수 백오프로 재시도하세요. 400, 401, 402, 403, 413, 422는 재시도하지 말고 원인을 고치세요. BroadNet에서는 실패마다 X-Request-ID 헤더도 기록하세요.

### 채팅 완성 요청을 재시도해도 안전한가요?

모델 호출 자체에는 부수 효과가 없으므로 안전합니다. 다만 새로운 추론이므로 종량제에서는 다시 과금됩니다. 위험한 것은 도구입니다. 도구가 멱등성 키를 쓰지 않으면, 재시도한 단계가 이메일을 두 번 보낼 수 있습니다.

### 장애 후 에이전트를 어떻게 재개하나요?

완료된 단계마다 메시지 목록과 단계 번호를 저장하고, 실행하기 전에 부수 효과 ID를 기록한 다음, 시작할 때 다시 불러오세요. 에이전트는 마지막으로 저장된 단계부터 재개합니다.

### 장시간 실행 에이전트에는 무제한 플랜이 필요한가요?

꼭 그렇지는 않지만, 종량제에서는 재시도와 긴 컨텍스트 비용이 쌓입니다. BroadNet 무제한 플랜에서는 DeepSeek V4.1 Flash에 토큰 계량이 없으므로 재시도에 추가 비용이 들지 않습니다. 다만 각 세션은 여전히 한 번에 요청 1개만 실행합니다.

## 이어서 읽기

-   [오픈 모델 도구 호출: 스키마, 병렬 호출, 재시도](https://broadrouter.com/ko/blog/tool-calling-open-models/)
-   [멀티 에이전트 구성의 실제 비용: 토큰당 과금 vs 정액 세션](https://broadrouter.com/ko/blog/multi-agent-cost/)
-   [정액제 LLM API로 코딩 에이전트를 병렬 실행하는 방법](https://broadrouter.com/ko/blog/run-parallel-coding-agents-flat-rate/)
-   [LLM API 플랜의 "무제한"은 실제로 무엇을 뜻할까](https://broadrouter.com/ko/blog/what-unlimited-llm-api-really-means/)
-   [LLM API 페일오버: 직접 작성한 코드로 두 번째 제공업체로 전환하기](https://broadrouter.com/ko/blog/llm-api-failover-fallback/)
-   [AI 코딩 에이전트 1회 실행 비용: 단계 수, 컨텍스트 증가, 캐싱](https://broadrouter.com/ko/blog/ai-coding-agent-run-cost/)
-   [오픈 모델로 Claude Code 쓰기: 프록시, 네이티브 엔드포인트, 한계](https://broadrouter.com/ko/blog/claude-code-with-openai-compatible-models/)
-   [가이드: BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)
-   [가이드: 채팅 완성 스트리밍과 끊긴 연결 처리하기](https://broadrouter.com/ko/guides/streaming-chat-completions/)
-   [가이드: 에이전트용 무제한 LLM API 플랜은 어떻게 작동하나요?](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)
-   [가이드: BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-long-running-agents-timeouts-retries&utm_content=page-cta) ·

**출처**

-   [OpenAI Python SDK README, 재시도와 타임아웃 (2026-11-14 확인)](https://github.com/openai/openai-python)
-   [BroadNet Inference API 레퍼런스, 오류와 재시도 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-long-running-agents-timeouts-retries&utm_content=sources#errors)
-   [BroadNet Inference API 레퍼런스, 스트리밍과 한도 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-long-running-agents-timeouts-retries&utm_content=sources#requests)
-   [BroadNet Inference 무제한 플랜 (영어)](https://inference.broadnet.ai/plans?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-long-running-agents-timeouts-retries&utm_content=sources)
