Originally published on tamiz.pro.
에이전트 플릿(Agent fleets)은 특이하게 실패합니다. 데모에서는 완벽하게 작동하지만, 실제 프로덕션 트래픽을 받으면 무너집니다. 코드는 합리적으로 보입니다. 들어오는 요청 하나하나, 문서 청크 하나하나, 서브 에이전트 하나하나에 대해 태스크를 생성합니다. 각 태스크는 모델을 호출하고, 실패 시 재시도하며, 도구(tool)를 기다리고, 더 많은 작업을 생성합니다. 처리량(Throughput)은 상승하다가 결국 무언가가 포화 상태에 이릅니다: 연결 풀(connection pools), 속도 제한(rate limits), 메모리, 월별 예산, 또는 제공업체(provider)의 서비스 의지입니다.
해결책은 에이전트를 더 빠르게 만드는 것이 아닙니다. 동시성(concurrency)을 애플리케이션 로직에서 발생하는 부수적인 효과가 아니라 **제한된 자원(bounded resource)**으로 만드는 것입니다. 제한된 워커 풀(bounded worker pool)은 2026년 시대 에이전트 인프라의 핵심 원시 요소입니다. 이는 용량이 존재할 때만 작업을 수용하고, 용량이 없을 때는 백프레셔(backpressure)를 적용하며, 다운스트림 시스템을 녹이는 대신 의도적으로 부하를 줄여나가는 고정적이거나 탄력적인 용량 예산입니다.
이 가이드는 API 표면 아래로 들어갑니다. 우리는 에이전트 실행을 큐-및-워커(queue-and-worker) 시스템으로 모델링하고, 팬아웃(fan-out)과 팬인(fan-in)을 분리하며, 적응형 동시성 제어(adaptive concurrency control)를 구현하고, 에이전트 플릿을 프로덕션에서 운영하는 데 필요한 관측 가능성(observability) 및 실패 의미론(failure semantics)을 추가할 것입니다.
목차 (Table of Contents)
-
- 동시성의 폭발 (The Concurrency Explosion)
-
- 핵심 아키텍처: 큐, 워커, 어댑터 (Core Architecture: Queues, Workers, and Adapters)
-
- 제한된 워커 풀 구축하기 (Building a Bounded Worker Pool)
-
- 백프레셔: 가장 중요한 빠진 조각 (Backpressure: The Most Important Missing Piece)
-
- 적응형 동시성: 올바른 한계 찾기 (Adaptive Concurrency: Finding the Right Limit)
-
- 서킷 브레이커, 재시도, 데드 레터 큐 (Circuit Breakers, Retries, and Dead Letter Queues)
-
- 팬아웃, 팬인, 그리고 다중 에이전트 구조 (Fan-Out, Fan-In, and the Multi-Agent Shape)
-
- 관측 가능성: 볼 수 없는 것은 튜닝할 수 없다 (Observability: You Cannot Tune What You Cannot See)
-
- 비용 및 예산 제어 (Cost and Budget Control)
-
- 프로덕션 배포 패턴 (Production Deployment Patterns)
-
- 에이전트 플릿 테스트하기 (Testing Agent Fleets)
-
- 안티패턴과 그 대체재 (Anti-Patterns and Their Replacements)
-
- 아키텍처 결정 가이드 (Architecture Decision Guide)
- 자주 묻는 질문 (Frequently Asked Questions)
1. 동시성의 폭발 (The Concurrency Explosion)
겉보기에는 무해한 문서 분석 파이프라인을 가정해 봅시다:
async def process_document(doc):
chunks = await chunk_document(doc)
results = await asyncio.gather(*[
...
하나의 문서가 500개의 청크를 포함할 수 있습니다. 열 번의 동시 업로드는 5,000번의 동시 모델 호출을 생성합니다. asyncio.gather 호출은 병렬성(parallelism)을 생성하는 것이 아니라, 이벤트 루프와 HTTP 클라이언트가 허용하는 한 최대한 빨리 실행되려고 시도할 5,000개의 보류 중인 코루틴(pending coroutines)을 만듭니다.
이 패턴에는 세 가지 명확한 문제가 있습니다.
첫째, 다운스트림 제한 사항이 모델링되지 않습니다. 모델 제공업체는 분당 토큰 수(TPM), 분당 요청 수(RPM), 그리고 동시성 상한선을 강제합니다. 이 한계를 초과하면 429 응답을 받거나, 지연 시간이 급증하거나, 계정 수준의 스로틀링이 발생합니다. 애플리케이션은 이러한 제한을 표현할 방법이 없으므로, 실패를 통해서만 이를 발견하게 됩니다.
둘째, 재시도가 부하를 증폭시킵니다. 5,000개의 작업에 걸친 세 번의 시도 정책은 최대 15,000개의 요청을 의미합니다. 재시도는 고립된 상황에서는 올바르지만, 이미 과부하가 걸린 시스템에 적용될 경우 출력을 지연시키는 '재시도 폭풍(retry storm)'을 만듭니다.
셋째, 메모리와 테일 레이턴시(tail latency)가 비선형적으로 저하됩니다. 보류 중인 각 작업은 프롬프트, 파싱된 응답, 그리고 중간 상태를 유지합니다. 백만 개의 대기 항목은 메모리상의 백만 개 객체이며, 완료하는 마지막 항목은 전체 큐 뒤에 기다려야 합니다.
아키텍처적 실수는 동시성을 워크로드 크기의 결과로 취급하는 것입니다. 동시성은 데이터베이스 연결이나 워커 스레드처럼 할당해야 하는 리소스여야 합니다.
정신 모델: 에이전트 플릿을 대기열 시스템으로 간주하기
에이전트 플릿은 '서버'가 알 수 없고 가변적인 용량을 가진 LLM API인 분산형 대기열 시스템(distributed queueing system)입니다. 고전적인 대기열 이론(Classical queueing theory)은 우리에게 다음과 같은 어휘를 제공합니다:
| Concept | Agent fleet equivalent |
|---|
| Arrival rate (λ) | 초당 제출되는 요청 수 (Requests submitted per second) |
| ... | |
| 핵심 통찰: 도착률(arrival rate, λ)이 서비스율(service rate)을 초과하면, 아무리 많은 동시성(concurrency)을 확보해도 도움이 되지 않습니다. 제공자가 이미 포화 상태일 때 워커를 추가하는 것은 단순히 큐(queue)의 위치만 옮길 뿐입니다. 여러분의 임무는 활용률(utilization)을 1 미만으로 유지하고, 큐 경계(queue boundary)를 명시적으로 만드는 것입니다. | |
워커 풀은 성능 최적화 수단이 아닙니다. 그것은 한 번에 얼마나 많은 작업이 진행될 수 있는지, 그리고 그 계약이 지켜지지 않을 때 무슨 일이 발생하는지에 대한 '규약'입니다.
2. 핵심 아키텍처: 큐(Queues), 워커(Workers), 어댑터(Adapters)
프로덕션 에이전트 플릿은 데모에서 흔히 혼동되는 세 가지 관심사(concerns)를 분리합니다:
- 작업 소스 (The work source): 작업 디스크립터(task descriptors)를 생성합니다. 무엇을 해야 하는지(what)는 알지만, 얼마나 많은 작업을 동시에 실행할 수 있는지(how much)는 모릅니다.
- 스케줄러/풀 (The scheduler/pool): 동시성 예산(concurrency budget)을 소유합니다. 언제 작업이 시작될지(when)를 결정합니다.
- 실행기 (The executor): 실제 에이전트 실행(agent run)을 수행합니다. 여기에는 모델 호출(model calls), 도구 호출(tool invocations), 재시도(retries) 등이 포함됩니다.
이러한 분리는 메모리 내 큐를 Redis, SQS 또는 Kafka로 교체해도 에이전트 로직을 건드릴 필요가 없게 만듭니다. 또한 서로 다른 리소스 유형에 대해 다른 제한을 적용할 수 있게 합니다. LLM을 호출하는 플릿과 샌드박스(sandbox)로 작업을 위임하는 플릿은 완전히 다른 용량 특성(capacity characteristics)을 가집니다.
작업 계약 정의하기 (Defining the task contract)
타입이 지정되고 직렬화 가능한(serializable) 작업 디스크립터로 시작해야 합니다. 큐를 통해 라이브 코루틴(live coroutines)이나 열린 연결(open connections)을 전달해서는 안 됩니다.
from dataclasses import dataclass, field
from typing import Any, Literal
...
여기서 두 가지 세부 사항이 중요합니다. max_attempts와 timeout_s는 작업과 함께 이동하여 실행기의 동작을 결정론적(deterministic)이고 재현 가능하게 만듭니다. cost_limit_usd 필드는 예산 내에서 성공할 수 없는 작업을 사후에 초과 사용량을 발견하는 대신, 풀(pool)이 미리 거부하도록 합니다.
풀(Pool)을 실행기(Executor)와 분리하기 (Separating the pool from the executor)
풀은 LLM에 대해서는 아무것도 알지 못해야 합니다. 이는 콜러블(callables)을 수락하므로, 사소한 함수로 테스트할 수도 있고 모든 종류의 동시 작업에 사용할 수도 있습니다.
이 구현은 의도적으로 단순하며, 일반적인 경우에 대해서는 정확합니다. 하지만 아직 수행하지 않는 두 가지 사항이 있습니다: 호출자에게 결과를 반환하지 않으며, 속도 제한(rate limits)이나 회로 차단기(circuit breakers)를 적용하지 않습니다. 이 부분들은 추가할 것입니다.
세마포어만으로는 충분하지 않은 이유
다음과 같이 작성하고 싶은 유혹을 느낄 수 있습니다:
sem = asyncio.Semaphore(20)
async def guarded(task):
...
이것은 동시성(concurrency)을 제한하며, 무제한적인 확산(unbounded fan-out)보다는 낫습니다. 하지만 여전히 세 가지 이유로 워커 풀이라고 할 수 없습니다.
- 경계가 있는 큐(No bounded queue). 호출자는 여전히 모든 작업을 미리 생성합니다. 10만 개의 작업을 제출하면, 각 페이로드(payload)를 담고 있는 10만 개의 작업이 메모리에 존재하게 됩니다. 세마포어는 '실행'을 제한할 뿐, '진입(admission)'을 제한하지 않습니다.
- 자연스러운 우선순위 또는 순서 지정 불가. 우선순위를 위해서는 세마포어가 아니라 우선순위 큐(priority queue)나 스케줄러가 필요합니다.
- 생명 주기 관리 부재(No lifecycle). 깨끗한 시작(start), 비우기(drain), 또는 종료 경로가 없으며, 풀 수준의 메트릭을 연결할 장소도 없습니다.
세마포어 패턴은 수백 개의 항목에 대한 경계가 있는 확산에는 적합합니다. 플릿(fleet)의 경우, 명시적인 큐와 워커를 사용해야 합니다.
3. 경계가 있는 워커 풀 구축하기
결과를 반환하고, 우선순위를 지원하며, 정확한 메트릭을 노출하는 풀을 만들어 봅시다. 이것이 실제로 배포할 버전입니다.
import asyncio
import heapq
import itertools
...