Skip to content

Commit 8728936

Browse files
jsonmp-k8jsonmp-k8
committed
docs: expand AGENTS.md with code reuse, naming, and architecture sections
- Add code reuse section to discourage duplicating functions/utilities - Add naming conventions section requiring descriptive variable and function names across all languages - Expand repo structure with docker, contrib, design, docs, scripts, test - Add per-language development details (Go modules, Python tooling, UI stack) - Add CI/CD pipeline breakdown and architectural patterns (MCP, memory, SDK) - Fix make lint description to clarify it only covers Go + Python - Add separate UI lint command (npm -C ui run lint) Signed-off-by: Jaison Paul <paul.jaison@gmail.com>
1 parent 548e20e commit 8728936

File tree

1 file changed

+174
-111
lines changed

1 file changed

+174
-111
lines changed

‎AGENTS.md‎

Lines changed: 174 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,15 @@
1-
# CLAUDE.md - Kagent Development Guide
1+
# AGENTS.md - Kagent Repository Guide for AI Agents
22

3-
This document provides essential guidance for AI agents working in the kagent repository.
4-
5-
---
6-
7-
## Development Workflow Skill
8-
9-
**For detailed development workflows, use the `kagent-dev` skill.** The skill provides comprehensive guidance on:
10-
11-
- Adding CRD fields (step-by-step with examples)
12-
- Running and debugging E2E tests
13-
- PR review workflows
14-
- Local development setup
15-
- CI failure troubleshooting
16-
- Common development patterns
17-
18-
The skill includes detailed reference materials on CRD workflows, translator patterns, E2E debugging, and CI failures.
3+
This document provides instructions and context for AI coding agents working in the kagent repository.
194

205
---
216

227
## Project Overview
238

24-
**Kagent** is a Kubernetes-native framework for building, deploying, and managing AI agents.
9+
**Kagent** is a Kubernetes-native framework for building, deploying, and managing AI agents. It is in **alpha stage (v0.x.x)**.
2510

2611
**Architecture:**
12+
2713
```
2814
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
2915
│ Controller │ │ HTTP Server │ │ UI │
@@ -37,73 +23,93 @@ The skill includes detailed reference materials on CRD workflows, translator pat
3723
└─────────────┘ └──────────────┘
3824
```
3925

40-
**Current Version:** v0.x.x (Alpha stage)
26+
- **Go** — Kubernetes controllers, HTTP server, CLI, database layer, Go ADK
27+
- **Python** — Agent runtime, AI/ML logic, LLM integrations, Python ADK
28+
- **TypeScript** — Next.js web UI only
4129

4230
---
4331

4432
## Repository Structure
4533

4634
```
4735
kagent/
48-
├── go/ # Go workspace (go.work)
49-
│ ├── api/ # Shared types: CRDs, ADK types, DB models, HTTP client
50-
│ ├── core/ # Infrastructure: controllers, HTTP server, CLI
51-
│ └── adk/ # Go Agent Development Kit
52-
├── python/ # Agent runtime and ADK
53-
│ ├── packages/ # UV workspace packages (kagent-adk, etc.)
54-
│ └── samples/ # Example agents
55-
├── ui/ # Next.js web interface
56-
├── helm/ # Kubernetes deployment charts
57-
│ ├── kagent-crds/ # CRD chart (install first)
58-
│ └── kagent/ # Main application chart
59-
└── .claude/skills/kagent-dev/ # Development skill
36+
├── go/ # Go workspace (go.work)
37+
│ ├── api/ # Shared types: CRDs (v1alpha2), DB models, HTTP client SDK
38+
│ ├── core/ # Kubernetes controllers, HTTP server, CLI
39+
│ │ └── test/e2e/ # End-to-end tests (SQLite + PostgreSQL)
40+
│ └── adk/ # Go Agent Development Kit
41+
├── python/ # Python workspace (UV)
42+
│ ├── packages/ # kagent-adk, kagent-core, kagent-skills, etc.
43+
│ └── samples/ # Example agents
44+
├── ui/ # Next.js web interface
45+
├── helm/ # Kubernetes deployment charts
46+
│ ├── kagent-crds/ # CRD chart (install first)
47+
│ └── kagent/ # Main application chart
48+
├── docker/ # Dockerfiles for all images
49+
├── contrib/ # Community addons, tools, integrations
50+
├── design/ # Architecture enhancement proposals (EP-*.md)
51+
├── docs/ # Documentation
52+
├── examples/ # Sample configurations
53+
├── scripts/ # Build and deployment scripts
54+
├── test/ # Integration tests
55+
├── .github/workflows/ # CI/CD pipelines
56+
├── Makefile # Top-level build orchestration
57+
├── DEVELOPMENT.md # Detailed development setup
58+
└── CONTRIBUTING.md # Contribution standards
6059
```
6160

