3. 조회 전용 Declarative Agent

결론부터

Declarative Agent는 prompt 파일 하나가 아니라 명시적 runtime·model·instructions·tool reference를 묶은 Kubernetes resource다

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

ModelConfigModel Configuration

Agent가 사용할 model provider와 model 설정을 이름으로 참조하는 resource다.

systemMessageSystem Message

Agent의 역할·금지 행동·응답 형식을 model에 가장 먼저 주는 instructions다.

tool allowlistAllowed Tool Names

MCP server가 제공하는 기능 중 이 Agent가 실제로 쓸 이름만 고른 목록이다.

conditionKubernetes Condition

controller가 판단한 Accepted·Ready 같은 상태와 이유를 담는 표준 필드다.

연결할 resource 먼저 확인

demo profile이 만든 기본 model과 tool server 이름을 확인한다.

kubectl -n kagent get modelconfig default-model-config
kubectl -n kagent get remotemcpserver kagent-tool-server

1장에서 default-model-config 자체를 LiteLLM으로 바꿨다면 기존 sample Agent와 이번 lab-reader가 함께 전환된다. 별도 litellm-default를 만들었다면 아래 Agent manifest의 modelConfig도 그 이름으로 바꾼다.

kubectl -n kagent get agents \
  -o custom-columns='AGENT:.metadata.name,MODEL_CONFIG:.spec.declarative.modelConfig'

둘 중 하나가 없다면 아래 manifest를 적용하지 않는다. 설치 version에서 이름이 바뀌었는지 실제 목록과 release notes를 확인한다.

ModelConfig가 model 전환 단위다

Agent마다 key와 URL을 복제하지 않는다. 한 ModelConfig를 여러 Agent가 참조하면 model·gateway 변경을 한 곳에서 적용할 수 있다. 반대로 blast radius를 줄이려면 새 ModelConfig를 만든 뒤 Agent 하나에서 invoke까지 검증하고 나머지 reference를 옮긴다.

Agent 만들기

다음 Agent는 Kubernetes 조회 tool 둘만 참조한다. 변경 tool을 prompt로 금지하는 데 그치지 않고 allowlist에서 뺀다. a2aConfig.skills에는 외부 client가 Agent Card에서 볼 조회 능력 설명을 하나 넣는다. 이는 metadata이며 tool을 새로 실행하거나 권한을 추가하지 않는다.

kubectl apply -f - <<'EOF'
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: lab-reader
  namespace: kagent
spec:
  description: Read-only lab agent that explains resources in the kagent namespace.
  type: Declarative
  declarative:
    runtime: go
    modelConfig: default-model-config
    systemMessage: |-
      You are a read-only Kubernetes lab assistant.

      Rules:
      - Inspect resources only in the namespace explicitly requested by the user.
      - Never claim that you changed, deleted, restarted, or applied a resource.
      - Use a tool for facts about the current cluster; do not guess.
      - If a request requires a mutation, explain that this lab agent has no mutation tool.
      - Summarize the tool evidence before giving a conclusion.
    tools:
      - type: McpServer
        mcpServer:
          apiGroup: kagent.dev
          kind: RemoteMCPServer
          name: kagent-tool-server
          toolNames:
            - k8s_get_available_api_resources
            - k8s_get_resources
    a2aConfig:
      skills:
        - id: inspect-kubernetes-resources
          name: Inspect Kubernetes resources
          description: Read and explain Kubernetes resources in a requested namespace.
          tags:
            - kubernetes
            - read-only
          examples:
            - List the Pods in the kagent namespace and cite the tool evidence.
          inputModes:
            - text
          outputModes:
            - text
EOF

UI로 만들어도 같은 resource다

dashboard의 Agents → New Agent는 이 manifest와 같은 필드 — model, instructions, tool — 를 채우는 화면이다. 이 장은 재현 가능한 선언을 남기려고 manifest를 정본으로 쓴다. UI로 만들었더라도 결과는 같은 Agent resource이고, 아래 확인 명령이 똑같이 적용된다.

Accepted와 Ready 기다리기

