콘텐츠로 이동
Study Notekagent 실습

0. 실습 지도와 안전 경계

내용 검토: 2026. 08. 21.검토 필요

결론부터
첫 명령보다 먼저 어느 cluster에서 어떤 권한의 Agent를 만들고, backend와 온프렘 승격을 무엇으로 성공 판정할지 고정한다
이 장에서 처음 나오는 말4개
Agent CRAgent Custom Resource
model·prompt·tool과 실행 방식을 Kubernetes에 선언하는 kagent resource다.
control planeControl Plane
Agent resource를 읽고 workload와 호출 endpoint를 조정하는 kagent controller와 API 층이다.
MCPModel Context Protocol
Agent가 외부 기능을 발견하고 호출하는 tool 계약이다.
A2AAgent-to-Agent Protocol
client나 다른 Agent가 Agent의 card를 발견하고 task를 호출하는 바깥쪽 계약이다.

이번 실습의 작은 세계

섹션 제목: “이번 실습의 작은 세계”
backend의 관리 요청은 Kubernetes API로, 호출 요청은 kagent controller의 A2A route로 들어가며 controller가 Agent workload를 조정하는 두 경로

관리와 호출은 같은 경로가 아니다. backend는 Kubernetes API에 CRD를 apply하고 status를 읽으며, 실제 질문은 kagent-controller Service의 8083 A2A route로 보낸다. Agent가 답하려면 resource가 accepted된 뒤 workload가 ready여야 하고, controller의 route와 model provider·tool server에도 실제로 닿아야 한다.

사내에 자체 포털을 두면 dashboard는 운영자 콘솔로 남고, 우리 backend가 위의 두 경로를 소유한다. 그 연결 설계는 Agent 배포 플랫폼 10장에 있다.

이 실습에서 다루는 실행 수명주기

섹션 제목: “이 실습에서 다루는 실행 수명주기”

이 덱의 Declarative와 BYO는 구현 방식을 나누는 값이다. 둘 다 cluster에 배포하면 기본적으로 A2A 요청을 기다리는 Deployment가 된다. CLI에서 task 하나가 끝나도 Agent Pod가 그 task와 함께 종료되는 구조가 아니다.

개념이 덱에서의 범위
일반 Agent직접 만들고 Ready·invoke까지 확인
one-shot taskkagent invoke 한 번의 시작과 완료를 관찰
주기·event trigger다루지 않음. 외부 scheduler가 Agent를 호출하는 platform 영역
SandboxAgent11~12장에서 같은 cluster에 Substrate를 추가하고 직접 실행
AgentHarness첫 hands-on에서는 실행하지 않음. coding workspace 수요가 생길 때 13장의 후속 gate로 판단

구현 방식·호출 계기·상주 방식·상태·격리를 독립적으로 나누는 기준과 kagent resource 매핑은 Agent 배포 플랫폼 — kagent 아키텍처에서 이어 본다.

덱 셋의 경계

섹션 제목: “덱 셋의 경계”
질문볼 덱
Docker·kind·kubectl을 운영체제에서 어떻게 준비하나실습 환경
kagent를 설치하고 Agent를 실제로 어떻게 호출하나지금 보는 kagent 실습
회사 catalog·ACL·승인·배포 계약에 어떻게 편입하나Agent 배포 플랫폼

이 덱은 production 설치 runbook이 아니다. kind에서 계약을 확인하고, 10장에서 비운영 온프렘 staging에 승격하기 위한 values·인프라·acceptance test를 만든다. 실제 운영 변경 승인과 조직별 secret·registry·storage 절차는 각 플랫폼 runbook이 맡는다.

고정할 이름과 자원

섹션 제목: “고정할 이름과 자원”
항목실습 값이유
kind clusterkagent-lab삭제 대상을 이름으로 고정
kubectl contextkind-kagent-lab다른 cluster 오적용 방지
kagent namespacekagent공식 quickstart 기본값과 일치
custom Agentlab-readersample Agent와 구분
custom MCP servermcp-website-fetchertool workload를 따로 추적
fetch Agentsimple-fetch-agent4장의 MCP 실습 Agent를 sample·lab-reader와 구분
backend 적용 Agentbackend-reader사람의 kubectl과 backend ServiceAccount 경로를 구분
Substrate namespaceate-systemkagent namespace와 Substrate control/data plane을 구분
SandboxAgentsandbox-reader일반 lab-reader와 A/B 비교

기본 0~10장은 로컬 runtime에 CPU 4개, 메모리 8 GiB, 디스크 여유 15 GiB 이상을 권장한다. Substrate까지 실행할 때는 CPU 6개, 메모리 12 GiB, 디스크 여유 25 GiB를 학습용 출발값으로 잡는다. 제품의 고정 최소치가 아니므로 1장과 11장에서 실제 Pod request·Pending 원인을 보고 조정한다.

비밀과 비용 경계

섹션 제목: “비밀과 비용 경계”

모델 API key는 shell 환경 변수로만 넣고 Git 파일이나 command 예시의 literal로 남기지 않는다. 모델 호출에는 실제 비용이 들 수 있으므로 짧은 질문으로 시작하고 사용량 한도를 둔다. 두 경로 중 하나만 준비한다.

OpenAI API를 직접 쓰는 경우

섹션 제목: “OpenAI API를 직접 쓰는 경우”
터미널 창
read -s "OPENAI_API_KEY?OpenAI API key: "
export OPENAI_API_KEY

사내 LiteLLM을 쓰는 경우

섹션 제목: “사내 LiteLLM을 쓰는 경우”

provider의 원본 key가 아니라 이 실습 workload에 허용된 LiteLLM virtual key를 받는다. URL은 OpenAI-compatible API의 /v1까지, model은 LiteLLM이 공개한 model_name 또는 alias로 기록한다.

터미널 창
read -s "LITELLM_API_KEY?LiteLLM virtual key: "
export LITELLM_API_KEY
export LITELLM_BASE_URL="https://litellm.company.example/v1"
export LITELLM_MODEL="company-model-alias"

새 terminal에는 이 변수들이 자동으로 전달되지 않는다. key 값을 확인하려고 출력하지 말고 존재 여부만 본다.

터미널 창
if test -n "$OPENAI_API_KEY" || test -n "$LITELLM_API_KEY"; then
  echo "model API key is set"
fi

Tool 권한 경계

섹션 제목: “Tool 권한 경계”

첫 Agent에는 k8s_get_available_api_resources, k8s_get_resources처럼 조회 tool만 준다. apply, delete, shell 실행 같은 tool은 연결하지 않는다. LLM의 문장이 친절해도 tool이 가진 Kubernetes 권한보다 안전해지지는 않는다.

완료 체크

섹션 제목: “완료 체크”
  • 실습용 이름과 cleanup 대상을 말할 수 있다.
  • MCP는 Agent가 tool을 부르는 안쪽 계약, A2A는 client가 Agent를 부르는 바깥쪽 계약이라고 구분한다.
  • backend 관리 경로는 Kubernetes API, 호출 경로는 controller의 A2A endpoint라고 구분한다.
  • API key를 파일에 쓰지 않고 OpenAI 직접 연결과 LiteLLM gateway 연결을 구분한다.

참고 자료

섹션 제목: “참고 자료”
1. 전용 cluster와 kagent 설치context를 고정하고 demo profile을 설치한 뒤 controller·UI·CRD를 확인한다.