6261
---
6362

6463
## Language Guidelines
6564

66-
### When to Use Each Language
65+
| Language | Use For | Do Not Use For |
66+
|----------------|------------------------------------------------------|--------------------------------------|
67+
| **Go** | K8s controllers, CLI, core APIs, HTTP server, DB | Agent runtime, LLM integrations, UI |
68+
| **Python** | Agent runtime, ADK, LLM integrations, AI/ML logic | K8s controllers, CLI, infrastructure |
69+
| **TypeScript** | Web UI components and API clients only | Backend logic, controllers, agents |
6770

68-
| Language | Use For | Don't Use For |
69-
|----------|---------|---------------|
70-
| **Go** | K8s controllers, CLI tools, core APIs, HTTP server, database layer | Agent runtime, LLM integrations, UI |
71-
| **Python** | Agent runtime, ADK, LLM integrations, AI/ML logic | Kubernetes controllers, CLI, infrastructure |
72-
| **TypeScript** | Web UI components and API clients only | Backend logic, controllers, agents |
71+
---
7372

74-
**Rule of thumb:** Infrastructure in Go, AI/Agent logic in Python, User interface in TypeScript.
73+
## Build & Test Commands
74+
75+
| Task | Command |
76+
|--------------------------|----------------------------------------|
77+
| Build all images | `make build` |
78+
| Build CLI | `make build-cli` |
79+
| Run all tests | `make test` |
80+
| Run Go E2E tests | `make -C go e2e` |
81+
| Lint Go + Python | `make lint` |
82+
| Lint Go only | `make -C go lint` |
83+
| Lint UI | `npm -C ui run lint` |
84+
| Generate CRD code | `make -C go generate` |
85+
| Create Kind cluster | `make create-kind-cluster` |
86+
| Deploy kagent | `make helm-install` |
87+
| Helm template tests | `make helm-test` |
88+
| CVE scan | `make audit` |
89+
| Access UI | `kubectl port-forward -n kagent svc/kagent-ui 3000:8080` |
90+
91+
Before submitting changes, run `make lint` for Go/Python changes, and for UI changes run `npm -C ui run lint` and the relevant UI tests.
7592

7693
---
7794

78-
## Core Conventions
95+
## Go Development
7996

80-
### Error Handling
97+
### Module Layout
8198

82-
**Go:**
83-
```go
84-
// Always wrap errors with context using %w
85-
if err != nil {
86-
return fmt.Errorf("failed to create agent %s: %w", name, err)
87-
}
88-
```
99+
The Go code lives under `go/` with three modules managed by `go.work`:
89100

90-
**Controllers:**
91-
```go
92-
// Return error to requeue with backoff
93-
if err != nil {
94-
return ctrl.Result{}, fmt.Errorf("reconciliation failed: %w", err)
95-
}
96-
```
101+
- **`go/api`** — Foundation layer. CRD types (`v1alpha2`), database models, HTTP client SDK, shared utilities.
102+
- **`go/core`** — Infrastructure layer. Kubernetes controller (`cmd/controller`), HTTP server, MCP integration, metrics, E2E tests.
103+
- **`go/adk`** — Agent Development Kit. Agent runner, session management, skills, models, memory, telemetry.
97104

98-
### Testing
105+
### Conventions
99106

100-
**Required for all PRs:**
101-
- ✅ Unit tests for new functions/methods
102-
- ✅ E2E tests for new CRD fields or API endpoints
103-
- ✅ Mock external services (LLMs, K8s API) in unit tests
104-
- ✅ All tests passing in CI pipeline
107+
- Wrap errors with context: `fmt.Errorf("failed to create agent %s: %w", name, err)`
108+
- Controllers should return errors to requeue with backoff.
109+
- Run `gofmt -w` on changed files before committing.
110+
- Run `golangci-lint run` before submitting (CI enforces this).
111+
- Use table-driven tests:
105112