1. resource가 생겼는지 본다.

   kubectl -n kagent get agent lab-reader

2. condition 두 개를 기다린다.

   kubectl -n kagent wait \
     --for=condition=Accepted agent/lab-reader --timeout=2m
   kubectl -n kagent wait \
     --for=condition=Ready agent/lab-reader --timeout=3m

3. 최종 spec과 status를 함께 읽는다.

   kubectl -n kagent get agent lab-reader -o yaml

Accepted=True는 controller가 선언을 받아들였다는 뜻이고, Ready=True는 생성된 deployment가 준비됐다는 뜻이다. 둘은 model 호출 성공까지 보장하지 않으므로 실제 invoke가 마지막 검증이다.

조회와 거부를 각각 시험하기

실제 사용자가 만나는 경로대로 dashboard에서 먼저 시험한다. Agent 목록에서 lab-reader를 열고 두 질문을 차례로 보낸다.

1. 허용된 조회 — “kagent namespace의 Pod를 나열하고 tool 근거를 같이 보여줘.”
2. 일부러 보내는 변경 요청 — “kagent namespace의 Pod 하나를 삭제해 줘.”

첫 질문에서는 2장처럼 tool arguments와 result를 펼쳐 근거를 본다. 두 번째 요청은 실제 삭제 tool을 호출할 수 없어야 한다. prompt의 거부 문장도 중요하지만, 더 강한 경계는 Agent spec에 delete tool 자체가 없다는 사실이다. 실제 Pod 수가 그대로인지 kubectl get pods로 확인한다.

같은 시험을 CLI로 재현한다. controller port-forward가 없다면 별도 terminal에서 다시 연다.

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

kagent invoke -n kagent -a lab-reader -S \
  -t "List the Pods in the kagent namespace and cite the tool evidence."
kagent invoke -n kagent -a lab-reader -S \
  -t "Delete one Pod in the kagent namespace."

한 필드씩 읽는 법

필드	지금 고정한 것
type: Declarative	kagent가 표준 runtime을 구성
runtime: go	문서·version별 기본값 변화에 기대지 않고 실행 engine을 고정
modelConfig	model credential과 provider 세부를 Agent와 분리
systemMessage	역할과 행동 원칙
mcpServer	tool을 발견할 endpoint resource
toolNames	server 전체가 아니라 조회 기능 둘만 허용
a2aConfig.skills	Agent Card에 공개할 AgentSkill metadata—실행 tool이 아님
status.conditions	controller가 선언을 실제 상태로 바꾼 결과

안 될 때 먼저 볼 것

증상	확인
Accepted wait가 timeout	kubectl -n kagent describe agent lab-reader의 conditions·Events — modelConfig·mcpServer 이름 오타
Accepted=True인데 Ready timeout	생성된 Deployment와 Pod Events, image pull
invoke가 connection refused	controller port-forward terminal이 살아 있는지
model authentication 오류	참조한 ModelConfig와 Secret — 1장에서 LiteLLM으로 바꿨다면 그 설정 그대로인지
조회 tool이 실행되지 않음	toolNames 철자와 kagent-tool-server 상태

완료 체크

• lab-reader가 Accepted=True, Ready=True다.
• dashboard chat에서 조회·거부를 시험했고 같은 호출을 CLI로 재현했다.
• 조회 요청에는 tool evidence가 있고 결과가 kubectl과 맞는다.
• 삭제 요청 뒤 실제 resource가 변하지 않았다.
• a2aConfig.skills와 MCP toolNames를 서로 다른 선언으로 구분한다.
• cluster와 Agent는 다음 장에서 재사용한다.

참고 자료

• kagent Agent 개념 — instructions·tool·runtime과 Declarative spec
• 첫 MCP tool — Agent v1alpha2와 RemoteMCPServer reference
• kagent API reference — Agent, ModelConfig, RemoteMCPServer schema

4. MCP tool server 붙이기새 MCPServer를 배포하고 한 tool만 allowlist에 넣어 Agent의 능력이 어디서 생기는지 본다.