Kubernetes에서 모든 AI 에이전트 실행하기: 단계별

Source: Dev.to

사전 요구 사항

이 가이드를 따라 하려면 다음이 필요합니다:

• kagent가 설치된 Kubernetes 클러스터. 아직 kagent를 설치하지 않았다면, 여기의 안내를 참고하세요.
• Python 3.10 이상.
• 컨테이너 이미지를 빌드하기 위한 Docker Desktop(또는 Docker 엔진) 설치.

BYO 에이전트란?

BYO(Bring Your Own, 직접 가져오기)는 kagent가 지원하는 어떤 공급자든 사용해 에이전트를 만들 수 있다는 의미입니다. Python으로 CrewAI, ADK, LangChain 또는 다른 프레임워크를 사용해 에이전트를 작성하든, kagent는 이를 가져올 수 있게 해줍니다. 추가로 필요한 단계는 에이전트를 컨테이너화하는 것인데, Dockerfile만 있으면 아주 간단합니다(예시는 Creating an Agent 섹션을 참고).

에이전트 만들기

다음 섹션에서는 Agent Development Kit(ADK)를 사용해 맞춤형 에이전트를 만드는 방법과 기존 에이전트를 참고하는 방법을 안내합니다.

에이전트 생성

1. Google ADK 라이브러리를 설치합니다(pip3를 사용해도 됩니다):

   pip install google-adk

2. 새 ADK 에이전트를 스캐폴드합니다:

   adk create NAME_OF_YOUR_AGENT

   그러면 adk/NAME_OF_YOUR_AGENT 디렉터리에 시작 템플릿이 생성됩니다.

3. 스캐폴드된 에이전트를 실행해 정상 동작을 확인합니다:

   cd adk/NAME_OF_YOUR_AGENT && adk run NAME_OF_YOUR_AGENT

   

기존 에이전트 사용

과정을 단순화하려면 미리 만들어진 에이전트 저장소를 시작점으로 사용할 수 있습니다.

1. 데모 저장소를 클론하고 ADK 예제로 이동합니다:

   git clone https://github.com/thenjdevopsguy/agentic-demo-code.git
   cd agentic-demo-code/adk/troubleshoot-agent

2. 제공된 Dockerfile을 검토합니다:

   # STAGE 1: base image
   ARG DOCKER_REGISTRY=ghcr.io
   ARG VERSION=0.7.4
   FROM $DOCKER_REGISTRY/kagent-dev/kagent/kagent-adk:$VERSION
   
   WORKDIR /app
   
   COPY troubleshootagent/ troubleshootagent/
   COPY pyproject.toml pyproject.toml
   COPY uv.lock uv.lock
   COPY how-it-works.md how-it-works.md
   
   RUN uv sync --locked --refresh
   
   CMD ["troubleshootagent"]

3. 컨테이너 이미지를 빌드합니다:

   docker build . -t troubleshootagent:latest

   uv sync 오류가 발생하면 먼저 lock 파일을 생성합니다:

   uv lock

   빌드가 성공하면 다음과 같은 화면이 나타납니다:

   

4. 이미지를 레지스트리에 푸시합니다(예: Docker Hub는 무료이며, 여기서는 GitHub Container Registry를 사용):

   docker tag troubleshootagent:latest adminturneddevops/troubleshootagent:latest
   docker push adminturneddevops/troubleshootagent:latest

   이미지를 푸시하고 싶지 않다면, 다음 단계에서 adminturneddevops/troubleshootagent:latest를 그대로 참조해도 됩니다(이미지가 공개되어 있기 때문).

Kubernetes에 에이전트 배포

컨테이너 이미지가 준비되면, kagent의 CRD를 사용해 선언형으로 배포합니다.

1. LLM 자격 증명 설정(예시에서는 Google Gemini를 사용; 필요에 따라 다른 공급자로 교체):

   export GOOGLE_API_KEY=YOUR_API_KEY_HERE

2. API 키를 저장할 Kubernetes Secret을 생성합니다:

   apiVersion: v1
   kind: Secret
   metadata:
     name: kagent-google
     namespace: kagent
   type: Opaque
   stringData:
     GOOGLE_API_KEY: $GOOGLE_API_KEY

   Secret을 적용합니다:

   kubectl apply -f-

3. 에이전트 커스텀 리소스를 정의합니다:

   apiVersion: kagent.dev/v1alpha2
   kind: Agent
   metadata:
     name: troubleshoot-agent
     namespace: kagent
   spec:
     description: Platform Engineering troubleshoot expert.
     type: BYO
     byo:
       deployment:
         image: adminturneddevops/troubleshootagent:latest
         env:
           - name: GOOGLE_API_KEY
             valueFrom:
               secretKeyRef:
                 name: kagent-google
                 key: GOOGLE_API_KEY

   Agent 매니페스트를 적용합니다:

   kubectl apply -f-

4. kagent 네임스페이스에서 Agent 파드가 실행 중인지 확인합니다:

   kubectl get pods -n kagent

   다음과 같은 파드가 표시될 것입니다:

   

이제 에이전트가 배포되어 kagent 내에서 사용할 준비가 되었습니다.