다중 에이전트 워크플로 실행 시 "API 시간 초과 오류" 해결 방법

다중 에이전트 워크플로에서 발생하는 "API 시간 초과 오류"는 단순히 숫자 하나만 변경한다고 해결되는 경우가 드뭅니다. 플래너는 세 개의 에이전트를 호출할 수 있고, 각 에이전트는 LLM, 검색 서비스, 데이터베이스 또는 도구 API를 호출할 수 있으며, 각 계층마다 자체적인 시간 초과, 재시도 정책, 연결 풀 및 동시 실행 제한을 설정할 수 있습니다. 실질적인 해결책은 어느 계층에서 먼저 시간 초과가 발생하는지 파악한 다음, 대기 시간 연장, 동시 호출 횟수 감소, 효율적인 재시도, 임계 경로 단축 또는 비동기 작업 설계 중에서 선택하는 것입니다.

절충점이 중요합니다. 타임아웃 시간을 늘리는 것은 간단하지만 리소스를 더 오래 점유하게 되고, 재시도를 너무 많이 하면 부하와 비용이 증가할 수 있습니다. 동시 실행 수를 줄이면 안정성은 향상되지만 최대 처리량이 감소하고, 병렬 에이전트는 하위 서비스가 분산된 부하를 감당할 수 있을 때만 실제 지연 시간을 줄입니다. 모든 다중 에이전트 시스템에 적용할 수 있는 최적의 설정은 하나로 정해져 있지 않습니다.

실제로 어떤 타임아웃에 걸린 건가요?

모든 타임아웃을 동일한 이벤트로 처리하기보다는 실패 유형을 분류하는 것부터 시작하세요. HTTP 클라이언트는 연결, 읽기, 쓰기 또는 연결 풀에서 연결을 기다리는 동안 타임아웃이 발생할 수 있습니다. 예를 들어 HTTPX는 연결, 읽기, 쓰기, 풀의 네 가지 타임아웃 유형을 명시하고 있습니다. 기본 동작은 전체 요청 시간 5초가 아닌 네트워크 활동이 5초 동안 없을 경우 타임아웃을 발생시키는 것입니다. 자세한 내용은 HTTPX 공식 타임아웃 문서를 참조하세요 .

OpenAI Python SDK를 사용하는 경우, 현재 공식 README 파일에는 요청에 대한 기본 클라이언트 타임아웃이 10분으로 설정되어 있으며, 타임아웃 실패 시 기본적으로 두 번 재시도한다고 명시되어 있습니다. 또한 SDK는 연결 오류 및 HTTP 408, 409, 429, 5xx 응답에 대해 짧은 지수 백오프를 사용하여 자동으로 재시도합니다. 이는 SDK의 기본 설정이며, 요청 앞에 있는 모든 프록시, 로드 밸런서, 게이트웨이 또는 오케스트레이터가 10분을 기다린다는 보장은 아닙니다. 자세한 내용은 OpenAI Python SDK 공식 README 파일을 참조하십시오 .

어떤 해결책을 선택해야 할까요?

1단계: 마감일을 초과한 첫 번째 레이어를 찾습니다.

전체 워크플로에 대한 상관 관계 ID와 각 상담원 및 도구 호출에 대한 스팬 또는 하위 ID를 기록합니다. 시작 시간, 종료 시간, 엔드포인트, 시도 횟수, 예외 유형, 가능한 경우 응답 상태, 그리고 취소가 발신자 측에서 발생했는지 또는 하위 서비스 측에서 발생했는지 여부를 기록합니다.

중요한 질문은 "누가 먼저 기다림을 멈췄는가?"입니다. LLM 호출이 42초 만에 완료되었지만 API 게이트웨이가 30초 만에 포기하는 경우, LLM 클라이언트 시간 초과를 60초에서 120초로 늘려도 아무런 변화가 없습니다. Amazon의 API Gateway HTTP API 관련 최신 문서에는 최대 통합 시간 초과가 30초로 명시되어 있는데, 이는 연결 과정에서 가장 짧은 마감 시간이 결과에 영향을 미치는 이유를 잘 보여주는 예입니다. Amazon API Gateway HTTP API 할당량을 참조하세요 .

