5. CLI와 A2A로 Agent 호출하기

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

결론부터

dashboard는 한 client일 뿐이며 외부 호출 계약은 kagent controller가 제공하는 Agent Card와 A2A task endpoint다

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

Agent CardA2A Agent Card: Agent 이름·설명·URL·capability·skill을 client가 발견하도록 공개한 JSON 문서다.
AgentSkillA2A Agent Skill: a2aConfig.skills에 선언하고 Agent Card에 실리는 능력 메타데이터다. 실행 tool이 아니다.
taskA2A Task: client가 Agent에 맡긴 작업과 진행·완료·실패 상태를 묶는 단위다.
streamingStreaming Response: 완료될 때까지 기다리지 않고 event나 text 조각을 순서대로 받는 방식이다.

MCP와 A2A를 방향으로 구분하기

사용자 또는 다른 Agent ── A2A ──▶ kagent Agent ── MCP ──▶ tool server

A2A는 Agent를 호출되는 서비스로 만든다. MCP는 그 Agent가 바깥 기능을 호출하는 client가 되게 한다. 둘 다 JSON 기반 protocol이라는 이유로 같은 역할로 보면 연결 방향과 권한 주체가 뒤섞인다.

controller endpoint 열기

이미 port-forward 중이면 하나만 유지한다.

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

이 tunnel은 로컬 8083을 cluster의 controller service 8083으로 연결한다. terminal을 점유하는 것이 정상이다.

Agent Card 읽기

다른 terminal에서 lab-reader의 well-known endpoint를 요청한다.

curl --fail --silent --show-error \
  http://localhost:8083/api/a2a/kagent/lab-reader/.well-known/agent.json

JSON에서 다음을 찾는다.

필드	답하는 질문
`name`, `description`	어떤 Agent인가
`url`	task를 어디로 보내나
`capabilities.streaming`	stream을 지원하나
`defaultInputModes`, `defaultOutputModes`	어떤 content type을 받고 내보내나
`skills`	client가 발견할 수 있게 어떤 능력을 설명했나

card가 열린다는 것은 route와 discovery가 동작한다는 뜻이다. model과 tool 호출까지 성공했다는 뜻은 아니다.

AgentSkill metadata와 실행 tool 구분하기

3장의 a2aConfig.skills는 Agent Card에 실리는 AgentSkill metadata다. kagent Agents 개념은 이 하위 유형을 Actions-to-actions (A2A) skills라고 부르지만, protocol 이름의 A2A는 계속 Agent2Agent다. 이 덱은 두 의미를 섞지 않도록 a2aConfig.skills의 값을 AgentSkill metadata라고 부른다.

위에서 읽은 Agent Card의 skills 배열에 다음 ID가 있는지 본다.

inspect-kubernetes-resources

그런 다음 Kubernetes resource에 실제로 허용한 MCP tool 이름을 다시 출력한다.

kubectl -n kagent get agent lab-reader \
  -o jsonpath='{range .spec.declarative.tools[*].mcpServer.toolNames[*]}{.}{"\n"}{end}'

기대값은 3장에서 허용한 둘뿐이다.

k8s_get_available_api_resources
k8s_get_resources

Agent Card에는 발견용 능력 설명이 추가되었지만 MCP tool allowlist는 늘지 않았다. 반대로 metadata가 실제 instructions·tool·runtime으로 수행할 수 없는 능력을 선전하면 discovery와 실행이 엇갈린다. 포털은 AgentSkill을 실행 권한으로 해석하지 않고, publication 전에 실제 호출로 설명과 실행이 맞는지 검증한다.

CLI invoke와 연결하기

Agent 목록에서 이름을 다시 확인한다.
터미널 창
```
kagent get agent -n kagent
```

streaming task를 보낸다.

kagent invoke -n kagent -a lab-reader -S \
  -t "How many Services exist in the kagent namespace? Use a tool and explain the evidence."

완료 뒤 session 목록을 확인한다.
터미널 창
```
kagent get session -n kagent
```
출력된 session ID 하나를 상세 조회한다.
터미널 창
```
kagent get session <session-id> -n kagent
```

CLI가 URL 구성과 A2A message 형식을 대신 만들지만, 앞에서 읽은 Agent Card의 endpoint와 capability를 사용한다.

실패 위치를 나누기

확인 결과	좁혀지는 위치
port-forward 자체 실패	Service·Pod·로컬 포트
card가 404	namespace·Agent 이름·A2A route
card는 성공, task가 실패	Agent workload·model·tool·session
task는 성공, tool result 오류	MCP server·외부 대상·RBAC
tool result 성공, 답변이 부정확	instructions·model·result 요약

이 순서로 보면 “Agent가 안 돼요”를 한 덩어리로 controller log부터 뒤지는 일을 줄일 수 있다.

완료 체크

lab-reader Agent Card를 JSON으로 읽었다.
Agent Card의 AgentSkill metadata와 MCP tool allowlist가 다른 것을 확인했다.
Agent-to-Agent protocol과 kagent 문서의 Actions-to-actions skill 표현을 구분한다.
discovery 성공과 실제 task 성공을 구분한다.
CLI invoke 뒤 session을 별도 resource로 조회했다.
MCP와 A2A의 연결 방향을 설명할 수 있다.

참고 자료

A2A Agent 예제 — Agent Card path와 dashboard·CLI·A2A client 호출
kagent invoke — task·file·session·stream flag
A2A protocol AgentSkill — Agent Card에 실리는 능력 metadata의 표준 schema

6. 상태와 로그로 실패 진단하기일부러 잘못된 model reference를 만들고 condition에서 controller log까지 좁혀 간다.