⏲️

AI Agents Platform via kagent, agentgateway

Introduction

엔터프라이즈/서버 환경에서의 AI Agent 운용은 local 환경 대비 하기 요구에 응할 수 있는 장점을 가진다.

•

접근성: 내부 서비스, Kubernetes 리소스 등의 엔터프라이즈 자원에 안정적으로 접근할 수 있어야 한다.

•

통제성: 엔터프라이즈 자원 접근으로 인해 자격 증명, 승인된 도구, 정책, 감사 로그가 요구된다.

•

지속성: 사용자 세션이나 노트북 상태와 무관하게 Agent가 계속 실행되어야 한다.

•

공유성: 팀과 시스템이 공통으로 접근 가능해야 한다.

이는 자연스럽게 도구 연결, 실행 환경, 보안, 운영 모델의 강조로 이어진다. 즉, agent 수가 늘어나고, 연결 대상 시스템이 많아짐으로 문제는 Agent를 만들 수 있는가가 아닌 Agent를 운영 가능한 시스템으로 만들 수 있는가로 바뀐다.

kagent와 agentgateway는 이 문제에 대한 Kubernetes 맥락에서의 해결책으로, 본 문서는 kagent의 구성요소인 kmcp를 포함하여 개발자와 운영자 관점에서 정리한다.

•

kagent: Agent와 MCP를 포함한 tool을 Kubernetes에서 운영 가능한 리소스로 만드는 플랫폼

•

agentgateway: Runtime Agent 트래픽을 통제 가능한 구조로 만드는 게이트웨이

AI Agent 요구사항: kagent, agentgateway features

kgagent, agentgateway가 다루는 agent는 Kubernetes의 마이크로서비스(first-class citizen)임과 동시에, 다수의 자원 접근과 지능적 실행 특성으로 인한 부가적 요구사항을 갖는다.

다음은 kagent, agentgateway가 대응하는 Kubernetes에서의 AI agent 요구사항이다.

Kubernetes 기반 서비스 운영 모델과의 정합성

•

Kubernetes 네이티브 운영: Agent도 일반 마이크로서비스처럼 스케줄링, 확장, 격리, 네트워킹, 정책 적용의 대상이 되어야 한다.

•

선언형 배포 / 수명주기 관리: Agent 역시 일반 마이크로서비스와 마찬가지로 Kubernetes/GitOps 친화적인 선언형 모델이 되어야 한다.

kagent, agentgateway는 공통적으로 위 요구사항에 대응한다.

AI Agent 플랫폼 전용 요구 사항

•

다수 Agent의 일관된 운영 관리: 여러 Agent를 동일한 방식으로 배포, 갱신, 권한 부여, 정책 적용, 관측할 수 있어야 한다.

•

선언형부터 BYO까지의 Agent 작성 모델: 플랫폼은 prompt 기반의 간단한 선언만으로 Agent를 생성할 수 있어야 하며, 필요 시 사용자 코드나 프레임워크를 가져오는 BYO(Bring Your Own) 방식으로 확장할 수 있어야 한다.

•

멀티 Agent 협업 / 위임 모델: 단일 Agent를 넘어서 여러 Agent가 서로 역할을 나누고 호출하며 협업할 수 있어야 한다.

•

상태 지속성 / 장기 실행 내구성: Agent는 세션, task 상태, 재시도, 복구를 다뤄야 하므로 사용자 세션과 분리된 상태 지속성과 실행 내구성이 필요하다.

•

재사용 가능한 tool 제공 모델: 각 Agent가 로컬 MCP 서버를 개별 내장하기보다, MCP / Tool Server를 공용 서비스로 분리해 재사용, 버전 관리, 보안 통제가 가능해야 한다.

•

Human-in-the-loop 실행 제어: Agent 실행 중 특정 단계에서 사용자 승인, 보류, 재개 같은 개입이 가능해야 한다.

위 요구사항은 kagent가 대응하며,

•

A2A / MCP / LLM 통합 접근 계층: Agent-to-Agent, Agent-to-Tool, Agent-to-LLM 호출을 개별 Agent 구현이 아니라 공통 접근 계층에서 일관되게 중재할 수 있어야 한다.

•