106-
**Go testing pattern (table-driven):**
107113
```go
108114
func TestSomething(t *testing.T) {
109115
tests := []struct {
@@ -115,7 +121,6 @@ func TestSomething(t *testing.T) {
115121
{name: "valid input", input: "foo", want: "bar", wantErr: false},
116122
{name: "invalid input", input: "", want: "", wantErr: true},
117123
}
118-
119124
for _, tt := range tests {
120125
t.Run(tt.name, func(t *testing.T) {
121126
got, err := Something(tt.input)
@@ -130,85 +135,143 @@ func TestSomething(t *testing.T) {
130135
}
131136
```
132137

133-
### Commit Messages
138+
- Go tests run with `-race` flag in CI.
139+
- E2E tests run against both SQLite and PostgreSQL.
140+
141+
---
142+
143+
## Python Development
144+
145+
- Python 3.10+ required.
146+
- Uses **UV** for dependency management across workspace packages.
147+
- **Ruff** for linting and formatting (120-char line limit).
148+
- **Pytest** for testing (async auto mode).
149+
- CI tests across Python 3.10-3.13.
150+
- Key packages: `kagent-adk`, `kagent-core`, `kagent-skills`, `kagent-crewai`, `kagent-langgraph`, `kagent-openai`.
151+
152+
---
153+
154+
## UI Development
155+
156+
- **Next.js** with React, TypeScript, Tailwind CSS, Radix UI.
157+
- **Zod** for validation, **Zustand** for state management, **React Hook Form** for forms.
158+
- Do not use `any` type in TypeScript.
159+
- ESLint for linting, Jest for unit tests, Cypress for E2E tests.
160+
161+
---
162+
163+
## API Versioning
164+
165+
- **v1alpha2** — Current. All new features go here.
166+
- **v1alpha1** — Legacy/deprecated. Do not modify unless fixing critical bugs.
167+
168+
Key CRDs: `Agent`, `ModelConfig`, `ModelProviderConfig`, `RemoteMCPServer`.
134169

135-
Use **Conventional Commits** format:
170+
Breaking changes are acceptable in alpha versions.
171+
172+
---
173+
174+
## CI/CD Pipeline
175+
176+
The main CI workflow (`.github/workflows/ci.yaml`) runs on pushes/PRs to `main` and release branches:
177+
178+
1. **Go** — Unit tests with race detection, E2E tests (SQLite + PostgreSQL), golangci-lint
179+
2. **Python** — Tests on 3.10-3.13, ruff linting, format validation
180+
3. **UI** — ESLint, Jest unit tests
181+
4. **Helm** — Chart unit tests, manifest verification
182+
5. **Docker** — Multi-platform builds (amd64, arm64) for controller, ui, app, cli, golang-adk, skills-init
183+
184+
Additional workflows: image scanning, release tagging, stale issue management.
185+
186+
---
187+
188+
## Commit Messages
189+
190+
Use **Conventional Commits**:
136191

137192
```
138193
<type>: <description>
139194
140195
[optional body]
196+
197+
Signed-off-by: Name <email>
141198
```
142199

143-
**Types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`
200+
Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`
144201

145-
**Examples:**
146-
```
147-
feat: add support for custom service account in agent CRD
148-
fix: enable usage metadata in streaming OpenAI responses
149-
docs: update CLAUDE.md with testing requirements
150-
```
202+
All commits require `Signed-off-by` trailer (DCO). Use `git commit -s` or run `make init-git-hooks`.
151203

152204
---
153205

154-
## API Versioning
206+
## Testing Requirements
155207

156-
- **v1alpha2** (current) - All new features go here
157-
- **v1alpha1** (legacy/deprecated) - Minimal maintenance only
208+
All PRs must include:
158209

159-
Breaking changes are acceptable in alpha versions.
210+
- Unit tests for new functions/methods
211+
- E2E tests for new CRD fields or API endpoints
212+
- Mocked external services (LLMs, K8s API) in unit tests
213+
- All tests passing in CI
160214

161215
---
162216

163-
## Best Practices
217+
## Key Architectural Patterns
218+
219+
### MCP Integration
220+
- Reference-based architecture (no embedded details in CRDs)
221+
- Supports MCPServer CRD, Kubernetes Services, and RemoteMCPServer
222+
- Protocols: SSE and STREAMABLE_HTTP
223+
- Built-in tools: Kubernetes, Istio, Helm, Argo, Prometheus, Grafana, Cilium
224+
225+
### Memory System
226+
- PostgreSQL + pgvector for production, Turso/libSQL for development
227+
- 768-dimensional embeddings with cosine similarity search (threshold 0.3)
228+
- Dual save: explicit (via tools) + implicit (auto-save every 5 turns)
229+
- 15-day memory expiration with intelligent retention
164230

