kagent-dev

# Kagent Development Guide

## Quick Reference

### Most Common Commands

```bash
# Local Kind cluster setup
make create-kind-cluster
make helm-install  # Builds images and deploys to Kind

# Code generation (after CRD type changes)
make controller-manifests  # generate + copy CRDs to helm (recommended)
make -C go generate         # DeepCopy methods only

# sqlc (after editing go/core/internal/database/queries/*.sql)
cd go/core/internal/database && sqlc generate  # regenerate gen/ — commit both

# Build & test
make -C go test               # Unit tests (includes golden file checks)
make -C go e2e                # E2E tests (needs KAGENT_URL)
make -C go lint               # Go lint
make -C python lint           # Python lint

# Golden file regeneration (after translator changes)
UPDATE_GOLDEN=true make -C go test

# Set KAGENT_URL for E2E tests
export KAGENT_URL="http://$(kubectl get svc -n kagent kagent-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}'):8083"

# Check cluster status
kubectl get agents.kagent.dev -n kagent
kubectl get pods -n kagent
```

### Repository Structure

```
kagent/
├── go/                      # Go workspace (go.work: api, core, adk)
│   ├── api/                 # Shared types module
│   │   ├── v1alpha2/        # Current CRD types (agent_types.go, etc.)
│   │   ├── adk/             # ADK config types (types.go) — flows to Python runtime
│   │   ├── database/        # database models
│   │   ├── httpapi/         # HTTP API types
│   │   └── config/crd/bases/ # Generated CRD YAML
│   ├── core/                # Infrastructure module
│   │   ├── cmd/             # Controller & CLI binaries
│   │   ├── internal/        # Controllers, HTTP server, DB impl
│   │   │   └── controller/translator/agent/  # Translator files:
│   │   │       ├── adk_api_translator.go     # Main: TranslateAgent(), builds K8s objects
│   │   │       ├── deployments.go            # resolvedDeployment struct, resolve*Deployment()
│   │   │       ├── template.go               # Prompt template resolution
│   │   │       └── testdata/                 # Golden test inputs/ and outputs/
│   │   └── test/e2e/        # E2E tests
│   └── adk/                 # Go Agent Development Kit
│
├── python/                  # Python workspace (UV)
│   ├── packages/            # UV workspace packages (kagent-adk, etc.)
│   └── samples/             # Example agents (adk/, crewai/, langgraph/, openai/)
│
├── helm/                    # Kubernetes deployment
│   ├── kagent-crds/         # CRD chart (install first)
│   └── kagent/              # Main app chart
│
└── ui/                      # Next.js web interface
```

**Module Boundaries:**
- **go/api/** - Shared types used by both core and adk. Import from other modules OK.
- **go/core/** - Infrastructure code. Should NOT import from go/adk.
- **go/adk/** - Agent runtime. Can import from go/api, not from go/core.

---

## Adding CRD Fields

Adding a field propagates from the type definition through codegen, translator, and tests.

### Step-by-Step Workflow

0. **Check if the field already exists**

   Before writing any code, search existing types — many common fields are already implemented. The Agent CRD already has fields for image, resources, env, replicas, imagePullPolicy, tolerations, service accounts, volumes across `SharedDeploymentSpec`, `DeclarativeAgentSpec`, and related structs.

   ```bash
   grep -rn "fieldName\|FieldName" go/api/v1alpha2/
   ```

1. **Edit the CRD type definition**

   File: `go/api/v1alpha2/agent_types.go` (or the relevant CRD type file)

   Choose the right struct:
   - `DeclarativeAgentSpec` — agent behavior (system message, model, tools, runtime config)
   - `SharedDeploymentSpec` — deployment concerns shared by Declarative + BYO (image, resources, env, replicas, imagePullPolicy)
   - `DeclarativeDeploymentSpec` / `ByoDeploymentSpec` — type-specific deployment config

   ```go
   // NewField is a description of what this field does
   // +optional
   // +kubebuilder:validation:Enum=value1;value2;value3
   NewField *string `json:"newField,omitempty"`
   ```

   Use pointers for optional primitives (to distinguish "unset" from zero value), value types for slices/maps.

2. **Run code generation**

   ```bash
   make controller-manifests
   ```

   This runs `make -C go generate` (DeepCopy methods + CRD YAML) and copies CRD YAML to `helm/kagent-crds/templates/`. Run steps separately if needed.

3. **Update the translator (if field affects K8s resources)**

   Two key files depending on what your field does:

   - **`deployments.go`** — for fields affecting the Deployment spec (image, resources, env, volumes, replicas). Add to `resolvedDeployment` struct, wire in `resolveInlineDeployment()` / `resolveByoDeployment()`.

   - **`adk_api_translator.go`** — for fields affecting ADK config JSON, Service, or overall translation. Main method: `TranslateAgent()`.

   Pattern (check-if-set, else use default):
   ```go
   if spec.Declarative.NewField != nil {
       // use *spec.Declarative.NewField
   }
   ```

   See `references/translator-guide.md` for detailed patterns.

4. **If the field flows to the Python runtime**

   Some fields need to reach the Python agent process (e.g., `stream`, `executeCodeBlocks`):
   - `go/api/adk/types.go` — add field to `AgentConfig`
   - `python/packages/kagent-adk/src/kagent/adk/types.py` — add corresponding field

5. **Regenerate golden files**

   ```bash
   UPDATE_GOLDEN=true make -C go test
   git diff go/core/internal/controller/translator/agent/testdata/outputs/
   ```

   Review the diff — only your expected changes should appear. If unexpected changes show up, fix the translator logic rather than committing bad golden files.

6. **Add E2E test**

   File: `go/core/test/e2e/invoke_api_test.go`

   Tests follow: create resources → wait for Ready → send A2A messages → verify → clean up. Look at existing tests for patterns.

7. **Run tests**

   ```bash
   make -C go test    # Unit tests