MCP 세션 상태의 연속성 보장: client-facing 세션과 backend MCP server 세션 사이의 상태 연속성을 유지할 수 있어야 한다.

•

MCP server 통합 / Multiplexing: 여러 MCP server를 개별 endpoint로 직접 다루기보다, 하나의 접근 계층으로 묶고 tool 목록 통합, 이름 충돌 회피, target별 라우팅을 처리할 수 있어야 한다.

•

인증/인가 및 정책 거버넌스: namespace 단위 데이터 경계, Gateway/Route별 조직 정책, 사용자 토큰의 안전한 권한 위임, Secret 기반 자격 증명 관리를 중앙에서 일관되게 집행할 수 있어야 한다.

•

관찰성 및 감사(audit): 어떤 Agent가 어떤 tool과 LLM을 어떤 경로와 정책 아래 호출했는지 추적 가능해야 한다.

•

프롬프트 / 응답 수준의 런타임 통제: Agent-to-LLM 호출에서는 단순 인증/인가를 넘어, 프롬프트와 응답 내용을 검사하고 필요 시 mask 또는 reject 할 수 있는 guardrail 계층이 필요하다.

위 요구사항은 agentgateway가 대응한다.

kagent, agentgateway 기반 AI Agent 플랫폼 Architecture

graph TD
    User((<b>User / Operator</b>))
    KagentCLI["<b>kagent CLI</b><br/><i>Client</i>"]
    LLM["<b>LLM</b><br/>(ChatGPT, Gemini, Claude, etc.)"]

    subgraph K8s["Kubernetes Cluster"]
        direction TB

        AGController["<b>agentgateway-controller</b><br/><i>1 Deployment</i>"]
        KagentUI["<b>kagent-ui</b><br/><i>1 Deployment</i>"]
        subgraph KagentCPGroup[" "]
            direction TB
            KagentCtrl["<b>kagent-controller</b><br/><i>1 Deployment</i>"]
            KMCP["<b>kmcp-controller</b><br/><i>1 Deployment</i>"]
        end

        Agent["<b>Agent</b><br/><i>1..N Deployments</i>"]
        MCPServer["<b>MCP / Tool Server</b><br/><i>1..N Deployments</i>"]
        AG["<b>agentgateway</b><br/><i>1..N Deployments</i><br/><i>(one per Gateway)</i>"]

        Service["<b>Service</b><br/><i>Workloads</i>"]
    end

    %% Control Plane Logic
    KagentUI <-->|User Interaction / Manage| KagentCPGroup
    KagentCLI <-->|User Interaction / Manage| KagentCPGroup
    KagentCtrl -->|"Tool Discovery<br/>(streamable HTTP or SSE)"| MCPServer
    KagentCtrl <-->|"User Interaction / Manage"| Agent
    AGController -.->|"Program Config / Policy"| AG
    KMCP -.->|Manage| MCPServer


    %% User flow
    User -->|"- User Interaction<br/>- Manage (Operator)"| KagentCLI
    User -->|"- User Interaction<br/>- Manage (Operator)"| KagentUI
    User -.->|"Manage via Agent / MCP CRDs (Operator)"| KagentCPGroup
    User -.->|"Manage via Gateway API / CRDs (Operator)"| AGController

    %% Traffic Flows via `agentgateway`
    Agent <-->|A2A / MCP / LLM Traffic| AG
    AG -->|Routing / Policy Enforcement| MCPServer
    AG -->|Unified API / Guardrail| LLM

    %% Execution
    MCPServer -->|API Call| Service

    %% 스타일 정의
    classDef external fill:#eceff1,stroke:#90a4ae,stroke-width:2px,color:#37474f
    classDef actor_user fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#1b5e20,font-size:18px
    classDef actor_operator fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#0d47a1,font-size:18px
    classDef external_llm fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#0d47a1,font-size:16px

    %% [그룹 1] `kagent / kmcp` 라인 (보라 계열)
    classDef highlight_kagent fill:#6200ee,stroke:#3700b3,stroke-width:4px,color:#fff
    classDef highlight_kagentUI fill:#8200ee,stroke:#5700b3,stroke-width:4px,color:#fff
    classDef runtime_kagent fill:#f3e5f5,stroke:#7e57c2,stroke-width:2px,color:#311b92

    %% [그룹 2] `agentgateway` 라인 (오렌지 계열)
    classDef highlight_ag fill:#ff6d00,stroke:#e65100,stroke-width:4px,color:#fff
    classDef control_kgateway fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#e65100

    %% 기타
    classDef backend fill:#ffffff,stroke:#c2185b,stroke-width:1px,color:#880e4f

    %% 서브그래프 스타일
    style K8s fill:#f8f9fa,stroke:#37474f,stroke-width:2px,stroke-dasharray: 5 5
    style KagentCPGroup fill:none,stroke:#7e57c2,stroke-width:2px,stroke-dasharray: 5 5

    %% 클래스 적용
    class LLM external_llm
    class User actor_user
    class KagentUI,KagentCtrl,KMCP,KagentCLI runtime_kagent
    class Agent highlight_kagent
    class MCPServer highlight_kagentUI
    class AGController control_kgateway
    class AG highlight_ag
    class Service backend
