세 실행 형태 — Agent · SandboxAgent · AgentHarness
Agent는 Pod가 계속 떠 있는 Deployment다. 추가 설치 없이 동작하는 기본 형태다.SandboxAgent는 같은 spec을 Agent Substrate 위에서 실행한다. 쉬는 동안 snapshot으로 저장되고 호출되면 복원된다.AgentHarness는 kagent runtime 없이 OpenClaw·Hermes 같은 외부 coding agent의 sandbox를 만든다.- 뒤의 둘은 Agent Substrate라는 별도 runtime을 설치해야 한다. 필요가 확인되기 전에는
Agent로 시작한다.
이 장에서 처음 나오는 말5개
Agent Substrate- Agent를 Pod 하나에 묶지 않고, 미리 띄운 worker Pod 위에서 필요할 때만 올렸다 내리는 Kubernetes용 runtime이다.
actor- Substrate가 관리하는 Agent 인스턴스 하나다. 격리된 상태를 가지며 worker 위에 올라가 실행된다.
WorkerPool- actor를 올릴 worker Pod 묶음을 선언하는 Substrate 리소스다. 용량을 정한다.
snapshot- 쉬고 있는 actor의 상태를 압축해 object storage에 저장한 것이다. 다시 호출되면 여기서 복원한다.
gVisor- container와 host kernel 사이에 끼어 system call을 가로채는 sandbox runtime이다. 신뢰할 수 없는 코드를 격리한다.
지금까지 본 Agent는 Agent 하나가 Pod 하나를 계속 차지한다. Agent가 수백 개인데 대부분 하루에 몇 번만
호출된다면 쉬는 Pod가 자원을 계속 잡고 있게 된다. 또 Agent가 임의 코드를 실행한다면 일반 container 격리로는
부족할 수 있다. kagent는 이 두 문제에 대해 실행 형태를 따로 제공한다.
한눈에 비교
섹션 제목: “한눈에 비교”Agent | SandboxAgent | AgentHarness | |
|---|---|---|---|
| 실행되는 곳 | Deployment의 Pod | Substrate actor | Substrate actor |
| 안에서 도는 것 | kagent ADK runtime 또는 BYO image | 같음 | OpenClaw 또는 Hermes |
| 쉴 때 | Pod가 계속 떠 있다 | snapshot으로 저장하고 worker를 비운다 | actor 하나가 오래 유지된다 |
| 격리 | 일반 container | gVisor sandbox | gVisor sandbox |
| 추가 설치 | 없음 | Agent Substrate | Agent Substrate |
| 맞는 경우 | 기본 | 호출이 드문 Agent가 많거나 격리가 필요할 때 | 외부 coding agent를 그대로 쓰고 싶을 때 |
AgentHarness는 공식 문서가
명시하듯 Agent와 나란히 목록에 보이지만 같은 것이 아니다. kagent가 Agent의 내용을 정하지 않고
sandbox의 수명만 관리한다. 상세는 Hermes 페이지에서 다룬다.
SandboxAgent — spec은 같고 실행 방식만 다르다
섹션 제목: “SandboxAgent — spec은 같고 실행 방식만 다르다”SandboxAgent는 Agent와 spec이 같다. kind만 바꾸고 필요하면 spec.substrate로 배치를 정한다
(Sandboxed Agents).
# 발췌 — Agent와 달라지는 부분만apiVersion: kagent.dev/v1alpha2kind: SandboxAgentmetadata: name: hr-helper namespace: agentsspec: type: Declarative substrate: workerPoolRef: name: kagent-default declarative: runtime: go modelConfig: litellm-default systemMessage: ...v0.10부터 Go·Python Declarative와 BYO를 모두 지원한다. Go·Python Declarative는 대화 이력을 actor의
durableDir에 있는 SQLite에 저장하고, session 목록 조회를 위해 metadata만 PostgreSQL에 복사한다
(Agent Substrate — Declarative agents).
Agent Substrate가 하는 일
섹션 제목: “Agent Substrate가 하는 일”Agent Substrate는 Agent의 수명을 Pod와 분리한다.
- 호출이 오면 비어 있는 worker에 actor를 올린다. 쉬고 있던 actor는 snapshot에서 복원한다.
- 실행은 gVisor sandbox 안에서 한다.
- 쉬면 상태를 snapshot으로 저장하고 worker를 비운다. 그 worker는 다른 actor를 받는다.
그래서 worker Pod 몇 개가 그보다 훨씬 많은 Agent를 번갈아 실행할 수 있다. 문서가 드는 장점은 빠른 시작(새 Pod를 띄우지 않고 snapshot 복원), 자원 효율, 격리, 리소스 기반 선언 관리다.
얻는 대신 운영해야 하는 것
섹션 제목: “얻는 대신 운영해야 하는 것”Substrate는 kagent와 별개의 runtime이라 구성 요소가 따로 있다. 이름을 외울 필요는 없고, 운영 대상이 이만큼 늘어난다는 점만 본다.
| 층 | 구성 요소 | 역할 |
|---|---|---|
| control plane | ateapi, atecontroller | API·workflow(Redis 계열 저장소 사용), WorkerPool·ActorTemplate reconcile |
| data plane | atenet, atelet(DaemonSet), ateom | actor로 가는 트래픽 routing, node별 snapshot 전송, worker 감독 |
| storage | object storage | Zstd로 압축한 snapshot 저장 |
kagent 쪽에서는 Helm values로 연동을 켠다(Enable AgentHarness support).
# kagent chart values — Substrate 연동controller: substrate: enabled: true ateApiEndpoint: dns:///api.ate-system.svc:443 ateApiInsecure: truesubstrateWorkerPool: create: true replicas: 10.x 문서가 고정한 Substrate 버전은 v0.0.9다. kagent와 Substrate는 문서가 함께 확인한 조합으로 올리고, 한쪽만 최신으로 올리지 않는다.
어느 형태로 시작할 것인가
섹션 제목: “어느 형태로 시작할 것인가”Substrate를 도입하는 근거는 측정된 필요여야 한다.
| 상황 | 선택 |
|---|---|
| Agent 수가 적고 자주 호출된다 | Agent. 상주 Pod가 더 단순하고 응답이 일정하다 |
| Agent가 많고 대부분 쉬고 있다. 쉬는 Pod의 자원이 문제다 | SandboxAgent 검토. 절감량과 복원 지연을 재서 판단 |
| Agent가 신뢰할 수 없는 코드를 실행한다 | SandboxAgent 검토. gVisor 격리가 요구사항인지 확인 |
| OpenClaw·Hermes를 그대로 쓰고 싶다 | AgentHarness. Substrate가 필수다 |
같은 클러스터에서 Agent와 SandboxAgent를 나란히 띄워 비교하는 실습은
kagent 실습 덱의 Substrate 장에 있다(v0.9.9·Substrate v0.0.6 기준).
도입 여부의 판정 축은 사내 Agent 배포 플랫폼 덱의 결정 상태를 따른다.
이해 확인
섹션 제목: “이해 확인”Agent를SandboxAgent로 바꾸면 A2A 호출 주소와tools선언이 달라지는가? → spec이 같으므로tools는 그대로다. 달라지는 것은 실행 위치와 쉴 때의 동작이다. 첫 호출에 복원 시간이 더해질 수 있다.- Substrate를 설치하지 않은 클러스터에
AgentHarness를 만들면? → controller가 sandbox를 만들 수 없어 준비 상태가 되지 않는다. 연동이 꺼져 있으면AgentHarness는 동작하지 않는다.