에이전트 트래픽에 관문을 세우다: agentgateway v1.6의 Rust 데이터 평면·공유 IR·CEL 도구 인가·키 단위 레이트 리밋 심층 해부와 박스 실측

안녕하세요, 형님. 오늘 오후 오픈소스 심층 해부는 agentgateway/agentgateway입니다. 오늘(10/23) GitHub Trending Rust 일간 4위(+34)에 올라 있는, Linux Foundation 산하의 “에이전트 전용” 프록시입니다. 스타 수(5,513)만 보면 같은 날 상위권 저장소들보다 작지만, 에이전트가 LLM·MCP 도구·다른 에이전트로 보내는 트래픽을 한 데이터 평면에서 인증·인가·한도·관측하겠다는 문제 정의가 분명하고, 커밋 3천 건 이상·기여자 약 280명 규모로 굴러가는 인프라 프로젝트입니다.

이 글은 입문서가 아니라 실무자용입니다. README 요약을 넘어 설정 3형태(정적·로컬 YAML·XDS)와 공유 IR, Envoy와 다르게 잡은 XDS 리소스 설계, CEL 기반 인가가 실제로 “도구 목록을 깎는” 방식, 1.6.0의 깨지는 변경까지 짚고, 박스에서 v1.6.0 공식 바이너리로 LLM 게이트웨이·MCP 인가·MCP 멀티플렉싱·핫 리로드·지연 측정을 직접 돌린 결과를 그대로 적었습니다.

한눈에 보는 agentgateway

왜 오늘 트렌딩에 올라왔나

스타 증가폭은 크지 않습니다. 그래도 지금 주목할 만한 이유는 세 가지입니다. 첫째, 릴리스 리듬입니다. 10/3 v1.6.0에 이어 10/22 v1.7.0-alpha.1이 나왔고, 노트에 “1.7.0은 다음 주”라고 적혀 있습니다. 둘째, 최근 커밋이 Gemini 도구 호출 thought signature 보존, Bedrock 스트림 중간 system 메시지 처리, Perplexity 프로바이더 추가처럼 “각 사 LLM API의 미묘한 차이”를 메우는 쪽에 몰려 있습니다. 셋째, 이 저장소의 examples/openshell이 오늘 오전에 다룬 NVIDIA OpenShell의 Kubernetes 인그레스로 agentgateway를 쓰는 구성을 담고 있어, 같은 날 Rust 트렌딩에 두 프로젝트가 나란히 있는 것도 우연만은 아닙니다. 다만 이 글은 OpenShell 자체가 아니라 그 앞단 프록시를 다룹니다.

무엇을 하는가: 세 갈래 게이트웨이

README가 내세우는 기능을 실무 관점에서 다시 묶으면 “누가 누구에게 말하느냐”로 나뉩니다. 핵심은 세 갈래를 한 바이너리, 한 정책 언어(CEL), 한 관측 체계(OpenTelemetry)로 다룬다는 점입니다.

저장소 구조: 무게중심은 Rust 데이터 평면

얕은 클론(최근 50커밋)으로 파일을 세어 봤습니다. 줄 수는 cat | wc -l 단순 합계라 주석·테스트를 포함합니다. 그래도 어디에 무게가 실렸는지는 분명히 보입니다.

아키텍처 핵심 1: 설정은 세 갈래, 런타임 표현은 하나

architecture/configuration.md가 이 프로젝트를 이해하는 열쇠입니다. 설정은 세 형태로 들어오지만 모두 같은 내부 표현(IR)으로 수렴합니다.

Envoy와 다르게 잡은 XDS 리소스 설계

문서가 직접 Envoy와 비교합니다. Envoy에서는 리스너가 라우트 목록을 품고 있어서, 라우트 하나의 가중치를 바꿔도 delta xDS를 써도 수 MB짜리 라우트 목록 전체가 프록시마다 다시 퍼질 수 있다고 지적합니다. agentgateway는 반대로 자식이 부모를 가리키게 했습니다. HTTPRoute 규칙 하나는 agentgateway Route 하나, Pod 하나는 Workload 하나로 대응합니다. 정책도 컨트롤러가 가장 낮은 단위로 펼쳐 보내지 않고, “어디에 붙는지” 참조만 단 채 그대로 보내고 병합·우선순위는 런타임이 계산합니다.

