5분 동안 도는 에이전트는 실패를 무시해도 됩니다. 5시간 동안 도는 에이전트는 타임아웃, 429, 끊긴 스트림, 그리고 아마 재시작까지 겪게 됩니다. 장시간 실행 에이전트에 관한 가이드는 대부분 워크플로 엔진을 권합니다. 꼭 필요하지 않을 수도 있습니다. 이 글은 평범한 에이전트 루프를 몇 시간씩 살려 두는 다섯 가지 습관을 OpenAI Python SDK 코드와 함께 다룹니다.
에이전트가 몇 시간씩 돌면 무엇이 깨지나요?
| 장애 | 증상 | 대응하는 습관 |
|---|---|---|
| 멈추거나 느린 호출 | 몇 분 동안 응답 없음 | 호출별 타임아웃, 스트리밍 |
| 속도 제한 또는 과부하 | 429, 5xx | 백오프를 둔 상한 있는 재시도 |
| 끊긴 스트림 | [DONE] 전에 연결 종료 |
불완전한 것으로 보고 호출 재시도 |
| 중복 부수 효과 | 재시도 후 도구가 두 번 실행됨 | 멱등성 키 |
| 프로세스 장애 또는 배포 | 에이전트가 1단계부터 다시 시작 | 단계별 체크포인트 |
1. 호출 하나에 얼마나 시간을 줘야 하나요?
OpenAI Python SDK의 README에 따르면 요청은 기본적으로 10분 후 타임아웃되고, 특정 오류는 두 번 재시도됩니다. 에이전트에서는 동작이 모르는 사이에 바뀌지 않도록 둘 다 직접 설정하세요.
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
timeout=300, max_retries=4)
타임아웃은 데이터로 정하세요. 하루 동안 모든 호출의 소요 시간을 기록하고, 성공한 호출 중 가장 느린 것보다 넉넉히 길게 잡으세요. 큰 프롬프트는 시작이 더 오래 걸리고, 추론 모델은 쓰기 전에 생각합니다. 속도가 초당 약 100토큰 수준이면 출력 토큰 8,000개만으로도 1분이 넘게 걸립니다. 계속 돌아가는 루프가 밤새 실행되지 않도록 작업마다 별도의 실제 시간 예산을 두세요.
2. 장시간 실행 에이전트에서 왜 스트리밍을 써야 하나요?
스트리밍은 모델이 일하는 동안 신호를 줍니다. 스트리밍이 없으면 느린 호출과 끊긴 연결은 타임아웃이 걸릴 때까지 똑같아 보입니다. 스트리밍을 쓰면 청크가 도착하는 것을 볼 수 있고, 마지막 청크에서 토큰 사용량도 받을 수 있습니다.
BroadNet의 스트리밍 규칙: 문자 그대로 data: [DONE] 줄이 올 때까지 읽으세요. 그 전에 연결이 닫히면 응답은 불완전합니다. X-Request-ID를 기록한 다음 새 요청을 보낼지 결정하세요. 스트리밍 전체 가이드를 참고하세요.
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가 볼 수 없는 것에 대해서만 그 위에 직접 재시도를 얹으세요.
- 재시도: 연결 오류, 429, 5xx, 불완전한 스트림. 지터와 상한(예: 4회)을 둔 지수 백오프를 쓰세요.
- 재시도하지 말고 고치기: 400, 401, 402, 403, 413, 422. 매번 똑같이 실패합니다. 오류 코드와 재시도 시점을 참고하세요.
- 재시도 예산은 호출별만이 아니라 작업별로도 잡으세요. 10단계가 각각 네 번씩 재시도하면 추가 호출이 40번입니다.
- 재시도를 다 쓰면 페일오버하세요. 실행이 제공업체 장애를 견뎌야 한다면 연결 오류, 5xx, 속도 제한 429를 두 번째 제공업체로 넘기세요. LLM API 페일오버에서 클라이언트 코드와 서킷 브레이커를 보여 줍니다.
종량제에서는 재시도할 때마다 새로운 추론이 되어 다시 과금됩니다. 종량제 키는 분당 요청 30개, 동시 처리 4개까지 허용하므로, 재시도가 몰리면 금방 속도 제한에 걸립니다. 속도 제한 계산기로 에이전트에 여유가 얼마나 있는지 확인할 수 있습니다. 백오프는 429 처리 글에서 자세히 다룹니다. 무제한 플랜에서는 재시도에 추가 비용이 없지만, 실행되는 동안 세션의 하나뿐인 요청 슬롯을 차지합니다.
4. 도구 호출을 어떻게 멱등적으로 만드나요?
모델 호출에는 부수 효과가 없습니다. 도구 호출에는 있을 수 있습니다. send_invoice가 실행된 뒤 단계가 저장되기 전에 에이전트가 죽으면, 재시작한 에이전트가 송장을 다시 보냅니다.
부수 효과가 있는 호출마다 작업과 단계에서 만든 멱등성 키를 주고, 실행 전에 확인해서 이미 기록되어 있으면 호출을 건너뛰세요.
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. 에이전트 체크포인트는 어떻게 남기나요?
완료된 단계마다 메시지 목록, 단계 번호, 부수 효과 키를 저장하세요. 시작할 때 최신 체크포인트가 있으면 불러옵니다.
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의 1,048,576 토큰에서도 컨텍스트 윈도 안에 머물 수 있습니다.
밤새 실행하기 전 체크리스트
- 클라이언트에 타임아웃과
max_retries를 명시적으로 설정. include_usage와 함께 스트리밍을 켜고, 불완전한 스트림은 재시도.- 작업별 재시도 예산과 실제 시간 한도.
- 쓰기, 전송, 결제를 하는 모든 도구에 멱등성 키.
- 단계마다 원자적으로 쓰는 체크포인트.
- 단계 번호, 소요 시간, 토큰,
X-Request-ID를 담은 로그.
여러 에이전트를 나란히 실행한다면 정액제로 코딩 에이전트 병렬 실행하기와 멀티 에이전트 구성의 비용을 읽어 보세요.
BroadNet Inference의 역할
BroadNet Inference는 표준 채팅 완성 스트리밍을 쓰고, 기록할 수 있는 X-Request-ID 헤더를 반환하며, 어떤 오류를 재시도해야 하는지 문서화하므로 위의 패턴이 그대로 작동합니다. 하루 종일 도는 에이전트라면 무제한 플랜이 세션당 월 $60 요금으로 DeepSeek V4.1 Flash의 토큰 계량을 없애 주므로 재시도가 무료가 됩니다. 다만 Meteor 1시간은 구매 후 1시간, Orbit 1주일은 7일 후에 끝나므로, 긴 작업은 그 기간 안에 끝나거나 갱신되는 Full Moon 세션으로 옮겨야 합니다. 플랜은 inference.broadnet.ai/plans에 있습니다.
