AgentCore gateway 레이트 리밋 구성

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

AgentCore gateway에 레이트 리밋을 적용하면 요청(RPS/RPM), 토큰(TPM), 연결(CPS) 기반으로 사용자와 대상별 트래픽을 세밀하게 제어할 수 있다. 차원 키(targetName, toolName, qualifiedModelId, JWT 클레임 등)를 조합해 엔트리 단위로 허용량을 할당하며, 사전 토큰 추정 후 모델 제공자 보고량으로 정산하는 TPM 정산 흐름을 포함한다. 그룹 수준과 사용자 수준을 결합한 이중 한도는 공정성 확보와 백엔드 보호를 동시에 달성하며, 에이전트의 인증 방식(OBO vs M2M)에 따라 적용 주체가 달라지므로 에이전트별 한도도 설계해야 한다.

섹션별 상세

AgentCore gateway는 단일 진입점에서 AI 트래픽을 라우팅하고 중앙에서 트래픽 관리를 제공하며, 레이트 리밋은 이 진입점에 사용자·대상·모델 기준의 세밀한 제어를 추가한다. 구현은 요청 기반(RPS/RPM), 토큰 기반(TPM, 추론 전후 정산), 연결 기반(CPS) 세 가지 지표를 모두 지원하며 각각 다른 보호 목적을 가진다. 운영 관점에서 이 구조는 스트리밍 호출이나 토큰 집약형 모델이 백엔드를 고갈시키는 것을 방지해 서비스 가용성을 유지한다.

차원 키와 엔트리 구조는 요청을 어떤 버킷으로 매핑할지 결정하는 핵심 메커니즘이다. 차원 키는 요청 컨텍스트의 필드값(targetName, toolName, qualifiedModelId, JWT 클레임 등)을 조합해 고유한 키를 만들고, 엔트리는 그 조합에 대응하는 허용량을 정의한다. 이 방식은 특정 모델이나 도구, 또는 사용자 그룹별로 전용 제한을 부여해 공정한 자원 분배와 백엔드 보호를 동시에 달성한다.

토큰 한도는 추론 대상에만 적용되며 요청의 입력·출력 토큰을 모두 고려한다. 게이트웨이는 사전 토큰 추정을 통해 호출 전에 한도를 차감하고, 응답에서 모델 제공자가 보고한 실제 토큰 사용량으로 정산하는 보정 과정을 거친다. 이 전후 정산 메커니즘은 과도한 동시 호출이나 토큰 폭주로 인한 초과 소비를 사전에 억제하면서 실제 비용과 사용량의 일치성을 확보한다.

그룹 수준과 사용자 수준의 이중 레이트 리밋 설계는 공정성 확보를 목표로 한다. 그룹 레벨은 전체 그룹이 소비할 수 있는 상한을 정해 한 그룹이 다른 그룹을 제압하지 못하도록 하고, 사용자 레벨은 동일 그룹 내에서 한 개인이 버킷 전체를 소진하는 것을 막는다. 두 한도는 AND 논리로 독립 평가되며 어느 하나라도 초과하면 요청이 거부되어 자원 과소모를 방지한다.

대상(target)-기반 한도는 특정 백엔드 또는 모델의 보호에 초점을 두며, qualifiedModelId나 toolName을 차원으로 사용해 모델별 TPM 또는 도구별 RPS/CPS를 설정할 수 있다. 단, targetName만 사용하는 한도는 모든 호출자가 동일한 한도를 공유하므로 일부 그룹의 집중 트래픽으로 인해 다른 사용자들이 고갈될 위험이 있다. 이 경우 identity 차원을 결합하면(예: ["targetName","$.context.jwt.role"]) 특정 그룹이나 사용자에 대해 별도 한도를 부여할 수 있다.

Agent(에이전트)가 하위 리소스를 호출할 때 인증 방식에 따라 레이트 리밋의 적용 주체가 달라진다. 사용자의 JWT를 바탕으로 OBO 토큰을 이용하면 하위 호출은 원래 사용자의 신원을 유지하므로 기존 사용자 기반 한도가 그대로 적용된다. 반면 에이전트가 클라이언트 자격 증명으로 자체 토큰을 발급받으면 하위 호출은 에이전트 신원으로 분류되므로 에이전트별 한도를 별도로 설정해 자원 고갈을 막아야 한다.

이미지 분석

Diagram
이 다이어그램은 사용자 그룹(Basic·Advanced·Beta), AgentCore Identity와 Policy, 그리고 MCP·inference·HTTP 타깃으로의 라우팅 관계를 시각적으로 정리한다. 각 그룹에 대해 다른 역할 기반 접근과 레이트 리밋을 적용하는 흐름을 한눈에 확인할 수 있어 정책 설계와 차원 키 선택에 도움을 준다. 실무에서는 이 구조를 보고 어떤 차원으로 버킷을 분리할지, OBO 토큰 사용 여부에 따른 하위 호출 신원 처리를 결정할 수 있다.
AgentCore gateway 아키텍처 다이어그램

Screenshot
코드 스니펫 이미지로 targetName을 차원 키로 사용하는 예시를 보여준다. Booking 대상에 대해 100 RPS를 명시하고 나머지 대상에는 각각 10 RPS의 독립 버킷을 할당하는 구성을 시각적으로 확인할 수 있어 차원 키와 와일드카드 동작을 이해하는 데 유용하다. 운영자는 이 예를 바탕으로 고트래픽 대상에 특화된 예외를 적용하거나 전체 보호를 위한 기본 와일드카드를 함께 설정하면 된다.
레이트 리밋 엔트리 예시(Booking 대상과 와일드카드)