Mermaid
복사
Figure 1. kagent / agentgateway 기반 AI Agent Platform 전체 구조

컴포넌트 간 통신 프로토콜, 접근 방식

상기 Architecture에 담긴 link label에 대한 설명이다.

•

User Interaction: 사용자 상호작용 경로로, A2A와 HTTP API를 사용

•

Manage: 운영자가 선언형 리소스를 관리하는 경로로, Kubernetes API / CRDs / Gateway API를 사용

•

Tool Discovery: MCP tools/list를 통해 tool 메타데이터를 수집하는 경로로, streamable HTTP 또는 SSE를 사용

•

Program Config / Policy: control plane이 data plane에 라우팅과 정책 구성을 배포하는 경로로, xDS를 사용

•

A2A / MCP / LLM Traffic: agent 실행 중 발생하는 runtime bizlogic traffic으로, A2A / MCP / LLM provider API를 사용

•

Routing / Policy Enforcement: agentgateway data plane에서 backend routing, authn/z, policy를 inline으로 적용하는 경로로, 주로 MCP over HTTP 계열(예: streamable HTTP / SSE) 또는 backend가 노출한 해당 프로토콜을 사용

•

Unified API / Guardrail: LLM 요청/응답에 대해 공통 API 처리와 콘텐츠 정책 검사를 수행하고, 필요 시 mask 또는 reject 하는 경로로, 주로 OpenAI-compatible HTTP API 또는 provider별 HTTP API를 사용

•

API Call: MCP / Tool Server가 실제 backend service를 호출하는 경로로, 보통 HTTP/HTTPS를 사용

컴포넌트 설명: Client / Interface Layer

컴포넌트	배포 형태	하위 컴포넌트	역할
kagent CLI	External Client	CLI client	Agent 호출과 관리 작업의 진입점. invoke/chat 성격의 요청은 A2A 경로를, 생성/조회/세션/태스크 관리 같은 작업은 일반 HTTP API를 사용
kagent-ui	1 Deployment	Next.js UI	브라우저 기반 사용자/운영자 인터페이스 제공. kagent-controller의 /api 경로를 호출해 Agent 상호작용과 관리 기능 수행

컴포넌트 설명: Controller Layer

컴포넌트	배포 형태	하위 컴포넌트	역할
kagent-controller	1 Deployment	controller-manager	Agent, RemoteMCPServer, 일부 Service, 일부 MCPServer, ModelConfig, ModelProviderConfig를 watch/reconcile하고, Agent 실행 리소스와 tool catalog 상태를 동기화
↑	↑	HTTP server	UI backend, REST API, A2A proxy, MCP proxy 역할 수행. Agent invoke/chat은 A2A 경로로, 관리/조회 계열 요청은 일반 HTTP API로 처리
↑	↑	DB client/cache logic	agents, tool servers, tools, sessions, conversations 메타데이터를 저장·조회하는 읽기 최적화 계층. PostgreSQL을 외부 의존으로 둘 수도 있고, values 설정에 따라 bundled PostgreSQL을 별도 Deployment로 띄울 수도 있음
kmcp-controller	1 Deployment	KMCP controller-manager	MCPServer CR을 watch하고 spec을 해석해 managed MCP server용 Deployment와 필요 시 Service 같은 런타임 리소스를 생성·갱신·삭제하며, MCPServer.status를 반영
agentgateway-controller	1 Deployment	controller-manager / syncer	Gateway API와 AgentgatewayBackend, AgentgatewayPolicy, AgentgatewayParameters 같은 리소스를 watch/reconcile하고, 이를 agentgateway가 이해하는 내부 설정으로 번역
↑	↑	xDS control plane	번역된 라우팅/정책/백엔드 구성을 agentgateway data plane에 배포