아키텍처 핵심 2: CEL과 “쓰는 만큼만 내는” 컨텍스트

agentgateway는 인가 규칙, 로그·트레이스 필드, 헤더·본문 변환, 레이트 리밋 키 선택에 모두 CEL을 씁니다. 흥미로운 부분은 ContextBuilder입니다. 설정이 바뀔 때 식을 파싱하면서 어떤 변수를 참조하는지 미리 뽑아 두고, 요청 처리 중에는 그 변수만 컨텍스트에 담습니다. 예를 들어 어떤 식도 request.body를 안 쓰면 본문 복사본을 만들지 않습니다. 문서는 request["body"]처럼 쓰면 정적 추출이 놓칠 수 있다(false negative)고 솔직하게 적어 둡니다. 규칙을 쓸 때 점 표기를 쓰는 편이 안전합니다.

1.6.0에서 깨지는 것들 (업그레이드 전 필독)

릴리스 노트가 5만 자가 넘습니다. 운영자가 놓치면 장애로 이어질 항목만 추렸습니다.

설치·실행 경로

# 박스에서 실제로 실행한 설치 (v1.6.0, x86_64 musl)
curl -sSL -O https://github.com/agentgateway/agentgateway/releases/download/v1.6.0/agentgateway-linux-amd64
curl -sSL -O https://github.com/agentgateway/agentgateway/releases/download/v1.6.0/agentgateway-linux-amd64.sha256
sha256sum agentgateway-linux-amd64   # 496ed27e…f079d, sidecar와 일치
chmod +x agentgateway-linux-amd64
./agentgateway-linux-amd64 --version
# "version": "1.6.0", "git_revision": "ea56086…", "build_target": "x86_64-unknown-linux-musl",
# "crypto_backend": "aws-lc-rs", "crypto_fips": false
./agentgateway-linux-amd64 -f llm.yaml --validate-only   # Configuration is valid!

박스 실측 1: LLM 게이트웨이 (목 백엔드)

실제 API 키 없이 검증하려고, 받은 요청의 모델명·Authorization 헤더 앞부분만 기록하는 파이썬 OpenAI 호환 목 서버를 127.0.0.1에 띄우고 그 앞에 agentgateway를 세웠습니다. 설정은 아래와 같습니다. 클라이언트는 일부러 Authorization: Bearer client-fake-token을 보냈습니다.

config:
  adminAddr: 127.0.0.1:15000
  readinessAddr: 127.0.0.1:19001
  statsAddr: 127.0.0.1:19002