2단계: 평균 지연 시간뿐만 아니라 핵심 경로도 측정하십시오.

평균 지연 시간은 양호해 보일 수 있지만, 소수의 느린 호출로 인해 대부분의 워크플로 오류가 발생할 수 있습니다. 최소한 종속성별 성공률과 p50, p95, p99 지연 시간을 추적하십시오. 팬아웃 단계에서는 큐 시간과 연결 풀 대기 시간도 기록해야 합니다. "느린 API"처럼 보이는 현상이 실제로는 과부하된 클라이언트가 사용 가능한 연결을 기다리는 것일 수 있기 때문입니다.

추적 기능을 사용하여 다음 세 가지 실질적인 질문에 대한 답을 찾으세요. 어떤 종속성이 중요 경로를 지배하는지, 여러 개의 느린 에이전트가 동시에 실행될 수 있음에도 불구하고 순차적으로 실행되는지, 그리고 동시성 급증이 429, 풀 타임아웃 또는 5xx 오류와 일치하는지 여부입니다.

3단계: 외부에서부터 타임아웃 예산을 수립합니다.

먼저 전체 워크플로 마감 시간을 설정한 다음, 하위 계층의 마감 시간을 줄여 오케스트레이터가 복구할 수 있도록 하위 계층에서 오류가 조기에 발생하도록 합니다. 예를 들어, 사용자에게 표시되는 마감 시간을 120초로 설정하면 오케스트레이션 및 응답 처리에 10초를 할당하여 유용한 작업에 110초를 남길 수 있습니다. 개별 도구 호출에는 15초를, 모델 호출에는 관찰된 지연 시간에 따라 45초 또는 60초를 할당할 수 있습니다.

이러한 값을 맹목적으로 복사하지 마십시오. 이는 예산 책정 방법의 예시일 뿐이며, 보편적인 기본값이 아닙니다. 측정된 지연 시간 분포와 제품 SLO를 기반으로 값을 선택하십시오. 외부 마감 시간은 내부 호출, 허용된 재시도 시간, 백오프 지연 시간 및 정리 시간을 포함할 만큼 충분히 길어야 합니다.

Python 3.11 이상 버전에서는 asyncio.timeout()비동기 작업에 마감 시간을 설정할 수 있습니다. 마감 시간이 만료되면 작업이 취소되고 컨텍스트 관리자에 오류가 표시됩니다 TimeoutError. Python asyncio 타임아웃에 대한 공식 문서를 참조하십시오 .

import asyncio

async def run_stage():
    try:
        async with asyncio.timeout(90):
            return await run_agents()
    except TimeoutError:
        return {"status": "partial", "reason": "stage_timeout"}

4단계: 재시도 횟수를 늘리기 전에 동시 접속자 수를 제한하세요.

다중 에이전트 시스템은 예상보다 빠른 속도로 에이전트 수가 증가하여 실패하는 경우가 많습니다. 예를 들어, 20명의 사용자 요청이 각각 5개의 에이전트를 실행하고 각 에이전트가 2개의 도구를 실행하는 경우, 시스템은 재시도 전에 최대 200개의 하위 시스템 호출을 생성할 수 있습니다. 이때 재시도 기능을 추가하면 시스템 혼잡이 재시도 폭증으로 이어질 수 있습니다.

429 응답, 풀 타임아웃, 대기 시간 증가 또는 하위 종속성 포화 상태가 발생할 때 동시 실행 제한을 적용하는 것이 종종 더 나은 첫 번째 조치입니다. Python은 카운터를 기반으로 asyncio.Semaphore보호된 영역에 동시에 진입하는 코루틴 수를 제한하는 간단한 방법을 제공합니다. Python 세마포어 공식 문서를 참조하세요 .

import asyncio

sem = asyncio.Semaphore(8)

async def guarded_agent_call(agent, task):
    async with sem:
        return await agent.run(task)

이러한 절충은 의도적인 것입니다. 낮은 제한값은 하위 서비스를 보호하지만 애플리케이션 내부의 대기 시간을 증가시킬 수 있습니다. 따라서 시스템이 예약할 수 있는 최대값을 선택하기보다는 처리량, p95 지연 시간, 속도 제한 및 연결 풀 용량을 고려하여 조정하십시오.

