본문으로 건너뛰기

Kagent - Kubernetes AI Agent 관리

다중 모델 생태계에서 AI 에이전트는 여러 LLM/SLM을 호출하고, MCP/A2A 프로토콜로 도구와 다른 에이전트에 연결되며, 트래픽에 따라 동적으로 스케일링되어야 합니다. Kubernetes의 Operator 패턴은 이러한 에이전트를 CRD로 선언적으로 정의하고 자동으로 라이프사이클을 관리하는 가장 자연스러운 방식입니다. Kagent는 이 패턴을 AI 에이전트에 적용한 참조 아키텍처입니다.

1. 개요​

Kagent는 Custom Resource Definition(CRD)을 통해 에이전트, 도구, 워크플로우를 선언적으로 정의하고, Operator가 이를 자동으로 배포 및 관리합니다. Deployment, Service, ConfigMap을 직접 작성하는 대신 Agent CRD 하나로 모델 연결, 도구 바인딩, 스케일링 정책을 통합 관리할 수 있습니다.

Kagent 프로젝트 상태

Kagent는 현재 참조 아키텍처 및 디자인 패턴 단계이며, 공식 오픈소스 프로젝트가 아직 공개되지 않았습니다. 본 문서의 예제는 개념적 구현을 기반으로 합니다. 프로덕션 환경에서는 Bedrock AgentCore, KubeAI, LangGraph Platform 등 검증된 대안을 고려하세요.

Kagent 배포 가이드는 Kagent 공식 문서를 참조하세요.

대안 솔루션 비교​

🔍 Kagent 대안 솔루션 비교
솔루션특징적합한 사용 사례
Kagent (참조)
AI 에이전트 전용 CRD, 워크플로우 오케스트레이션멀티 에이전트 시스템, 복잡한 워크플로우
KubeAI
경량 LLM 서빙, OpenAI 호환 API간단한 모델 서빙, 빠른 프로토타이핑
Bedrock AgentCore
AWS 관리형 Agent 런타임, MCP/A2A 네이티브, 자동 스케일링AWS 네이티브 Agent 배포, 관리형 인프라 선호 시
LangGraph Platform
Agent 워크플로우 프레임워크, 상태 관리, LangSmith 네이티브 통합복잡한 멀티스텝 Agent, 상태 기반 워크플로우

주요 기능​

  • 선언적 에이전트 관리: YAML 기반 에이전트 정의 및 배포
  • 도구 레지스트리: 에이전트가 사용할 도구를 CRD로 중앙 관리
  • 자동 스케일링: HPA/KEDA 통합을 통한 동적 확장
  • 멀티 에이전트 오케스트레이션: 복잡한 워크플로우를 위한 에이전트 간 협업
  • 관측성 통합: Langfuse/LangSmith, OpenTelemetry와의 네이티브 연동
대상 독자

이 문서는 Kubernetes 관리자, 플랫폼 엔지니어, MLOps 엔지니어를 대상으로 합니다. Kubernetes 기본 개념(Pod, Deployment, CRD)에 대한 이해가 필요합니다.

re:Invent 2025 관련 세션

CNS421: Streamline Amazon EKS Operations with Agentic AI — Kagent와 같은 AI 에이전트를 활용한 EKS 클러스터 자동 관리, 실시간 이슈 진단, 자동 복구 방법을 다루는 코드 토크 세션입니다.

주요 내용:

  • Model Context Protocol (MCP): AI 에이전트가 AWS 서비스와 통합하기 위한 표준 프로토콜
  • 자동화된 인시던트 대응: Pod 장애, 리소스 부족, 네트워크 문제 자동 진단 및 복구
  • AWS 서비스 통합: CloudWatch, Systems Manager, EKS API와의 네이티브 연동

세션 영상 보기

2. Kagent 아키텍처​

Kagent는 Kubernetes Operator 패턴을 따르며, Controller, CRD, Webhook으로 구성됩니다.