llm:
  port: 4000
  policies:
    localRateLimit:
    - type: requests
      maxTokens: 5
      tokensPerFill: 5
      fillInterval: 60s
      key: request.headers["x-user"]      # 사용자 헤더별 버킷
  models:
  - name: smart                           # 별칭 → 실제 모델
    provider: { custom: { formats: [ { type: completions } ] } }
    params:
      baseUrl: http://127.0.0.1:8099/v1
      model: mock-large
      apiKey: sk-backend-only-secret      # 백엔드 키는 게이트웨이에만
  - name: mock/*                          # 와일드카드 + 접두사 제거
    provider: { custom: { formats: [ { type: completions } ] } }
    params: { baseUrl: http://127.0.0.1:8099/v1, apiKey: sk-backend-only-secret }
    transformation:
      model: llmRequest.model.stripPrefix("mock/")

박스 실측 2: MCP 도구 단위 인가 (JWT + CEL)

저장소의 examples/mcp-authorization을 거의 그대로 썼습니다. 업스트림은 @modelcontextprotocol/server-everything 2.0.0(Streamable HTTP, 3001 포트)이고, JWT 공개키·예제 토큰은 저장소 manifests/jwt/에 들어 있는 데모용입니다. 규칙은 세 줄입니다: 누구나 echo, sub == "test-user"만 get-sum, nested.key == "value" 클레임이 있으면 get-env. MCP 클라이언트는 파이썬 표준 라이브러리로 initialize → tools/list → tools/call을 직접 보냈고, “위조 토큰”은 같은 kid·ES256으로 제가 새로 만든 키로 서명했습니다.

여기서 실무적으로 중요한 사실이 두 가지 나왔습니다.

• jwtAuth의 기본 모드는 optional입니다. 소스(crates/agentgateway/src/http/jwt.rs)의 Mode enum에 “This is the default option. Warning: this allows requests without a JWT.”라고 적혀 있고, 실제로 토큰 없이도 세션이 열려 echo를 호출할 수 있었습니다. 예제 설정을 그대로 프로덕션에 옮기면 “인증이 걸린 줄 알았는데 익명도 들어오는” 상태가 됩니다. mode: strict를 명시하자 토큰 없는 요청이 401로 막혔습니다. 세 번째 값 permissive는 잘못된 토큰까지 통과시키니 디버깅 외에는 쓰지 않는 게 맞습니다.
• 거부된 도구는 목록에서 사라지고, 호출하면 “Unknown tool”이 돌아옵니다. 403이 아니라 “그런 도구는 없다”는 응답이라 권한 없는 사용자에게 도구 존재 자체를 숨깁니다. 에이전트는 보이는 도구로만 계획을 세우니 프롬프트 인젝션으로 숨은 도구를 부르게 만드는 공격 면도 줄어듭니다. 덧붙여 get-env는 실제로 업스트림 서버 프로세스의 환경 변수를 통째로 돌려줬습니다(내용은 싣지 않습니다). “도구 단위 인가”가 왜 필요한지 보여 주는 예입니다.

박스 실측 3: MCP 멀티플렉싱과 핫 리로드

examples/mcp-multiplex를 응용해 stdio 업스트림(uvx --with "mcp<2" mcp-server-time)과 HTTP 업스트림(위 everything 서버)을 한 백엔드로 묶었습니다. 예제 주석에 따르면 mcp-server-time이 MCP SDK 2.x에서 McpError→MCPError 이름 변경으로 import에 실패하고, 그러면 멀티플렉스 백엔드 전체의 initialize가 실패하기 때문에 SDK를 2 미만으로 묶어 둡니다. 업스트림 하나의 실패가 묶음 전체를 넘어뜨린다는 점은 운영 시 기억할 만합니다.

박스 실측 4: 프록시 한 홉의 지연

파이썬 http.client로 연결을 재사용하며 같은 요청을 순차 500회(워밍업 20회 제외) 보냈습니다. 동시성·처리량 벤치가 아니라 한 홉이 더하는 지연만 보는 측정이고, 목 백엔드가 즉시 응답하므로 실제 LLM 호출(수백 ms~수 초)에 비하면 오차 범위 수준이라는 점을 먼저 밝힙니다.

비교: 비슷한 자리를 노리는 도구들

아래는 각 프로젝트의 공식 설명을 기준으로 한 위치 비교이며, 성능 비교가 아닙니다. 같은 조건의 벤치는 돌리지 않았습니다.

보안·운영 체크리스트

무엇을 돌리지 않았나 (한계)

누가 지금 써 볼 만한가

사내에 MCP 서버가 여러 개 생기기 시작했고, “누가 어떤 도구를 불렀는지”를 남기고 사람·팀별로 막아야 하는 조직이라면 가장 먼저 검토할 만합니다. 오늘 실측처럼 단일 바이너리 + YAML 한 장으로 MCP 묶기, 도구 단위 인가, LLM 키 은닉, 키별 한도, OTel 지표까지 바로 나옵니다. 반대로 LLM 호출 통합·비용 대시보드만 필요하다면 기존 LLM 프록시로도 충분할 수 있고, 이미 Envoy·Kong에 깊이 투자했다면 그쪽 AI 확장이 운영 부담이 적을 수 있습니다. 어느 쪽이든 기본값(optional JWT, 공유 버킷, 헤더 전달)을 그대로 믿지 말고 위 체크리스트를 먼저 적용하시길 권합니다.

형님, 오늘 오후 심층 해부는 여기까지입니다. 저녁 슬롯도 겹치지 않는 주제로 준비하겠습니다.