2. sample Agent 첫 호출

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

결론부터

첫 호출의 성공 조건은 답변 한 줄이 아니라 어떤 tool이 어떤 인자로 실행되어 어떤 결과를 돌려줬는지 확인하는 것이다

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

sessionConversation Session: 여러 turn을 같은 대화 문맥으로 묶는 실행 단위다.
tool callTool Invocation: model이 답을 만들기 위해 이름과 인자를 정해 외부 기능을 호출한 사건이다.
artifactA2A Artifact: Agent task 결과가 text·file 같은 part로 담겨 돌아오는 출력 단위다.

1장에서 default-model-config를 사내 LiteLLM으로 바꿨다면 이 장의 첫 호출이 그 전환의 마지막 검증이다. tool 호출까지 성공해야 gateway 연결, model alias, upstream의 tool calling 지원이 모두 확인된 것이다.

호출 전에 상태 보기

dashboard를 열지 않은 terminal에서 sample Agent를 찾는다.

kubectl -n kagent get agents

CLI는 기본적으로 로컬 controller endpoint를 보므로 port-forward가 필요하다. 별도 terminal에서 실행하고 유지한다.

kubectl -n kagent port-forward svc/kagent-controller 8083:8083

이제 다른 terminal에서 kagent가 보는 Agent 목록을 비교한다.

kagent get agent -n kagent

Kubernetes API의 resource 목록과 kagent API의 Agent 목록에 같은 이름이 보이는지가 첫 연결 확인이다. 1장에서 열어 둔 dashboard의 Agent 목록은 같은 kagent API를 보는 세 번째 창이다.

dashboard에서 첫 질문

dashboard에서 Kubernetes 관련 sample Agent를 연다. 닫았다면 1장의 dashboard 열기의 운영체제별 방법으로 다시 연다.

다음처럼 조회만 필요한 질문을 보낸다.

kagent namespace에서 실행 중인 Pod를 이름과 상태만 표로 보여줘.
변경 작업은 하지 마.

응답만 읽지 말고 펼칠 수 있는 Arguments와 Results를 연다.
tool 이름이 Kubernetes 조회 계열인지, namespace 인자가 kagent인지, result의 Pod가 실제 목록과 맞는지 비교한다.
터미널 창
```
kubectl -n kagent get pods
```

질문에 cluster 상태가 들어 있어도 model이 원래 알고 답한 것이 아니다. model이 tool을 선택하고, tool server가 Kubernetes API에서 현재 값을 읽고, model이 그 결과를 문장으로 정리한다.

CLI에서 같은 Agent 호출

앞에서 선택한 Agent 이름을 <sample-agent> 자리에 넣는다.

kagent invoke \
  --agent <sample-agent> \
  --namespace kagent \
  --task "List pods in the kagent namespace. Do not modify anything." \
  --stream

CLI 출력 형식은 길 수 있다. 최종 text뿐 아니라 task·artifact·tool event가 구분되는지 본다. dashboard와 CLI는 화면이 다르지만 kagent-controller의 같은 Agent를 호출한다.

답변을 검증하는 세 값

층	확인할 값	거짓 양성을 막는 이유
Agent	호출한 namespace와 이름	비슷한 sample Agent 혼동 방지
tool	tool 이름·arguments·result	model의 추측과 실제 조회 구분
cluster	`kubectl get` 결과	자연어 요약의 누락·오독 확인

Agent가 “정상”이라고 말해도 실제 Pod 상태가 다르면 cluster가 원본이다. 반대로 tool result 자체가 오류라면 문장 품질을 조정하기 전에 tool 연결과 RBAC를 고친다.

작은 비교 실험

같은 Agent에 두 질문을 차례로 보낸다.

“kagent namespace의 Pod 수를 알려줘.”
“그중 이름에 controller가 들어간 Pod만 설명해줘.”

같은 session이면 두 번째 질문의 “그중”이 앞 turn을 가리킬 수 있다. 새 chat을 열면 같은 표현이 모호해진다. 이 차이로 Agent resource와 conversation session이 별도 lifecycle이라는 점을 확인한다.

안 될 때 먼저 볼 것

증상	확인
CLI가 `localhost:8083`에 연결 못 함	controller port-forward terminal이 살아 있는지
Agent 목록은 있지만 호출 실패	`kubectl get agent <이름> -n kagent -o yaml`의 conditions
model authentication 오류	key 자체를 출력하지 말고 model config와 Secret 존재·controller log 확인
Kubernetes tool이 거부됨	선택한 tool 이름과 kagent tool server 상태·RBAC 확인
답변과 실제 상태가 다름	tool result와 `kubectl get`을 먼저 비교
LiteLLM 전환 뒤 호출이 `400`	model alias 뒤 upstream의 function/tool calling·`tool_choice: auto` 지원
LiteLLM 전환 뒤 연결 오류	`default-model-config`의 `openAI.baseUrl` 오타와 gateway `/v1/models` 재확인

완료 체크

dashboard에서 tool arguments와 result를 펼쳐 봤다.
CLI에서 같은 Agent를 호출했다.
Agent 응답, tool result, Kubernetes 실제 상태를 서로 다른 증거로 구분한다.
LiteLLM으로 전환했다면 tool 호출 성공으로 1장에서 미룬 전환 검증을 끝냈다.

참고 자료

kagent Quick Start — dashboard와 sample Agent·CLI 호출
kagent get — Agent·session·tool 조회
kagent invoke — task·stream·session flag

3. 조회 전용 Declarative Agentsample을 쓰는 데서 벗어나 model·prompt·tool allowlist를 직접 선언한다.