kagent development guide

Use docs/architecture and the current implementation to understand component boundaries. Keep each PR focused on the requested change and its necessary dependencies.

Read the root AGENTS.md and applicable nested guides before editing. Directory-specific validation, persistence, transport, and UI rules live there; use this skill for development workflows and the remaining specialized guidance.

Architecture

• Agent, Harness, and AgentTemplate are api.kagent.dev/v1alpha3 CRDs under go/api/v1alpha3.
• Session is stored in PostgreSQL and exposed through gRPC, not Kubernetes.
• Upstream A2A owns public interaction and history semantics.
• Substrate Actors are the only runtime compute path.
• DurableDir owns private runtime state needed across lifecycle operations and snapshots.
• kagent, Codex, and Claude are release-blocking Harness adapters.

The public API must not acquire Kubernetes scheduling, service-account, workload deployment, arbitrary runtime-container, channel, profile, or generic extension fields.

Repository map

go/api/v1alpha3/                 CRD types and validation
helm/kagent-crds/templates/      generated CRDs and Helm packaging
proto/                           protobuf and Buf inputs
go/api/gen/                      generated Go protobuf code
go/core/internal/grpcserver/     gRPC transport and policy
go/core/internal/service/        transport-independent services
go/core/internal/database/       Inline pgx SQL and private typed rows
go/core/pkg/migrations/          PostgreSQL migrations
go/core/internal/controller/     CRD reconciliation and preparation
go/adk/                          Go runtime
python/packages/                 Python runtime packages
ui/                              static Vite browser UI
helm/                            installation charts

Workflow