컴포넌트 설명: Gateway Layer

컴포넌트	배포 형태	하위 컴포넌트	역할
agentgateway	1..N Deployments, one per Gateway	state manager	xDS 또는 local config를 읽어 현재 gateway 상태를 구성
↑	↑	gateway / proxy listeners	A2A / MCP / LLM runtime traffic을 중재하고, 공통 라우팅, 인증/인가, 트레이싱, 속도 제한, CORS, guardrail, observability 집행
↑	↑	admin / metrics / readiness	운영용 endpoint와 상태 노출

컴포넌트 설명: Agent Layer

•

Agent runtime workloads(1..N Deployments)

◦

kagent-controller가 Agent CR을 보고 동적으로 생성하는 agent runtime
workload

◦

각 agent는 독립된 실행 단위로 배포됨

컴포넌트 설명: Tool Layer

•

Managed MCP server workloads(1..N Deployments)

◦

kmcp-controller가 MCPServer CR을 보고 동적으로 생성하는 MCP server runtime workload.

•

Preinstalled MCP tool servers(1..N Deployments)

◦

선택적으로 함께 배포되는 공용 tool server로 tool을 MCP로 노출

◦

kagent-querydoc: 문서/질의 계열 tool

◦

kagent-grafana-mcp: Grafana/observability 계열 tool

Agent 실행 구조

graph LR
    Dependencies["<b>LLM / Other Agents / MCPServers via agentgateway</b>"]

    Controller["<b>kagent-controller</b><br/><i>/api/a2a/{namespace}/{agent-name}/</i>"]
    DirectClients["<b>LLM / Other Agents via agentgateway</b>"]

    subgraph Agent[" "]
        AgentTitle["<b>Agent</b>: <i>1 Deployment</i>"]

        subgraph A2A["<b>A2A Server</b>"]
            Card["<b>Agent Card</b><br/><i>/.well-known/agent.json</i>"]
            Handler["<b>A2A JSON-RPC Endpoint</b><br/><i>message/send, message/stream</i><br/><i>tasks/*</i>"]
            A2AInfra["<b>Protocol / Security</b><br/><i>HTTP(S), JSON-RPC 2.0, auth</i>"]
        end

        Core["<b>Execution Runtime</b><br/>- Agent Executor<br/>- Session / Memory<br/>- MCP Client / Tool Loop<br/>- Event Conversion / HITL"]
    end

    Controller <-->|A2A discovery / request / response| A2A
    Controller -->|Manage| AgentTitle
    DirectClients <-->|A2A discovery / request / response| A2A
    Handler -.->|Dispatch| Core
    Core -->|Outbound calls| Dependencies

    classDef gateway_path fill:#fff3e0,stroke:#ef6c00,stroke-width:2.5px,color:#6d4c41
    classDef external_dep fill:#fff8e1,stroke:#f9a825,stroke-width:2.5px,color:#6d4c41
    classDef runtime_kagent fill:#f3e5f5,stroke:#7e57c2,stroke-width:2px,color:#311b92
    classDef highlight_kagent fill:#6200ee,stroke:#3700b3,stroke-width:4px,color:#fff
    classDef a2a_box fill:#e3f2fd,stroke:#64b5f6,stroke-width:2px,color:#0d47a1
    classDef a2a_box_alt fill:#d6ecfb,stroke:#42a5f5,stroke-width:2px,color:#0d47a1
    classDef core_box fill:#f5f9fd,stroke:#bbdefb,stroke-width:1.5px,color:#0d47a1
    classDef agent_title fill:none,stroke:none,color:#0d47a1,font-size:16px

    style Agent fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#0d47a1
    style A2A fill:#eef5fc,stroke:#90caf9,stroke-width:1.5px,color:#0d47a1

    class DirectClients gateway_path
    class Dependencies external_dep
    class Controller runtime_kagent
    class AgentTitle agent_title
    class Card a2a_box
    class Handler a2a_box_alt
    class A2AInfra a2a_box
    class Core core_box
