Kubernetes 클러스터 안에서 AI 에이전트를 선언적으로 운영하려면, 런타임·툴·모델 설정을 각각 따로 맞추다 보면 복잡도 상승 및 관리 포인트 증가로 이어질수 있는데 Kagent는 이걸 CRD 하나로 묶어주는 플랫폼이다. Solo.io에서 시작했고, 현재 CNCF sandbox 프로젝트로 진행 중이다.

이번 글에서는 공식 문서의 코어 컨셉—Architecture, Agent, Tools, AgentHarness—을 정리하고, 각각이 어떻게 연결되는지 본다. Helm 차트로 배포 한뒤 에이전트 배포, 모델 연결 등의 테스트 내용은 다음 글에서 다룰 예정이다.

Architecture

Kagent는 Agentic AI 플랫폼으로서 여러 컴포넌트로 구성된다.(Architecture)

컴포넌트 역할
Controller Go로 작성된 Kubernetes controller. Agent·Tool 등 CRD를 reconcile한다.
Engine (App) 에이전트 대화 루프의 핵심. Python ADK(기본) 또는 Go ADK 중 선택.
CLI Engine에 붙어서 리소스 관리·에이전트 대화를 CLI로 처리.
Dashboard 웹 UI. kubectl port-forward svc/kagent 8001:80 후 localhost:8001로 접속.

Engine 런타임 선택은 Agent spec의 runtime 필드로 한다. Python ADK는 Google ADK·LangGraph·CrewAI 연동에 유리하고, Go ADK는 기동이 빠른 장점과 (문서 기준 ~2초 vs ~15초) 리소스를 적게 쓰는 장점이 있다. MCP, HITL, Memory는 둘 다 지원한다.

Controller가 YAML을 받아 워크로드를 만들고, Engine이 LLM과 대화 루프를 돌리며, CLI·Dashboard는 같은 Engine에 붙는 구조다. 사용자는 UI나 CLI로 말을 걸고, 실제 추론·툴 호출은 Engine이 맡는다.

Agent

Agent CRD 하나가 “이 에이전트가 누구인지”를 정의한다. (Agents)

구성 요소는 크게 세 가지다.

  • Instructions (system prompt) — 역할, 말투, 행동 범위
  • Tools — 환경과 상호작용하는 함수
  • Skills — 툴을 언제·어떻게 쓸지 가이드하는 역량 설명

Instructions는 ConfigMap에 공통 프롬프트를 두고 ``로 끼워 넣을 수 있다. Controller가 reconcile 시점에 펼쳐 주므로, 안전 가드레일·툴 사용 규칙을 에이전트마다 복붙할 필요가 없다.

에이전트의 CRD kind와 spec 기준으로 보면 아래 처럼 나눌수 있을 것 같다.

  • Agent — 기본 CRD. 문서 예시 대부분은 spec.type: Declarative로 YAML을 선언하고, Engine이 Python/Go ADK 런타임을 실행한다. (Runtime)
  • SandboxAgent — Agent와 별도 CRD. spec은 Agent와 동일하지만 격리 샌드박스 워크로드로 띄운다. 기본적으로 아웃바운드가 차단된다. (Sandboxed Agents)
  • AgentHarness — 위 둘과 다른 리소스. 에이전트 런타임 대신 원격 실행 환경만 프로비저닝한다. (How it differs from agents)

부가 기능으로 HITL(민감한 툴은 승인 후 실행), Memory(대화 맥락 저장), Context compaction(긴 대화 요약)도 Agent spec에서 켤 수 있다.

Tools

툴은 에이전트가 “말” 너머로 실제 행동을 하게 만드는 부분이다. (Tools)

K8s 에이전트라면 pod 목록 조회, 로그 확인, 리소스 describe 같은 작업이 여기에 해당한다. 툴 정의와 설명은 Instructions와 함께 LLM에 전달되고, 모델이 사용자 요청을 보고 호출 여부를 판단한다.

툴을 붙이는 방법은 여러가지를 사용할 수 있다.

종류 설명
Built-in K8s·관측 등 기본 제공. 시작점으로 쓰기 좋다.
MCP Model Context Protocol 서버. 외부·커스텀 툴 연결의 주 경로.
HTTP URL + 스키마로 OpenAPI 호환 서비스 연동.
Agent as Tool 다른 Agent를 툴처럼 참조. PromQL 전문 에이전트를 메인 에이전트가 호출하는 패턴.
kmcp MCP 서버 개발·배포용 서브프로젝트. Kagent 설치 시 기본 포함.

다른 네임스페이스의 MCP 서버는 namespace/name 형식으로 참조할 수 있다. API 키 같은 헤더는 headersFrom으로 Secret·ConfigMap에서 주입한다.

민감한 툴(k8s_delete_resource 등)은 requireApproval에 넣어 UI에서 Approve/Reject를 받게 할 수 있다.

세 가지가 만나는 지점

정리하면 이렇게 이어진다.

Controller (CRD reconcile)
    ↓ Agent spec: instructions + tools + modelConfig
Engine (대화 루프)
    ↓ LLM 추론 → tool call
Tools (built-in / MCP / HTTP / 다른 Agent)
    ↓ 실제 API·클러스터·외부 서비스 호출

