6. 상태와 로그로 실패 진단하기

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

결론부터

Agent가 안 보이면 dashboard를 새로 고치기 전에 선언·reconcile·workload·dependency·invoke 순서로 실패 범위를 좁힌다

이 장에서 처음 나오는 말4개

reconcileReconciliation Loop: controller가 원하는 spec과 실제 상태를 비교해 계속 맞추는 반복 과정이다.
AcceptedAccepted Condition: Agent 선언이 유효하고 controller가 처리할 수 있다고 판정한 상태다.
ReadyReady Condition: Agent의 생성된 deployment가 요청을 받을 준비가 됐다고 판정한 상태다.
EventsKubernetes Events: scheduler·kubelet·controller가 resource에 관해 남긴 짧은 상태 변화 기록이다.

정상 Agent의 증거 모으기

먼저 정상인 lab-reader를 기준선으로 기록한다.

kubectl -n kagent get agent lab-reader -o yaml
kubectl -n kagent get pods
kubectl -n kagent get events --sort-by=.lastTimestamp

Agent YAML에서는 metadata.generation, status.observedGeneration, status.conditions를 함께 본다. observedGeneration이 현재 generation보다 작다면 controller가 최신 spec을 아직 처리하지 않은 상태일 수 있다.

의도적으로 잘못된 Agent 만들기

정상 Agent를 망가뜨리지 않고 별도 resource로 실패를 만든다. 존재하지 않는 ModelConfig를 참조한다.

kubectl apply -f - <<'EOF'
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: broken-model-agent
  namespace: kagent
spec:
  description: Intentionally broken agent for condition inspection.
  type: Declarative
  declarative:
    runtime: go
    modelConfig: model-config-does-not-exist
    systemMessage: You are intentionally misconfigured for a lab.
EOF

조건에서 로그까지 좁히기

사용자가 보는 화면부터 확인한다

dashboard의 Agent 목록에서 broken-model-agent가 어떻게 보이는지 본다. 목록에 없거나 상태 표시만 있을 뿐, 화면은 원인까지 말해 주지 않는다. 사용자가 실패를 처음 만나는 곳은 UI지만 진단은 여기서 내려간다.
resource status를 읽는다
터미널 창
```
kubectl -n kagent \
  get agent broken-model-agent -o yaml
```
status.conditions의 type, status, reason, message를 찾는다. 정확한 문구를 외우는 것이 아니라 missing model reference를 가리키는지 본다.

describe로 Events까지 합쳐 본다

kubectl -n kagent \
  describe agent broken-model-agent

controller가 같은 이름을 어떻게 기록했는지 찾는다

kubectl -n kagent \
  logs deployment/kagent-controller --since=10m | grep broken-model-agent

이름이 log에 없으면 filter를 빼고 최근 100줄을 읽는다.

kubectl -n kagent \
  logs deployment/kagent-controller --tail=100

실패 resource만 지운다

kubectl -n kagent \
  delete agent broken-model-agent

이 실패는 Pod log보다 먼저 Agent condition에서 드러나야 한다. 유효하지 않은 dependency 때문에 workload가 만들어지지 않았다면 찾을 Agent Pod 자체가 없을 수 있다.

진단 사다리

순서	질문	명령의 대상
1. 선언	resource가 원하는 namespace와 이름에 있나	`kubectl get agent`
2. reconcile	최신 generation이 accepted됐나	Agent conditions
3. workload	생성된 Pod가 ready인가	Pod·Deployment·Events
4. dependency	model·MCP·Secret·network에 닿나	참조 resource와 각 log
5. invoke	card·task·session 중 어디서 깨지나	curl·kagent CLI

위에서 처음 실패한 층을 고친다. model credential 오류인데 UI를 재설치하거나, invalid spec인데 Agent Pod를 찾는 식으로 층을 건너뛰지 않는다.

자주 만나는 증상

증상	먼저 볼 것
Agent가 dashboard에 없음	Agent `Accepted` condition과 controller log
`Accepted=True`, `Ready=False`	생성 workload·Pod Events·image pull
`Ready=True`, model 호출 실패	ModelConfig·Secret reference·provider network
Agent 호출 성공, tool 실패	MCPServer status·tool workload·egress·RBAC
간헐적 timeout	controller·Agent·tool 각 latency와 resource saturation

bug report를 만들 때

공식 CLI는 진단 묶음을 생성할 수 있다.

kagent bug-report

외부에 첨부하기 전 파일을 직접 열어 API key·Secret·authorization header·prompt·내부 URL이 포함되지 않았는지 검사한다. 자동 수집됐다는 이유로 안전하게 redaction됐다고 가정하지 않는다.

완료 체크

정상 Agent와 잘못된 Agent의 condition을 비교했다.
dashboard에서 보이는 실패 증상과 resource status의 원인(missing ModelConfig)을 구분했다.
실패 resource만 삭제했고 lab-reader는 그대로 ready다.
다음 장을 위해 cluster를 유지한다.

참고 자료

kagent debug — Agent status, controller·UI log, debug log와 bug report
Kubernetes API conventions — conditions — generation과 condition 해석

7. Backend walking skeletonNode/TypeScript backend가 Kubernetes API로 Agent를 관리하고 controller A2A route로 호출하는 두 경로를 연결한다.