# Gemini CLI 마스터하기(심화): v25 - 최종 실전 예제: 나만의 'K8s 상태 모니터링' Guarded Action 도구 만들기

길고도 심도 깊었던 Gemini CLI 마스터하기 여정의 마지막 단계에 오신 것을 환영합니다! 이전 단계들에서 우리는 에이전트의 지능(프롬프트 템플릿)과 안전하고 체계적인 외부 도구 연동(`ToolSchema`, `GuardedAction`) 방법을 배웠습니다. 이제 이 모든 지식을 총망라하여, 실제 **Kubernetes(K8s) 클러스터 상태를 모니터링하는 나만의 `GuardedAction` 도구**를 만들고 Gemini 에이전트에 연동하는 실전 예제를 통해, Gemini CLI의 무한한 확장성을 직접 경험해 보겠습니다.

---

## 1. 시나리오: DevOps 엔지니어의 K8s 파드 상태 점검

DevOps 엔지니어인 여러분은 매일 아침 간단한 질문만으로 K8s 클러스터의 파드 상태를 점검하고, 문제가 있는 파드만 요약 보고받고 싶습니다. 이를 위해 Gemini 에이전트가 K8s 클러스터와 직접 통신하여 파드 상태를 가져오고, 'Running' 상태가 아닌 파드들을 식별하여 보고하는 도구를 만들 것입니다.

## 2. 나만의 K8s 모니터링 도구 만들기 (개념 코드)

### 단계 1: 도구의 핵심 로직 (`check_unhealthy_pods_func`) 정의

이 함수는 K8s 클러스터에서 파드 목록을 가져와 'Running' 상태가 아닌 파드들을 찾아 반환하는 역할을 합니다. (v21에서 다룬 `list_resources` 로직을 활용)

```python
# k8s_monitor_tool.py 파일 (가상의 Python 코드)

from kubernetes import config, client # 실제 K8s 파이썬 클라이언트 라이브러리
# dynamic_client 등 v21에서 언급된 인터페이스를 사용한다고 가정

def check_unhealthy_pods_func(namespace: str = None) -> str:
    """
    Kubernetes 클러스터의 모든 파드(또는 지정된 네임스페이스의 파드) 상태를 모니터링하고,
    'Running' 상태가 아닌 파드들의 목록과 그 이유를 요약하여 반환합니다.
    """
    try:
        # v21에서 언급된 dynamic_client 등을 통해 K8s API 접근
        # 여기서는 단순화를 위해 kubernetes 파이썬 클라이언트를 직접 사용한다고 가정
        config.load_kube_config()
        v1 = client.CoreV1Api()

        if namespace:
            pods = v1.list_namespaced_pod(namespace=namespace).items
        else:
            pods = v1.list_pod_for_all_namespaces().items

        unhealthy_pods_summary = []
        for pod in pods:
            if pod.status.phase != "Running":
                reason = pod.status.reason if pod.status.reason else "N/A"
                message = pod.status.message if pod.status.message else "N/A"
                unhealthy_pods_summary.append(
                    f"- 파드: {pod.metadata.name} (네임스페이스: {pod.metadata.namespace})\n"
                    f"  상태: {pod.status.phase}, 이유: {reason}, 메시지: {message}\n"
                    f"  재시작 횟수: {sum([c.restart_count for c in pod.status.container_statuses or []])}"
                )
        
        if unhealthy_pods_summary:
            return "다음 파드들이 'Running' 상태가 아닙니다:\n" + "\n".join(unhealthy_pods_summary)
        else:
            return "모든 파드가 정상적으로 'Running' 상태입니다."

    except Exception as e:
        return f"Kubernetes 파드 상태를 확인하는 중 오류 발생: {e}"

# 실제 prepare/cleanup 함수는 K8s 클라이언트 초기화/종료 로직을 포함할 수 있습니다.
# 여기서는 편의상 간단하게 정의합니다.
def prepare_k8s_client():
    print("K8s 클라이언트 준비 중...")
    # 실제로는 K8s 클라이언트 인스턴스 초기화 및 인증 확인 로직 포함
    return True

def cleanup_k8s_client():
    print("K8s 클라이언트 정리 완료.")
    # 실제로는 K8s 클라이언트 자원 해제 로직 포함
    pass
```

### 단계 2: `GuardedAction`으로 감싸기

`check_unhealthy_pods_func`를 `GuardedAction`으로 감싸 안전한 실행을 보장합니다.

```python
# k8s_monitor_tool.py 파일에 추가

from gemini_cli_framework import GuardedAction # 가상의 프레임워크 임포트

k8s_monitor_action = GuardedAction(
    name="monitor_k8s_pods",
    func=check_unhealthy_pods_func,
    prepare_func=prepare_k8s_client,
    cleanup_func=cleanup_k8s_client
)
```

### 단계 3: `ToolSchema` 정의

이 도구를 에이전트가 이해할 수 있도록 `ToolSchema`를 정의합니다.