5단계: 나중에 성공할 가능성이 높은 실패만 다시 시도하십시오.

재시도 기능은 일시적인 연결 실패, 속도 제한, 특정 서버 오류 및 요청 시간 초과와 같이 작업을 반복해도 안전한 경우에 유용합니다. 하지만 유효성 검사 오류, 인증 실패, 결정론적 도구 버그 또는 멱등성 보호가 없는 부작용이 있는 작업에는 재시도 기능을 기본값으로 사용하는 것은 적절하지 않습니다.

재시도 횟수 증가에 주의하세요. SDK에서 두 번 재시도하는 경우, 하나의 논리적 호출에 대해 최대 세 번의 시도가 발생할 수 있습니다. 에이전트 계층에서도 전체 호출을 두 번 재시도하면, 이론적으로 해당 논리적 작업에 대해 최대 9번의 시도가 가능해집니다. 즉, 외부 재시도 3회에 SDK 재시도 3회를 곱한 값입니다. 오케스트레이터가 5개 ​​에이전트 단계 전체를 재시도하는 경우, 요청량이 급격히 증가할 수 있습니다.

가능한 경우 재시도 소유권을 중앙 집중화하세요. OpenAI Python SDK를 사용하는 LLM 호출의 경우, 현재 SDK는 기본적으로 특정 유형의 실패에 대해 두 번 재시도한다는 점을 기억하세요. 명확한 이유가 있고 총 시도 횟수를 제한할 수 있는 경우에만 외부 재시도를 추가하세요.

6단계: 팬아웃 문제를 발생시키지 않고 핵심 경로를 단축합니다.

기획자, 연구자, 평가자, 작성자 에이전트가 엄격하게 순차적으로 실행될 경우, 전체 지연 시간은 각 에이전트 실행 시간의 합과 거의 같습니다. 하지만 독립적인 분기들이 동시에 실행될 수도 있는데, 이 경우 실제 소요 시간은 모든 분기의 합이 아니라 가장 느린 분기의 소요 시간으로 단축됩니다.

파이썬의 TaskGroup은 asyncio.TaskGroup관련된 작업을 동시에 실행하는 구조화된 방법입니다. 현재 파이썬 공식 문서에 따르면 TaskGroup은 그룹 내 작업들을 기다리고, 작업 중 하나라도 취소 예외가 아닌 예외와 함께 실패하면 나머지 작업들을 취소하여, 구조화되지 않은 작업 생성 방식보다 더 강력한 안전성을 제공합니다. 자세한 내용은 파이썬 TaskGroup 공식 문서를 참조하십시오 .

병렬 처리는 비용이 발생합니다. 동일한 공급자가 분당 요청 수 또는 동시 요청 수에 엄격한 제한을 두는 경우, 에이전트 4개를 동시에 실행하면 느리지만 성공적인 워크플로가 429개의 응답이 폭증하는 빠른 워크플로로 바뀔 수 있습니다. 완전히 독립적인 작업만 병렬화하고 전체 동시 요청 제한은 그대로 유지하십시오.

7단계: 동기식 HTTP 요청 사용을 언제 중단해야 할까요?

일반적인 워크플로가 네트워크 경로에서 가장 짧은 요청 시간 초과보다 오래 지속되는 경우, 시간 초과를 계속 늘리는 것보다 비동기 작업 모델로 전환하는 것이 일반적으로 더 깔끔합니다. 초기 HTTP 요청은 입력을 검증하고, 영구적인 작업을 생성하고, 즉시 작업 ID를 반환할 수 있습니다. 그러면 작업자는 요청 수명 주기 외부에서 다중 에이전트 그래프를 실행하고, 클라이언트는 폴링, 서버 전송 이벤트, 웹소켓 또는 웹훅을 통해 진행 상황을 수신합니다.

스트리밍은 서버가 의미 있는 출력을 조기에 전송할 수 있을 때 유용합니다. 예를 들어, OpenAI Python SDK는 Responses API 호출에 대해 서버 전송 이벤트 스트리밍을 지원합니다. 스트리밍은 체감 응답성을 향상시키고 데이터를 생성하는 활성 연결을 유지할 수 있지만, 모든 프록시의 최대 요청 수명 문제를 자동으로 해결하지는 않습니다. 자세한 내용은 OpenAI 공식 스트리밍 이벤트 참조 문서를 확인하세요 .

