8. kagent 아키텍처
이 장에서 처음 나오는 말4개
CRDCustom Resource Definition- Kubernetes API에 Agent 같은 새 resource type을 추가하는 확장 방식이다.
controllerKubernetes Controller- 선언된 Agent 상태와 실제 Deployment 상태를 계속 비교해 맞추는 process다.
ADKAgent Development Kit- Google이 만든 Agent 실행 프레임워크. kagent의 기본 engine이 이 위에서 대화 loop를 돌린다.
A2AAgent-to-Agent- Agent를 외부에서 호출하고 응답을 stream으로 받는 표준 protocol이다.
앞선 7장까지가 제품 밖의 계약이었다면 8~11장은 그 계약을 실제로 실행하는 첫 target 후보인 kagent v0.9.9를 다룬다. 이 장은 구성 요소와 실행 형태만 고정한다. resource 필드는 9장, 사내 frontend·backend와의 연결은 10장, adapter 구현과 권한 경계는 11장으로 넘긴다.
전체 중 kagent의 자리
섹션 제목: “전체 중 kagent의 자리”
kagent는 Agent를 Kubernetes resource로 표현하고 model과 MCP tool 연결을 함께 관리한다. GitOps·namespace·
ServiceAccount·NetworkPolicy 같은 기존 Kubernetes 운영 모델과 가까운 것이 장점이다.
그림에서 dashboard·CLI가 점선인 이유는 중요하다. 이 도구는 controller의 내부 API와 설치·진단 command를 사용해 resource-derived 상태와 chat을 보여 주지만, 사내 backend가 의존할 versioned 계약은 아니다. 사내 포털을 따로 만들면 dashboard는 최종 사용자 화면이 아니라 플랫폼 팀의 운영 콘솔로 남는다. 이 경계는 10장에서 다시 다룬다.
구성 요소
섹션 제목: “구성 요소”| 구성 요소 | 하는 일 | 사내 플랫폼에서의 취급 |
|---|---|---|
| controller | CRD를 watch해 workload와 status를 조정하고 8083 A2A route를 Agent runtime으로 중계한다 | 관리 adapter는 Kubernetes API, invocation adapter는 controller A2A로 나누어 대화한다 |
| engine (app) | Agent의 대화 loop를 실행한다. model 호출, tool 호출, session 관리 | 일반 Agent Pod 또는 Substrate actor 안에서 돈다. 직접 조작하지 않는다 |
| dashboard | 웹 UI. Agent 생성·대화·상태 확인 | 운영자 콘솔. 최종 사용자에게 열지 않는다 |
| CLI | kagent install, kagent invoke 등 또 하나의 입구 | 설치·진단용. 서버 코드에서 shell로 부르지 않는다 |
| kmcp | MCP server 개발·배포용 하위 프로젝트. 기본 설치에 포함 | 사용자 MCP 배포 경로 후보 |
공식 architecture 문서는 controller를 Go로 쓰인 Kubernetes controller로, engine을 “Agent의 대화 loop를 실행하는 핵심 구성 요소”로 설명한다.
두 engine runtime
섹션 제목: “두 engine runtime”Declarative Agent는 runtime 필드로 engine 구현을 고른다. 공식 Agents 문서는 Python을 기본값으로 설명하지만,
이 덱은 alpha schema의 암묵적 기본값에 기대지 않고 모든 manifest에 값을 명시한다. 주요 차이는 시작 시간·자원과
사용 가능한 framework integration이다.
| 명시할 runtime | 문서상 시작 시간 | 특징 |
|---|---|---|
| Python ADK | 약 15초 | LangGraph·CrewAI·OpenAI 통합을 함께 쓸 수 있다 |
| Go ADK | 약 2초 | 자원 사용이 적다. pinned Substrate hands-on은 이 runtime으로 검증한다 |
Agent 수가 많아지면 시작 시간과 idle resource가 비용이 된다. 사내에서 Agent를 수백 개 등록받을 계획이라면 runtime 선택 기준과 지원 feature를 platform policy로 고정하고, upgrade 때 두 runtime의 contract test를 다시 돈다.
세 가지 실행 형태
섹션 제목: “세 가지 실행 형태”Agent.spec.type의 Declarative·BYO는 logic과 runtime을 누가 공급하는지를 구분한다.
한편 실행이 상주하는 방식은 Agent·SandboxAgent·AgentHarness라는 서로 다른 Kubernetes kind로 갈린다.
이 둘은 다른 축이다.
Agent | SandboxAgent | AgentHarness | |
|---|---|---|---|
| 실행 위치 | Deployment Pod | Agent Substrate actor | Agent Substrate actor |
| 상주 방식 | 항상 떠 있음 | idle이면 snapshot으로 내려감 | 장기 세션 유지 |
| 안의 내용 | kagent engine 또는 BYO image | API는 Declarative·BYO를 표현하며, pinned 실습은 Go Declarative | OpenClaw·Hermes 같은 외부 coding agent |
| 푸는 문제 | 항상 호출 가능한 Agent | idle compute 회수 | coding agent workspace lifecycle |
| 전제 인프라 | 없음 | gVisor node·object storage | gVisor node·object storage |
Agent Substrate의 설치·worker pool·snapshot A/B는
kagent 실습 덱 11~13장에서 같은 cluster의 일반 Agent와 직접 비교한다.
이 덱에서는 “언제 검토 대상이 되는가”만 기억하면 된다 — 등록된 Agent 수가 동시 활성 수를 크게 웃돌거나,
gVisor 격리가 필요한 실행 class가 생겼을 때다. coding workspace는 AgentHarness라는 더 넓은 별도 신뢰 경계다.
실행 수명주기는 다른 resource와 trigger로 표현한다
섹션 제목: “실행 수명주기는 다른 resource와 trigger로 표현한다”플랫폼이 받는 요구(“매일 아침 실행”, “한 번만 실행”)를 kagent에 그대로 옮길 수 있는 필드는 없다. 아래처럼 다른 resource와 외부 trigger로 번역한다.
| 원하는 실행 성격 | kagent에서의 대응 | process와 state |
|---|---|---|
| 항상 호출 가능한 일반 Agent | Agent의 Declarative 또는 BYO | Deployment replica가 A2A 요청을 기다림 |
| idle compute를 회수하는 Declarative Agent | SandboxAgent + Agent Substrate | idle actor를 snapshot하고 요청 때 복원 |
| 장기 coding 환경 | AgentHarness + Agent Substrate | filesystem·process를 가진 원격 sandbox를 ACP로 연결 |
| 한 번의 task | kagent invoke 또는 A2A task | task만 끝나며 일반 Agent Deployment는 남음 |
| 일정·event 기반 실행 | 외부 scheduler·event consumer가 A2A invoke | core Agent spec에는 schedule이 없음 |
SandboxAgent는 일반 Agent와 비슷한 선언을 Agent Substrate actor로 실행해 idle 자원을 줄인다. 논리적 Agent가
매번 사라지는 Job은 아니며 snapshot에서 다시 이어지는 suspendable 방식이다. AgentHarness는 OpenClaw·Hermes
같은 coding agent의 장기 workspace를 관리하며 일반 Agent와도 다르다.
주기 작업은 platform의 Trigger를 Kubernetes CronJob, Argo Workflows 같은 scheduler에 매핑하고, 실행 시
승인된 Agent의 A2A endpoint를 호출하는 구성이 기본이다. 정말 process까지 매번 종료해야 한다면 Job 안에서
Agent code를 직접 실행할 수 있지만, 이때는 kagent Agent의 Ready endpoint·session 관리 모델을 재사용하지
못한다. 이 차이를 capability로 드러내는 방법은
11장에 있다.
제품 중립 분류는 Agent 종류의 여섯 요구 차원에서, trigger 계약은 제품 밖의 domain model에서 정의한다.
8장 요약
섹션 제목: “8장 요약”- kagent의 관리 진실은 Kubernetes API의 resource이고 dashboard·CLI는 backend 계약이 아닌 운영 도구다.
- controller는 resource를 조정하고
8083A2A route를 Agent Pod 또는 Substrate actor로 중계한다. - engine runtime은 Python ADK(문서상 약 15초)와 Go ADK(약 2초) 중에서 고르고 manifest에 명시한다.
Declarative/BYO는 공급 주체 축,Agent/SandboxAgent/AgentHarness는 상주 방식 축이다.- 일정·event 실행은 kagent 밖의 scheduler가 A2A로 invoke하는 형태로 번역한다.
참고 자료
섹션 제목: “참고 자료”- kagent Architecture — controller·engine·CLI·dashboard의 역할 구분
- kagent A2A 예제 — controller
8083의 Agent Card·task route - kagent API reference —
Agent·SandboxAgent·AgentHarnessschema와 API version - kagent Agent Substrate — worker pool·actor·snapshot 구조
- kagent 실습 덱 — 전용 kind cluster에서 설치·backend CRD/A2A·보안·온프렘·Substrate를 직접 확인