Diagram
AWS Documentation Agent를 예로 들어 에이전트가 Docs MCP와 BedrockMantle 모델을 순차적으로 호출하는 흐름을 보여준다. 이미지에서는 에이전트의 인증 방식(OBO 또는 기계계정)에 따라 어떤 주체의 레이트 리밋이 적용되는지가 핵심이며, 이를 통해 에이전트별 한도 설정의 필요성을 명확히 알 수 있다. 에이전트를 운용하는 팀은 이 구조를 참조해 에이전트 신원에 대한 별도 레이트 리밋을 설계해야 한다.
에이전트 호출 시 다운스트림 리소스 소비 관계

용어 해설

차원 키(Dimension keys): — 차원 키는 들어오는 요청을 서로 다른 레이트 버킷으로 그룹화하는 식별자이다. 요청 컨텍스트에서 targetName, toolName, qualifiedModelId, JWT 클레임 같은 값을 추출해 조합을 만들며, 이 조합을 기준으로 각 요청의 허용량을 결정한다.
분당 토큰 한도(Tokens per minute (TPM)): — TPM은 추론 대상에 대해 입력 토큰과 출력 토큰의 전체 비용을 분 단위로 제한하는 지표이다. 게이트웨이는 사전 추정으로 토큰을 차감하고 모델 제공자가 반환한 실제 사용량으로 한도를 정산한다.
초당 연결 한도(Connections per second (CPS)): — CPS는 각 요청이 유지하는 동시 연결 수를 측정해 장시간 스트리밍 호출로 인한 동시 세션 과부하를 막는다. 스트리밍이 길면 해당 요청은 완료될 때까지 연결 슬롯을 계속 차지한다.
대리 인증 토큰(On-behalf-of token (OBO)): — OBO 토큰은 사용자의 JWT로부터 게이트웨이가 교환해 발급하는 토큰으로, 하위 리소스에 사용자 신원을 유지한 채 요청을 전달한다. 이 경우 사용자 기준의 레이트 리밋이 하위 호출에 그대로 적용된다.

코드 예제

bash

aws bedrock-agentcore-control create-gateway-rate-limit \
  --gateway-identifier my-gateway-abc1234567 \
  --dimension-keys '["targetName"]' \
  --description "Per-target RPS limit" \
  --entries '[
    {"dimensions":{"targetName":"Booking"},"requests":[{"rate":100,"period":"second"}]},
    {"dimensions":{"targetName":"*"},"requests":[{"rate":10,"period":"second"}]}
  ]'

이 AWS CLI 스니펫은 targetName을 차원으로 하는 게이트웨이 레이트 리밋을 생성하는 예시이다. 첫 번째 엔트리는 Booking 대상에 대해 초당 100 요청을 허용하고, 두 번째 와일드카드 엔트리는 나머지 각 대상에 대해 개별적으로 초당 10 요청 버킷을 할당한다. 이 구조는 특정 고트래픽 대상에 높은 허용치를 주면서 다른 대상은 독립된 저용량 버킷으로 보호하려는 운영 시나리오에 적합하다.

근거 모음

근거

토큰 기반(TPM) 한도는 입력과 출력 토큰의 전체 왕복 비용을 사전에 차감하고, 모델 제공자가 반환한 실제 사용량으로 정산한다. — 본문 'Token rate limits' 단락에서 게이트웨이가 토크나이저로 사전 추정해 차감하고 응답에서 실제 사용량으로 정산한다고 명시된 문장.
그룹 수준과 사용자 수준의 레이트 리밋은 AND 논리로 독립 평가되며 어느 하나라도 초과하면 요청이 거부된다. — 본문의 예시에서 그룹 레벨(예: Basic 100 RPM)과 사용자 레벨(예: Basic 사용자당 20 RPM)을 함께 적용한 후 둘 다 통과해야 한다고 설명된 부분.
차원 키의 와일드카드 '*'은 트레일링 위치에서만 허용되며, 와일드카드가 위치 N에 있으면 이후 모든 위치도 '*'이어야 한다. — 본문의 'catch all default *'와 차원 키 순서 규칙에 대한 설명과 trailing-only 제약 문단.

기술

AWS CLI
AgentCore gateway
AgentCore Identity
AgentCore Policy
Microsoft Entra ID
OpenTelemetry
BedrockMantle

활용 사례

다중 사용자 환경에서 역할별·사용자별 공정 사용 제한을 적용해 자원 분배를 보장하는 운영
고토큰 소비 모델을 모델별 TPM으로 제한하여 비용 과다 발생을 통제하는 경우
스트리밍 중심 워크로드에서 CPS를 설정해 동시 연결로 인한 백엔드 과부하를 방지하는 시나리오

AgentCore gateway 레이트 리밋 구성

TL;DR

섹션별 상세

이미지 분석

용어 해설

코드 예제

근거 모음

기술

활용 사례

관련 토론

댓글

관련 기사

Agent Access Model(작업 기반 에이전트 권한 모델)

LLM 호출 전 부하를 차단하는 비동기 벌크헤드

Ollama-gateway: Ollama 서버 앞에 두는 셀프호스티드 인증·쿼터·포워딩 게이트웨이

TokenShield 업데이트로 CrewAI 에이전트의 재시도 루프에서 토큰 폭주를 네트워크 레이어에서 차단함

한 달 동안 고객지원 에이전트의 총이익률이 약 60%인 줄 알았다가 실제로 적자로 전환된 경험