kagent와 kmcp가 맡는 자리
- kagent는
Agent리소스를 Deployment·Service로 바꾸고, 그 Agent를 부르는 주소를 controller에 열어 주는 Kubernetes controller다. - kmcp는
MCPServer리소스를 같은 방식으로 MCP 서버 Pod로 바꾼다. kagent chart에 기본 포함된다. - 경로는 둘이다. 리소스를 선언하는 경로는 Kubernetes API를, Agent를 호출하는 경로는 controller의
8083포트를 지난다. - UI와 CLI는 이 두 경로를 쓰는 클라이언트일 뿐이다. 없어도 Agent는 배포되고 호출된다.
이 장에서 처음 나오는 말5개
CRDCustom Resource Definition- Kubernetes API에
Agent같은 새 리소스 종류를 추가하는 확장 방식이다. kagent의 설정은 전부 이 리소스로 표현된다. controllerKubernetes Controller- 선언된 리소스와 실제 상태를 계속 비교해 맞추는 프로세스다.
Agent가 생기면 Deployment를 만들고, 지워지면 함께 지운다. MCPModel Context Protocol- Agent가 외부 도구를 호출하는 표준 프로토콜이다. 도구를 제공하는 쪽을 MCP 서버라 부른다.
A2AAgent-to-Agent Protocol- Agent를 호출하고 응답을 stream으로 받는 표준 프로토콜이다. kagent의 모든 Agent가 이 방식으로 호출된다.
ADKAgent Development Kit- Google이 만든 Agent 실행 프레임워크다. kagent의 Agent Pod 안에서 LLM 호출과 tool 호출을 반복하는 loop를 돌린다.
Agent를 Kubernetes에 직접 올리려면 Agent마다 Deployment·Service·ConfigMap을 만들고, 모델 API key를 연결하고, tool 서버 주소를 주입하고, 호출용 endpoint를 따로 설계해야 한다. Agent가 열 개가 되면 이 반복이 열 번이다. kagent는 이 반복을 “Agent 하나 = 리소스 하나”로 줄인다. Solo.io가 2025년에 만들었고 CNCF sandbox 프로젝트다.
이 페이지는 kagent가 클러스터에 무엇을 띄우고, 우리가 무엇을 선언하며, 요청이 어디로 들어오는지를 본다.
클러스터에 뜨는 것
섹션 제목: “클러스터에 뜨는 것”
공식 아키텍처 문서가 설명하는 구성 요소에 chart가 함께 설치하는 것을 더하면 다음과 같다.
| 구성 요소 | 하는 일 | 없으면 |
|---|---|---|
| controller | CRD를 감시해 Agent Pod를 만들고, 8083 포트에서 관리 API·A2A·MCP endpoint를 연다 | 아무것도 배포·호출되지 않는다 |
| Agent Pod | Agent 하나의 대화 loop를 돌린다. Declarative면 kagent의 ADK runtime, BYO면 우리 image | Agent가 없다 |
| kmcp controller | MCPServer를 감시해 MCP 서버 Pod와 Service를 만든다 | MCP 서버를 직접 Deployment로 띄워야 한다 |
| PostgreSQL | session·task·memory 같은 대화 상태를 저장한다 | 대화 이력이 남지 않는다 |
| UI | Agent 생성·채팅·tool 확인용 웹 화면. nginx가 /api를 controller로 넘긴다 | 운영 화면만 없다. Agent 동작과 무관 |
CLI (kagent, kmcp) | 설치, project 생성, manifest 생성, 호출을 돕는 로컬 도구 | 같은 일을 Helm·kubectl로 한다 |
chart는 여기에 예제 Agent 여러 개와 내장 tool 서버(kagent-tools)도 함께 설치한다. 이것은
설치 구성에서 끌지 말지 정한다.
우리가 선언하는 리소스
섹션 제목: “우리가 선언하는 리소스”kagent를 쓴다는 것은 아래 리소스를 만든다는 뜻이다. API reference의 resource type과 kmcp API를 합친 목록이다.
| 리소스 | API | 선언하는 것 | 이 덱의 페이지 |
|---|---|---|---|
Agent | kagent.dev/v1alpha2 | Agent 하나. 지시문·모델·tool 또는 container image | Agent |
ModelConfig | kagent.dev/v1alpha2 | 어떤 provider의 어떤 모델을 어떤 key로 부를지 | ModelConfig |
RemoteMCPServer | kagent.dev/v1alpha2 | 이미 떠 있는 MCP 서버의 URL | Tool 연결 |
MCPServer | kagent.dev/v1alpha1 | kmcp가 띄울 MCP 서버의 image·명령·전송 방식 | kmcp |
SandboxAgent | kagent.dev/v1alpha2 | Agent Substrate 위에서 격리 실행할 Agent | 세 실행 형태 |
AgentHarness | kagent.dev/v1alpha2 | OpenClaw·Hermes 같은 외부 coding agent의 sandbox | Hermes |
ModelProviderConfig도 있지만 UI에서 모델 목록을 자동으로 찾아오는 용도다. 이름만 알아 두면 된다.
리소스는 서로를 이름으로 참조한다. Agent가 ModelConfig와 tool 서버를 가리키고, controller가 그 참조를
풀어 Agent Pod의 설정으로 넣는다.
선언 경로와 호출 경로
섹션 제목: “선언 경로와 호출 경로”kagent와 주고받는 통신은 성격이 다른 두 갈래다. 둘을 섞으면 권한 설계가 꼬인다.
| 선언 경로 | 호출 경로 | |
|---|---|---|
| 하는 일 | Agent·tool·모델을 만들고 고친다 | 배포된 Agent에 질문을 보낸다 |
| 입구 | Kubernetes API (kubectl apply, GitOps 도구) | controller Service의 8083 포트 |
| 프로토콜 | Kubernetes 리소스 | A2A (JSON-RPC over HTTP, SSE stream) |
| 결과 확인 | 리소스의 status.conditions | 응답 stream |
| 누가 쓰나 | 배포 주체 — 우리 방식에서는 GitOps 도구 | 호출 주체 — 우리 방식에서는 backend |
호출 주소는 Agent마다 /api/a2a/{namespace}/{agent-name}/ 형태로 열린다
(A2A 예제). Agent Card는 그 아래
.well-known/agent.json에서 받는다.
# 설명용 — controller Service에 접근할 수 있는 곳에서curl http://kagent-controller.kagent:8083/api/a2a/agents/hr-helper/.well-known/agent.json같은 포트의 /mcp는 떠 있는 Agent 전체를 MCP 서버 하나로 노출한다. list_agents와 invoke_agent 두 tool이
있어서 Cursor 같은 MCP client가 kagent Agent를 부를 수 있다
(Agents via MCP). 편리하지만 모든 Agent를 한 번에
여는 문이므로, 이 포트에 누가 닿을 수 있는지가 곧 접근 제어다. 이 문제는
oauth2-proxy와 trusted-proxy 인증에서 다룬다.
kmcp의 자리
섹션 제목: “kmcp의 자리”kmcp는 별도 저장소의 하위 프로젝트지만 v0.7부터 kagent chart에 기본 포함된다. 역할은 둘로 나뉜다.
- 개발 도구:
kmcp init으로 MCP 서버 project를 만들고kmcp run으로 로컬에서 시험한다. - 배포 controller:
MCPServer리소스를 Deployment·Service·ConfigMap으로 바꾼다.
kagent 입장에서 MCP 서버는 “URL로 닿는 tool 제공자”일 뿐이다. kmcp가 띄운 서버든, 우리가 직접 Deployment로 띄운 서버든, 클러스터 밖의 서버든 Agent는 같은 방식으로 참조한다. kmcp는 그중 클러스터 안에서 띄우는 작업만 줄여 준다.
이해 확인
섹션 제목: “이해 확인”- UI Pod를 지우면 배포된 Agent의 A2A 호출은 어떻게 되는가? → 그대로 동작한다. UI는 controller의 클라이언트이고
호출 경로는 controller
8083과 Agent Pod만 지난다. Agent리소스를kubectl delete하면 무엇이 사라지는가? → controller가 만든 Deployment·Service가 함께 사라지고 호출 주소도 닫힌다.ModelConfig와 tool 서버 리소스는 별개라 남는다.