Instructions는 “무엇을, 어떤 태도로” 정하고, Tools는 “실제로 무엇을 할 수 있는지”를 열어 준다. Skills는 같은 툴이라도 troubleshooting용인지 조사용인지 방향을 잡아 준다. ModelConfig는 Supported Provider 중 하나를 가리키고, Engine이 그 endpoint로 추론 요청을 보낸다.

에이전트끼리 협업도 가능하다. A2A(Agent-to-Agent)로 노출된 에이전트는 Controller의 /mcp 엔드포인트를 통해 다른 에이전트의 툴처럼 붙일 수 있다.

AgentHarness

위에서 언급한 AgentHarness CRD를 조금 더 살펴 본다. (Agent Harness)

공식 문서(How it differs from agents) 기준 비교는 다음과 같다.

  Agent / SandboxAgent AgentHarness
목적 Kagent가 관리하는 에이전트 런타임 실행 원격 실행 환경(샌드박스)만 프로비저닝
비유 “에이전트 앱” “에이전트가 붙을 VM·쉘 환경”

OpenShell gateway를 통해 장기 실행 샌드박스를 만들고, Slack 같은 메시징 채널과 연결할 때 쓴다. spec.backend로 openclaw, nemoclaw, hermes 중 선택하고, modelConfigRef로 모델 설정을 넘긴다.

상태는 Accepted(spec 수용 여부)와 Ready(샌드박스 가용 여부) 두 조건으로 확인한다. Agent API·Dashboard에 같이 보이지만, 풀 에이전트 런타임을 패키징하지 않는다는 점이 핵심이다.

Supported Providers

LLM은 ModelConfig CRD로 연결한다. (Supported Providers) 지원 프로바이더 종류만 적어두면 다음과 같다.

Amazon Bedrock · Anthropic · Azure OpenAI · OpenAI · Ollama · Gemini · Google Vertex AI · SAP AI Core · xAI (Grok) · BYO OpenAI-compatible

세부 인증·endpoint 설정은 각 프로바이더 문서를 보면 된다. 배포할 때 어떤 걸 쓸지는 다음 포스팅에 작성할 예정이다.

Solo Kagent Enterprise

오픈소스 Kagent의 엔터프라이즈 버전이다. (About – Solo Enterprise for kagent) CRD로 에이전트·툴을 선언하는 기본 흐름은 같고, 운영·보안·멀티클러스터 쪽이 Enterprise에서 갈린다.

아키텍처도 한 단계 더 쌓인다. management 클러스터의 controller가 agent 클러스터와 relay tunnel로 연결되고, 단일 control plane에서 여러 클러스터의 에이전트·툴·연결·관측을 묶는 구조다.

멀티클러스터·운영

  • Multicluster federation — 단일 control plane에서 연결된 클러스터 전반의 에이전트·툴·연결·관측 관리
  • Enterprise management dashboard — 클러스터를 가로지르며 에이전트 생성·검증·디버그·배포·모니터링
  • Interactive UI — execution flow graph, trace tree, agent detail view
  • Multi-tenancy — namespace별 controller + Postgres schema 격리
  • Pre-built agents — k8s, helm, istio, promql, observability, cilium, argo-rollouts 등 기본 번들

관측(Observability)

  • Built-in OTel pipeline + ClickHouse — 클러스터 간 분산 트레이싱·서비스 그래프
  • BYO ClickHouse — 기존 ClickHouse 인스턴스 연결
  • Compliance audit trails — 에이전트 액션, 툴 호출, LLM 상호작용 전체 provenance 로깅

보안·인증

  • OIDC — Keycloak, Microsoft Entra ID, Okta, generic OIDC
  • RBAC — admin/writer/reader 역할을 IdP 그룹에 매핑
  • STS token exchange (OBO) — 에이전트가 위임된 사용자 identity로 downstream 요청
  • AccessPolicy — 에이전트·MCP 툴에 대한 fine-grained authorization
  • Kubernetes authorization — Kagent 로그인 토큰을 K8s credential로 교환, 네이티브 RBAC 적용
  • Agentgateway + Istio ambient mesh — MCP 툴 트래픽 프록시, waypoint/L4 정책, 멀티클러스터 mTLS

그 외

  • Solo build의 hardened chart, authorization policies for agents
  • FIPS·compliance용 specialty build, 24x7 production support

오픈소스와 Enterprise 기능 비교 전체 표는 How is Solo Enterprise for kagent different from the open source project?에 정리돼 있다. 다음 글은 오픈소스 Helm 배포 기준이지만, SSO·멀티클러스터가 필요하면 Enterprise 쪽 아키텍처를 참고하면 된다.

마무리

Kagent를 한 줄로 줄이면 “Kubernetes-native AI agent control plane” 이다. Controller가 선언적 spec을 받고, Engine이 LLM 루프를 돌리고, Tools가 클러스터·외부 세계와 연결된다.

다음 글에서는 Helm chart로 Kagent를 클러스터에 배포 하고, Agent·ModelConfig등을 배포하여 AWS Bedrock, LiteLLM과 연동하여 대화해 보는 과정, oauth2-proxy로 프론트 인증(sso) 등을 정리할 예정이다.

참고