165-
### Do's ✅
231+
### HTTP Client SDK
232+
- Located in `go/api/client/`
233+
- Covers Agent, Session, Tool, Memory, Model, ModelConfig, ModelProviderConfig operations
166234

167-
- Read existing code before making changes
168-
- Follow the language guidelines (Go for infra, Python for agents, TS for UI)
169-
- Write table-driven tests in Go
170-
- Wrap errors with context using `%w`
171-
- Use conventional commit messages
172-
- Mock external services in unit tests
173-
- Update documentation for user-facing changes
174-
- Run `make lint` before submitting
235+
---
175236

176-
### Don'ts ❌
237+
## Code Reuse
177238

178-
- Don't add features beyond what's requested (avoid over-engineering)
179-
- Don't modify v1alpha1 unless fixing critical bugs (focus on v1alpha2)
180-
- Don't vendor dependencies (use go.mod)
181-
- Don't commit without testing locally first
182-
- Don't use `any` type in TypeScript
183-
- Don't skip E2E tests for API/CRD changes
184-
- Don't create new MCP servers in the main kagent repo
239+
- Before writing new code, search the codebase for existing functions, utilities, and patterns that already solve the problem.
240+
- Do not duplicate logic. If similar functionality exists, refactor it into a shared helper or reuse the existing implementation.
241+
- Shared Go utilities belong in `go/api/` (types, models, client SDK) — not duplicated across `go/core/` and `go/adk/`.
242+
- Shared Python utilities belong in `kagent-core` — not duplicated across other packages.
243+
- If you find duplicated code while working on a change, consolidate it as part of your PR when the scope is reasonable.
185244

186245
---
187246

188-
## Quick Reference
247+
## Naming Conventions
189248

190-
| Task | Command |
191-
|------|---------|
192-
| Create Kind cluster | `make create-kind-cluster` |
193-
| Deploy kagent | `make helm-install` |
194-
| Build all | `make build` |
195-
| Run all tests | `make test` |
196-
| Run E2E tests | `make -C go e2e` |
197-
| Lint code | `make -C go lint` |
198-
| Generate CRD code | `make -C go generate` |
199-
| Access UI | `kubectl port-forward -n kagent svc/kagent-ui 3000:8080` |
249+
- Use **descriptive variable and function names** across all languages. Names should clearly convey purpose and intent.
250+
- Avoid abbreviations and single-letter names (except loop counters like `i`, `j`). Use `agentConfig` not `ac`, `modelProvider` not `mp`, `sessionID` not `sID`.
251+
- Function names should describe what they do: `createAgentFromSpec` not `makeAgent`, `validateModelConfig` not `checkCfg`.
252+
- Go: Follow standard Go naming (camelCase for unexported, PascalCase for exported). Receiver names can be short (1-2 chars) per Go convention.
253+
- Python: Use snake_case for functions/variables, PascalCase for classes.
254+
- TypeScript: Use camelCase for functions/variables, PascalCase for components and types.
200255

201256
---
202257

203-
## Additional Resources
258+
## What Not to Do
204259

205-
- **Development setup:** See [DEVELOPMENT.md](DEVELOPMENT.md)
206-
- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md)
207-
- **Architecture:** See [docs/architecture/](docs/architecture/)
208-
- **Examples:** Check `examples/` and `python/samples/`
260+
- Do not add features beyond what is requested (avoid over-engineering).
261+
- Do not modify v1alpha1 unless fixing critical bugs.
262+
- Do not vendor dependencies (use go.mod).
263+
- Do not commit without running tests locally.
264+
- Do not use `any` type in TypeScript.
265+
- Do not skip E2E tests for API/CRD changes.
266+
- Do not create new MCP servers in the main kagent repo.
267+
- Do not duplicate existing functions or utilities — reuse what already exists.
209268

210269
---
211270

212-
**Project Version:** v0.x.x (Alpha)
271+
## Additional Resources
213272

214-
For questions or suggestions about this guide, please open an issue or PR.
273+
- [DEVELOPMENT.md](DEVELOPMENT.md) — Detailed local development setup
274+
- [CONTRIBUTING.md](CONTRIBUTING.md) — Contribution process and standards
275+
- [docs/architecture/](docs/architecture/) — Architecture documentation
276+
- [design/](design/) — Enhancement proposals (EP-*.md)
277+
- [examples/](examples/) and [python/samples/](python/samples/) — Sample configurations

0 commit comments

Comments
 (0)