컴포넌트 설명​

컴포넌트역할설명
Kagent Controller조정 루프CRD 변경을 감지하고 원하는 상태로 리소스를 조정
Admission Webhook검증/변환CRD 생성/수정 시 유효성 검사 및 기본값 설정
Metrics Server메트릭 수집에이전트 상태 및 성능 메트릭 노출
Agent CRD에이전트 정의AI 에이전트의 스펙, 모델, 도구 설정
Tool CRD도구 정의에이전트가 사용할 도구(API, 검색 등) 정의
Workflow CRD워크플로우 정의멀티 에이전트 협업 워크플로우 정의

컴포넌트 상호작용​

사전 요구사항​

  • Kubernetes 클러스터 (v1.25 이상)
  • kubectl CLI 도구
  • Helm v3 (Helm 설치 시)
  • cert-manager (Webhook TLS 인증서 관리)

3. CRD 구조​

Agent CRD​

Agent CRD는 AI 에이전트의 모든 설정을 선언적으로 정의합니다. 아래는 핵심 스펙 구조입니다:

apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
  name: customer-support-agent
  namespace: ai-agents
spec:
  # 에이전트 기본 정보
  displayName: "고객 지원 에이전트"
  description: "고객 문의에 응답하고 티켓을 생성하는 AI 에이전트"

  # 모델 설정
  model:
    provider: openai          # openai, anthropic, bedrock, vllm
    name: gpt-4-turbo
    endpoint: ""              # 커스텀 엔드포인트 (vLLM 등)
    temperature: 0.7
    maxTokens: 4096
    apiKeySecretRef:
      name: openai-api-key
      key: api-key

  # 시스템 프롬프트
  systemPrompt: |
    당신은 친절하고 전문적인 고객 지원 에이전트입니다.

  # 사용할 도구 목록
  tools:
    - name: search-knowledge-base
    - name: create-ticket

  # 메모리 설정
  memory:
    type: redis
    config:
      host: redis-master.ai-data.svc.cluster.local
      ttl: 3600
      maxHistory: 50

  # 스케일링 설정
  scaling:
    minReplicas: 2
    maxReplicas: 10
    metrics:
      - type: cpu
        target:
          averageUtilization: 70
    keda:
      enabled: true
      triggers:
        - type: prometheus
          metadata:
            metricName: agent_active_sessions
            threshold: "50"

  # 리소스 제한
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

  # 관측성 설정
  observability:
    tracing:
      enabled: true
      provider: langfuse       # langfuse, langsmith, cloudwatch (상세: ../operations-mlops/observability/llmops-observability.md)
    metrics:
      enabled: true
      port: 9090

Tool CRD​

Tool CRD는 에이전트가 사용할 수 있는 도구를 정의합니다. 도구 유형은 api, retrieval, code, human이 있습니다.

주요 필드:

필드설명예시
spec.type도구 유형retrieval, api, code, human
spec.descriptionLLM이 도구 선택 시 참조하는 설명"지식 베이스에서 문서 검색"
spec.retrieval벡터 스토어 연결 설정Milvus, Pinecone 등
spec.apiREST API 호출 설정엔드포인트, 인증, 타임아웃
spec.parameters입력 파라미터 스키마name, type, required, enum
spec.output출력 스키마JSON Schema 형식

Memory CRD​

에이전트의 대화 컨텍스트와 상태를 저장하기 위한 메모리 설정입니다.

주요 기능:

기능설명
세션 메모리Redis/PostgreSQL 기반 단기 대화 기록 (TTL 설정)
대화 압축임계값 초과 시 LLM으로 대화 요약
장기 메모리벡터 스토어 기반 에이전트 경험 누적
메모리 유형redis, postgres, in-memory

Workflow CRD​

Workflow CRD를 사용하여 멀티 에이전트 워크플로우를 정의합니다.

핵심 구조:

필드설명
spec.input워크플로우 입력 파라미터 정의
spec.steps단계별 에이전트 실행 정의 (순차/병렬)
spec.steps[].dependsOn의존 단계 지정 (DAG 구성)
spec.steps[].parallel병렬 실행 여부
spec.output워크플로우 최종 출력 매핑
spec.errorHandling단계/워크플로우 실패 시 동작
spec.timeout전체 워크플로우 타임아웃
spec.concurrency동시 실행 제한 (queue/reject/replace)

4. 멀티 에이전트 오케스트레이션​

복잡한 작업을 여러 에이전트가 협업하여 처리하는 워크플로우를 정의합니다.

에이전트 간 통신 패턴​

오케스트레이션 패턴​

패턴설명적합한 경우
순차 파이프라인단계별 순차 실행, 이전 단계 출력이 다음 입력데이터 처리, ETL
병렬 팬아웃동일 입력을 여러 에이전트에 병렬 전달다각도 분석, A/B 비교
DAG 워크플로우의존성 기반 유향 비순환 그래프 실행복잡한 리서치, 보고서 생성
루프조건 충족까지 반복 실행검토-수정 사이클, 품질 검증
라우팅입력 내용에 따라 다른 에이전트로 분기문의 분류, 전문 영역 분배

워크플로우 예시: 리서치 리포트​

워크플로우 실행 상태는 WorkflowRun CRD를 통해 추적합니다:

상태설명
Pending실행 대기 중
Running하나 이상의 단계가 실행 중
Succeeded모든 단계 성공 완료
Failed하나 이상의 단계 실패 (재시도 소진)

5. Agent 라이프사이클 관리​

Operator가 관리하는 리소스​

Agent CRD를 생성하면 Controller가 다음 리소스를 자동으로 생성/관리합니다:

Agent CRD 생성
  ├── Deployment (에이전트 Pod 관리)
  ├── Service (네트워크 접근)
  ├── HPA/KEDA ScaledObject (자동 스케일링)
  ├── ConfigMap (에이전트 설정)
  └── Secret 참조 (API 키, 인증 정보)

업데이트 전략​

전략설명권장 시나리오
롤링 업데이트기본 전략. Pod를 점진적으로 교체일반적인 설정 변경
카나리 배포별도 Agent CRD로 새 버전 테스트모델 변경, 프롬프트 대규모 수정
블루-그린두 버전을 동시 운영 후 트래픽 전환무중단 마이그레이션

스케일링 전략​

메트릭설명임계값 예시
CPU 사용률기본 리소스 기반 스케일링70%
메모리 사용률메모리 압박 시 스케일 아웃80%
활성 세션 수KEDA + Prometheus 커스텀 메트릭50 세션/Pod
요청 처리량초당 요청 수 기반100 RPS/Pod

6. 관측성 통합​

Agent 실행 트레이스는 Langfuse, LangSmith, CloudWatch Generative AI Observability 중 하나로 전송합니다. 각 도구의 비교는 LLMOps Observability 비교를 참조하세요.

배포 가이드:

핵심 알림 규칙​

알림조건심각도
에이전트 오류율 증가오류율 > 5% (5분 지속)Critical
에이전트 응답 지연P99 > 30초 (5분 지속)Warning
Pod 가용성 저하Ready Pod < 50% (5분 지속)Critical

7. 결론​

Kagent를 활용하면 Kubernetes 환경에서 AI 에이전트를 선언적으로 관리할 수 있습니다. 주요 이점은 다음과 같습니다:

  • 선언적 관리: YAML 기반 에이전트 정의로 GitOps 워크플로우 지원
  • 자동화된 운영: Operator 패턴을 통한 자동 복구 및 스케일링
  • 표준화: CRD를 통한 에이전트 정의 표준화
  • 확장성: Kubernetes 네이티브 스케일링 메커니즘 활용
  • 관측성: 통합 모니터링 및 추적 지원
다음 단계

참고 자료​

공식 문서​

관련 문서​