Mermaid
복사
Figure 2. kagent agent의 내부 구조 및 타 components와의 연결 구조

kagent의 모든 Agent는 A2A(over HTTP) Agent로서,

•

클러스터 외부(e.g., User / kagent-ui, CLI) 접근: kagent-controller의 Service에 노출을 위임. /api/a2a/{namespace}/{agent-name}/.well-known/agent.json, 8083 port 사용.

◦

참고: kagent-controller는 agent를 MCP 프로토콜로도 노출(공식 문서 링크)

•

클러스터 내부 접근: 각 Agent 자체의 Service 를 통해 노출함. 8080 port 사용.

A2A Server

하위 컴포넌트	역할
Agent Card	agent의 이름, 설명, URL, capability 같은 discovery metadata를 제공하는 진입점
A2A JSON-RPC Endpoint	message/send, message/stream, tasks/* 요청을 받아 agent 실행으로 연결하는 호출 경로
Protocol / Security	HTTP(S), JSON-RPC 2.0, auth scheme을 통해 외부 client와의 통신 규약을 정의하는 계층

Execution Runtime

하위 컴포넌트	역할
Agent Executor	A2A 요청을 받아 session을 열거나 재개하고, agent 실행과 응답 생성을 시작하는 진입점
Session / Memory	대화 이력, task 상태 등을 유지해 multi-turn 실행과 재개를 가능하게 하는 상태 계층
A2A Client / Subagent Delegation	다른 agent를 subagent 또는 tool처럼 호출할 때 A2A client로 요청을 보내고, task와 결과를 현재 실행 흐름에 연결하는 계층
MCP Client / Tool Loop	LLM이 tool 호출을 결정하면 해당 MCP server에 요청을 보내고, 결과를 다시 LLM loop에 결합하는 실행 경로
Event Conversion / HITL	내부 실행 이벤트를 A2A event로 변환해 외부로 스트리밍하고, 승인 필요 시 실행을 pause/resume 하는 계층. HITL은 Human In The Loop을 의미

Declarative vs BYO Agents

kagent는 프롬프트만으로 Agent를 생성하는 Declarative Agent와 BYO Agent 모두를 지원.

•

Declarative: 프롬프트, 모델, tool만 지정하면 kagent가 ADK runtime 기반의 Agent Deployment와 설정 주입을 생성·관리

•

BYO(Bring Your Own): 이미 작성한 agent runtime과 custom container image를 그대로 가져올 수 있고, kagent는 그 image를 기준으로 Agent Deployment를 생성

◦

인터페이스: BYO runtime은 A2A Server 인터페이스를 제공하며, kagent는 이를 기존 Agent와 같은 방식으로 배포·호출

◦

지원 외부 framework: ADK, LangGraph, CrewAI, OpenAI Agents SDK 포함

◦

프로젝트 / container 생성: 새 프로젝트를 시작할 때는 현재 CLI 기준 kagent init이 adk/python scaffold를 지원. 이후 kagent build로 Docker image를 만들고, kagent deploy로 image build / push 후 Agent CRD와 관련 리소스를 생성 가능

◦

A2A 미지원 runtime: wrapper / adapter를 통해 A2A Server 형태로 연결

MCP Server 실행 구조

graph LR
    Clients["<b>Agent via agentgateway</b>"]
    Backend["<b>Backend Service / API</b>"]

    Controller["<b>kmcp-controller</b><br/><i>MCPServer CR</i>"]

    subgraph MCPServer[" "]
        MCPTitle["<b>MCP Server</b><br/><i>1 Deployment</i>"]

        subgraph MCP["<b>MCP Interface</b>"]
            Endpoint["<b>MCP Endpoint</b><br/><i>/mcp</i>"]
            Methods["<b>MCP Methods</b><br/><i>tools/list, tools/call</i>"]
            Transport["<b>Transport Type</b><br/><i>http or stdio</i>"]
        end

        Runtime["<b>Tool Runtime</b><br/>- Image / Cmd / Args<br/>- Env / SecretRefs<br/>- Backend Client"]
    end

    Controller -.->|Manage| MCPTitle
    Clients <-->|MCP request / response| MCP
    Methods -.->|Dispatch| Runtime
    Runtime -->|API Call| Backend

    classDef runtime_kagent fill:#f3e5f5,stroke:#7e57c2,stroke-width:2px,color:#311b92
    classDef external_dep fill:#fff8e1,stroke:#f9a825,stroke-width:2.5px,color:#6d4c41
    classDef a2a_box fill:#e3f2fd,stroke:#64b5f6,stroke-width:2px,color:#0d47a1
    classDef a2a_box_alt fill:#d6ecfb,stroke:#42a5f5,stroke-width:2px,color:#0d47a1
    classDef core_box fill:#f5f9fd,stroke:#bbdefb,stroke-width:1.5px,color:#0d47a1
    classDef agent_title fill:none,stroke:none,color:#0d47a1,font-size:16px

    style MCPServer fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#0d47a1
    style MCP fill:#eef5fc,stroke:#90caf9,stroke-width:1.5px,color:#0d47a1

    class Clients external_dep
    class Backend external_dep
    class Controller runtime_kagent
    class MCPTitle agent_title
    class Endpoint a2a_box
    class Methods a2a_box_alt
    class Transport a2a_box
    class Runtime core_box
Mermaid
복사
Figure 3. MCP Server agent의 내부 구조 및 타 components와의 연결 구조

managed MCP Server는 MCPServer CR을 기준으로 kmcp-controller가 배포·관리하며, runtime에서는 Agent 또는 agentgateway가 MCP 요청을 보내고, 내부 tool runtime이 실제 backend service 또는 API를 호출한다.

이 구조는 kmcp-controller가 생성하는 managed MCP Server뿐 아니라, kagent-querydoc, kagent-grafana-mcp 같은 preinstalled MCP tool server에도 동일하게 적용된다.

MCP Interface

하위 컴포넌트	역할
MCP Endpoint	MCP client가 붙는 /mcp 진입점
MCP Methods	주로 tools/list, tools/call 같은 MCP 호출을 받아 tool 실행으로 연결하는 경로
Transport Type	MCPServer spec의 transportType에 따라 http 또는 stdio transport를 선택하는 설정 계층

Tool Runtime

하위 컴포넌트	역할
Image / Cmd / Args	MCPServerDeployment에 정의된 image, command, args로 runtime 프로세스를 구성
Env / SecretRefs	tool runtime에 필요한 환경 변수와 secret 참조를 주입
Backend Client	tool 구현이 실제 내부 서비스, 외부 API, Kubernetes 리소스 등 backend dependency를 호출하는 계층

MCP 프로젝트 / 배포

•

프로젝트 scaffold: kagent mcp init은 fastmcp-python, mcp-go, typescript, java 기반 MCP server 프로젝트 scaffold를 생성

•

Image build: kagent mcp build는 프로젝트 디렉터리에서 Docker image를 생성

•

Cluster deploy: kagent mcp deploy는 MCPServer manifest를 생성하거나 클러스터에 적용하며, http / stdio transport를 선택 가능

•

Preinstalled MCP tool server: kagent-tools, kagent-querydoc, kagent-grafana-mcp

•

kagent-tools built-in tool catalog: 공식 Tools Registry 기준 Documentation(1), Prometheus(21), Kubernetes(21), Istio(13), Helm(6), Argo(7), Grafana(9), Cilium(58), Other(1) 등 100개 이상의 built-in MCP tool 포함

References

•

Book: AI Agents in Kubernetes

•

kagent Github

•

agentgateway Github

•

Kagent Documentation

•

Kmcp Documentation

•

A2A Specification

Appendix: Prometheus Metrics Inventory

아래 목록은 kagent, agentgateway코드 기준의 metric family inventory이다. histogram 계열은 Prometheus에서{bucket,sum,count} suffix로 노출되므로, 표에서는 이를 묶어서 표기했다.

kagent

kagent는 metrics-bind-address를 켰을 때 metric을 노출한다. 저장소 코드 기준으로는 kagent 자체 metric 하나와 controller-runtime / client-go 기본 metric family가 함께 노출된다.

Prometheus full name	타입	의미
kagent_build_info	gauge	kagent 빌드 버전 정보
controller_runtime_reconcile_total	counter	controller별 reconcile 수
controller_runtime_reconcile_errors_total	counter	controller별 reconcile error 수
controller_runtime_terminal_reconcile_errors_total	counter	controller별 terminal reconcile error 수
controller_runtime_reconcile_panics_total	counter	controller별 reconcile panic 수
controller_runtime_reconcile_time_seconds_{bucket,sum,count}	histogram	controller별 reconcile 지연 시간
controller_runtime_max_concurrent_reconciles	gauge	controller별 최대 동시 reconcile 수
controller_runtime_active_workers	gauge	controller별 활성 worker 수
workqueue_depth	gauge	workqueue depth
workqueue_adds_total	counter	workqueue add 수
workqueue_queue_duration_seconds_{bucket,sum,count}	histogram	item이 queue에서 대기한 시간
workqueue_work_duration_seconds_{bucket,sum,count}	histogram	item 처리 시간
workqueue_unfinished_work_seconds	gauge	아직 완료되지 않은 work 총 시간
workqueue_longest_running_processor_seconds	gauge	가장 오래 실행 중인 processor 시간
workqueue_retries_total	counter	workqueue retry 수
rest_client_requests_total	counter	Kubernetes API client 요청 수
leader_election_master_status	gauge	leader election 상태
leader_election_slowpath_total	counter	leader election slow path 발생 수
controller_runtime_webhook_latency_seconds_{bucket,sum,count}	histogram	webhook 처리 지연 시간
controller_runtime_webhook_requests_total	counter	webhook 요청 수
controller_runtime_webhook_requests_in_flight	gauge	처리 중 webhook 요청 수
controller_runtime_webhook_panics_total	counter	webhook panic 수

추가로 controller-runtime는 Prometheus Go / Process collector도 등록하므로 아래 family도 함께 노출될 수 있다.

Prometheus full name	타입	의미
process_*	collector family	프로세스 CPU, 메모리, FD, start time 등
go_*	collector family	Go runtime / GC / heap / goroutine 관련 metric

agentgateway

agentgateway는 agentgateway_ prefix 하위에 metric을 노출한다.

Prometheus full name	타입	의미
agentgateway_build_info	info gauge	빌드 버전 정보
agentgateway_requests_total	counter	HTTP 요청 수
agentgateway_request_duration_seconds_{bucket,sum,count}	histogram	HTTP 요청 지연 시간
agentgateway_response_bytes_total	counter	HTTP 응답 바이트 수
agentgateway_mcp_requests_total	counter	MCP 요청 수
agentgateway_gen_ai_client_token_usage_{bucket,sum,count}	histogram	LLM 요청별 token 사용량
agentgateway_gen_ai_server_request_duration_{bucket,sum,count}	histogram	LLM 요청 전체 지연 시간
agentgateway_gen_ai_server_time_per_output_token_{bucket,sum,count}	histogram	output token 생성 속도
agentgateway_gen_ai_server_time_to_first_token_{bucket,sum,count}	histogram	first token latency
agentgateway_tls_handshake_duration_seconds_{bucket,sum,count}	histogram	inbound TLS/HTTPS handshake 시간
agentgateway_downstream_connections_total	counter	downstream 연결 수
agentgateway_downstream_received_bytes_total	counter	downstream 수신 바이트 수
agentgateway_downstream_sent_bytes_total	counter	downstream 송신 바이트 수
agentgateway_upstream_connect_duration_seconds_{bucket,sum,count}	histogram	upstream 연결 수립 시간
agentgateway_guardrail_checks_total	counter	guardrail 검사 수
agentgateway_xds_connection_terminations_total	counter	xDS 연결 종료 수
agentgateway_xds_message_total	counter	xDS 메시지 수
agentgateway_xds_message_bytes_total	counter	xDS 메시지 바이트 수
agentgateway_tokio_global_queue_depth	gauge	Tokio runtime global queue 깊이
agentgateway_tokio_num_alive_tasks	gauge	살아 있는 Tokio task 수
agentgateway_tokio_num_workers	gauge	Tokio worker thread 수