즉각적인 편의성보다 내구성이 더 중요한 경우 비동기 작업을 선택하십시오. 예를 들어 장시간 소요되는 조사 작업, 사람의 승인이 필요한 에이전트 워크플로, 잦은 도구 호출, 반복을 피하고 싶은 비용이 많이 드는 작업, 또는 클라이언트 연결 끊김에도 실행되어야 하는 워크로드 등이 있습니다. 다만, 비동기 작업에는 추가적인 상태 관리가 필요합니다. 작업 상태, 체크포인트, 멱등성 키, 취소, 결과 저장, 재시도 권한 관리 등이 포함됩니다.

8단계: 실제 부하 조건에서 수정 사항을 검증합니다.

하나의 요청이 성공했다고 해서 문제가 해결되었다고 단정할 수는 없습니다. 실제 운영 환경에서 예상되는 동시 접속률로 테스트를 진행하고 성공률, 타임아웃률, 논리적 작업당 재시도 횟수, p95 및 p99 지연 시간, 큐 지연, 연결 풀 대기 시간, 다운스트림 429/5xx 오류 발생률, 완료된 워크플로당 비용을 측정하십시오.

Kubernetes에서 에이전트를 실행하는 경우, 준비 상태(readiness)와 활성 상태(liveness)는 서로 다른 목적으로 사용됩니다. Kubernetes 문서에 따르면 준비 상태 프로브는 Pod가 트래픽을 수신해야 하는지 여부를 판단하는 메커니즘이며, 활성 상태 프로브는 컨테이너를 재시작해야 하는 시점을 판단하는 메커니즘입니다. 특히 활성 상태 검사를 제대로 구현하지 않으면 부하가 걸린 상태에서 연쇄적인 장애가 발생할 수 있다고 명시적으로 경고합니다. 자세한 내용은 Kubernetes 프로브 공식 문서를 참조하십시오 .

일시적인 과부하의 경우, 정상 작동하는 작업자를 반복적으로 종료하는 것보다 "준비되지 않음" 상태가 되는 것이 더 안전한 경우가 많습니다. 프로세스 재시작이 진정으로 적절한 복구 조치인 경우에만 활성 상태 오류를 처리하십시오.

어떤 해결책이 당신의 실패 패턴에 적합한지 어떻게 알 수 있을까요?

실질적인 생산 기준선

일반적인 다중 에이전트 API의 경우, 견고한 기본 원칙은 모든 워크플로에 상관 관계 ID를 부여하고, 모든 에이전트 및 도구 호출을 추적하고, 하나의 종단 간 마감 시간을 정의하고, 그 안에서 호출별로 더 짧은 마감 시간을 할당하고, 하위 공급자별로 전역 동시 실행 제한을 적용하고, 재시도 횟수를 제한하고 멱등성을 유지하며, 부분 완료를 재개하거나 보고할 수 있도록 충분한 상태를 유지하는 것입니다.

측정값을 기반으로 튜닝하십시오. 시스템이 안정적이지만 속도가 너무 느리면 독립적인 작업을 선택적으로 병렬화하십시오. 부하가 낮을 때는 빠르지만 최대 부하에서 제대로 작동하지 않으면 팬아웃을 줄이고 백프레셔를 추가하십시오. 성공적인 워크플로가 동기식 요청 경로에서 허용하는 시간보다 자연스럽게 더 오래 걸리는 경우, 모든 프록시의 대기 시간을 늘리려고 하기보다는 아키텍처를 변경하십시오.

공식 참고 자료

• OpenAI Python SDK: 재시도 및 시간 초과
• HTTPX: 타임아웃 유형 및 구성
• Python asyncio: 타임아웃 처리
• Python asyncio: 세마포어
• Python asyncio: TaskGroup
• 아마존 API 게이트웨이 HTTP API 할당량
• Kubernetes: 활성 상태, 준비 상태 및 시작 프로브
• OpenAI 응답 API 스트리밍 이벤트