```python
# k8s_monitor_tool.py 파일에 추가

from gemini_cli_framework import ToolSchema # 가상의 프레임워크 임포트

k8s_monitor_schema = ToolSchema(
    name="monitor_k8s_pods",
    description="Kubernetes 클러스터의 파드 상태를 모니터링하여 'Running' 상태가 아닌 파드들을 찾아 요약 보고합니다. 특정 네임스페이스를 지정하여 확인할 수 있습니다.",
    parameters={
        "type": "object",
        "properties": {
            "namespace": {
                "type": "string",
                "description": "모니터링할 Kubernetes 네임스페이스. 생략 시 모든 네임스페이스의 파드를 확인합니다."
            }
        }
    }
)
```

### 단계 4: Gemini CLI에 도구 등록 (개념)

이제 위에서 정의한 `GuardedAction`과 `ToolSchema`를 Gemini CLI의 에이전트 프레임워크에 등록해야 합니다. 이는 보통 CLI의 설정 파일이나 플러그인 메커니즘을 통해 이루어집니다.

```bash
# 가상의 CLI 명령어
gemini register-tool \
  --name k8s_monitor_tool \
  --action-module k8s_monitor_tool.py \
  --schema-object k8s_monitor_tool.k8s_monitor_schema \
  --action-object k8s_monitor_tool.k8s_monitor_action
```

## 3. 인터랙티브 모드에서 나만의 K8s 모니터링 도구 사용하기

도구가 성공적으로 등록되면, `INTERACTIVE=1`로 `gemini web`을 실행하여 웹 인터페이스에 접속한 후, 자연어로 에이전트에게 파드 상태 점검을 요청할 수 있습니다.

**예시 1: 클러스터 전체 파드 상태 점검**

*   **사용자:** "현재 Kubernetes 클러스터의 파드 상태는 어때? 문제가 있는 파드만 보고해 줘."
*   **에이전트 로그:** "사용자 요청 분석: Kubernetes 파드 상태 모니터링 필요. `monitor_k8s_pods` 도구 사용 결정."
*   **행동 제안 카드:** "제안된 행동: `monitor_k8s_pods(namespace=None)`"
*   **사용자:** 승인.
*   **에이전트 응답:** `check_unhealthy_pods_func` 함수가 반환한 결과를 LLM이 해석하여 요약 보고합니다.
    ```
    AI: 현재 클러스터에서 2개의 파드가 'Running' 상태가 아닙니다:
    - 파드: backend-deployment-abc12-xyz34 (네임스페이스: default)
      상태: CrashLoopBackOff, 이유: Error, 메시지: Container failed to start
      재시작 횟수: 5
    - 파드: frontend-deployment-qwe56-asd78 (네임스페이스: production)
      상태: Pending, 이유: InsufficientCPU, 메시지: 0/3 nodes are available: 3 Insufficient cpu.
    ```

**예시 2: 특정 네임스페이스의 파드 상태 점검**

*   **사용자:** "default 네임스페이스의 파드 상태만 확인해 줘."
*   **에이전트 로그:** "사용자 요청 분석: `default` 네임스페이스 파드 상태 모니터링 필요. `monitor_k8s_pods` 도구 사용 결정."
*   **행동 제안 카드:** "제안된 행동: `monitor_k8s_pods(namespace='default')`"
*   **사용자:** 승인.
*   **에이전트 응답:** `default` 네임스페이스에 있는 문제 파드들만 보고합니다.

## 4. 시리즈를 마치며: 나만의 AI 에이전트를 향한 여정

v1부터 v25까지 이어진 긴 여정을 통해, 우리는 Gemini CLI가 단순한 프롬프트 응답 도구를 넘어, 다음과 같은 강력한 AI 에이전트 프레임워크임을 확인했습니다.

*   **다양한 상호작용 방식:** 텍스트, 음성 (기본 및 VAD)
*   **강력한 지식 검색:** 로컬 파일, 코드베이스, Elasticsearch (RAG)
*   **외부 시스템 연동:** Kubernetes 클러스터 관리 및 디버깅
*   **고도로 커스터마이징 가능한 지능:** 동적 프롬프트 템플릿 엔진
*   **안전하고 확장 가능한 실행:** `ToolSchema`와 `Guarded Actions`를 통한 도구 연동

이번 마지막 예제는 이 모든 개념의 집대성입니다. 여러분은 이제 Gemini CLI를 활용하여 자신만의 특정 요구사항을 해결하는 지능적이고 안전하며 확장 가능한 AI 에이전트를 구축할 수 있는 개념적 토대를 마련했습니다.

AI 에이전트 개발은 무한한 가능성을 지닌 분야입니다. 이 가이드가 여러분의 창의적인 아이디어를 현실로 만들고, Gemini CLI와 함께 더욱 효율적이고 혁신적인 미래를 만들어가는 데 큰 도움이 되기를 진심으로 바랍니다. 끊임없이 실험하고 배우며, 자신만의 AI 에이전트를 완성하는 즐거운 여정을 계속하시길 응원합니다!