How kagent-dev/kagent works
1. Repository shape
- This is a multi-language monorepo for a Kubernetes-native AI agent platform.
- The main deliverables are a Go control plane, a Next.js UI, several Python agent/runtime libraries and samples, Helm charts, and reusable MCP/tool server packages.
2. Primary runtime boundary: Kubernetes
- The system is centered on Kubernetes custom resources, not a standalone app server.
- Core resources include Agents, ModelConfigs, ToolServers, RemoteMCPServers, Memories, SandboxAgents, and AgentHarnesses.
- Most user actions ultimately translate into CRD creation/update, which the controller turns into Kubernetes workloads and supporting objects.
3. Control plane in Go
- The Go code under go/core is the operational center of the project.
- It contains the Kubernetes controller, HTTP API server, A2A transport/compat layers, database layer, MCP handling, sandbox backend logic, and shared utilities.
- The controller watches CRDs and reconciles them into Deployments, Services, Secrets, RBAC, routes, and status updates.
4. API and persistence
- go/core/internal/httpserver exposes the backend API used by the UI and by other clients.
- go/core/internal/database plus go/core/pkg/migrations manage persistent state such as sessions, tasks, feedback, memory, model/tool metadata, and shares.
- This persistence layer is separate from Kubernetes state; it stores conversational and platform data that should survive pod restarts independently of CRD reconciliation.
5. Agent execution boundary
- The actual agent runtime is split from the controller.
- Go packages under go/adk and Python packages under python/packages/kagent-adk, kagent-openai, kagent-crewai, kagent-langgraph, and kagent-core implement agent execution adapters, event conversion, sessions, HITL/approval flows, model bindings, and tool invocation.
- The runtime talks to external LLM providers and to tool services, while the controller remains responsible for declarative lifecycle management.
6. Tooling and MCP integration
- Tool access is modeled around MCP servers and tool servers.
- The repo includes reusable tool-server charts and templates in contrib/tools and helm/tools, plus controller logic for MCP-related CRDs and reconciliation.
- Agents can consume local or remote MCP servers, and the platform supports tool sharing across agents.
7. A2A and nested-agent communication
- There is a distinct agent-to-agent boundary implemented through A2A components in both Go and Python.
- go/core/internal/a2a and related Python modules handle remote agent calls, passthroughs, task/result aggregation, and compatibility with A2A protocol versions.
- This enables nested agents, remote tool/agent delegation, and sandboxed transport paths separate from normal tool calls.
8. Sandbox and substrate layer
- The sandbox/substrate code is a major architectural subsystem.
- go/core/pkg/sandboxbackend and go/core/internal/controller/*substrate* manage isolated execution environments and special agent harness flows.
- This layer is used when agents need controlled network, credential, or gateway behavior, and it is distinct from ordinary Kubernetes workloads.
9. UI as a management surface
- ui/ is a Next.js front end that drives the platform.
- It provides agent creation, model/provider setup, MCP management, prompts, sessions/chat, substrate status, and onboarding flows.
- The UI mostly orchestrates backend actions through API routes and action modules rather than owning business logic itself.
10. Authentication and access control
- The platform has explicit auth and proxy-auth support in the Go HTTP layer and corresponding UI auth context.
- There are signals of OIDC/proxy integration, session sharing, and user identity propagation through the API and chat/session flows.
- RBAC and service accounts are part of the deployed architecture, especially for controller actions and tool/server access.
11. Deployment packaging
- Helm charts under helm/ package the controller, UI, PostgreSQL, CRDs, and tool-server deployments.
- contrib/ contains additional add-ons, memory backend examples, and standalone tool-server manifests.
- The repo also includes devcontainer, Dockerfiles, and scripts to support local development and production image builds.
12. Validation, testing, and release flow
- The repo is heavily tested with Go unit/integration/e2e tests, Python unit/e2e tests, UI tests, and GitHub Actions workflows.
- There are dedicated test fixtures for agent translation, CRD reconciliation, MCP tooling, auth, upgrades, and UI behavior.
- Architecture-wise, this matters because many subsystems are validated independently: Kubernetes reconciliation, runtime adapters, UI actions, database migrations, and sample agent packages.
13. Typical data flow
- A user uses the UI or CLI to define an agent, model provider, memory, or tool server.
- The API/controller persists metadata and applies CRDs into Kubernetes.
- Reconciliation materializes workloads and secrets/RBAC.
- The runtime executes the agent, calls LLM providers and MCP tools, and emits events, traces, session updates, and feedback into the API/database.
14. External dependencies that matter
- The platform depends on Kubernetes, PostgreSQL, OpenTelemetry, and one or more LLM providers such as OpenAI, Anthropic, Azure OpenAI, Bedrock, Ollama, Gemini/Vertex AI, or SAP AI Core.
- It also integrates with MCP ecosystems and optional observability add-ons like Prometheus/Grafana.
- These are not incidental libraries; they define the main operational boundaries of the system.
Main entry points: controller Controller · app Next.js UI · adk Python ADK · helm Helm
Components 19
Go
Control plane, API, CLI, and shared runtime packages.
- Controller · Watches CRDs and materializes workloads, services, RBAC, secrets, routes, and status.
go/core/internal/controller - Translator · Converts agent specs into deployable Kubernetes manifests and runtime config.
go/core/internal/controller/translator/agent - API Server · Backend API for the UI and clients, including auth and platform operations.
go/core/internal/httpserver - Database · Persistent storage for sessions, tasks, feedback, memories, shares, and metadata.
go/core/internal/database - Migrations · Database migration set for core and vector-backed persistence.
go/core/pkg/migrations - A2A · Agent-to-agent compatibility, passthroughs, and remote task/result handling.
go/core/internal/a2a - MCP · MCP handling across controller, API, and runtime tool invocation paths.
go/core/internal/mcp - Sandbox · Substrate and sandbox lifecycle for controlled execution and gateway behavior.
go/core/pkg/sandboxbackend - Go ADK · Go agent runtime support for sessions, models, tools, telemetry, and A2A.
go/adk/pkg - CLI · Command-line workflows for agent init, deploy, invoke, and MCP scaffolding.
go/core/cli
Python
Agent runtimes, adapters, and samples.
- Python ADK · Python execution adapter for sessions, approvals, memory, MCP, A2A, and model bindings.
python/packages/kagent-adk/src/kagent/adk - Python Core · Shared Python core for A2A config, HITL utilities, and tracing.
python/packages/kagent-core/src/kagent/core - Framework Adapters · Execution adapters for OpenAI, CrewAI, LangGraph, and related agent frameworks.
python/packages - Samples · Reference agents and framework samples used for onboarding and validation.
python/samples
UI
Next.js management surface.
- Next.js UI · Operator console for agents, models, MCP, prompts, sessions, auth, and substrate.
ui/src/app - UI Logic · Action modules, contexts, hooks, and API bindings used by the UI.
ui/src/lib
Platform
Kubernetes packaging, CRDs, and deployment assets.
- CRDs · Custom resources for agents, model configs, tool servers, memories, and harnesses.
go/api/config/crd/bases - Helm · Charts for controller, UI, PostgreSQL, CRDs, agents, and tool servers.
helm - Tool Servers · Reusable MCP/tool server charts, templates, and example deployments.
contrib/tools
Connections 24
- Controller → CRDs: watches · Reconciles custom resources into Kubernetes objects.
- Translator → Controller: feeds manifests · Produces workload and runtime specifications consumed by reconciliation.
- API Server → Database: reads/writes · Persists conversational and platform state.
- API Server → Controller: mutates state · API actions create or update CRDs and related platform objects.
- Controller → Sandbox: provisions · Creates substrate and isolated execution environments when needed.
- Controller → MCP: reconciles · Manages MCP-related tool server resources and status.
- Go ADK → A2A: implements · Provides nested-agent and remote-call support in Go.
- Go ADK → MCP: invokes tools · Resolves tool registries and MCP-backed calls at runtime.
- Go ADK → Database: stores sessions · Uses persistent state for sessions, tasks, feedback, and memory.
- Python ADK → Python Core: builds on · Shares config, A2A, HITL, and tracing primitives.
- Python ADK → MCP: calls tools · Consumes local and remote MCP servers.
- Python ADK → A2A: delegates · Supports remote agent calls and task aggregation.
- Framework Adapters → Python ADK: extends · Framework-specific execution adapters plug into the shared runtime.
- Next.js UI → UI Logic: uses · Pages are driven by shared actions, contexts, hooks, and utilities.
- Next.js UI → API Server: calls API · Primary management surface for platform operations.
- Next.js UI → CRDs: manages · Creates and edits agents, models, tools, and harness resources.
- Next.js UI → A2A: chat routes · Handles A2A and sandbox chat flows in the interface.
- CLI → Helm: packages · CLI workflows align with deployable charts and manifests.
- CLI → Controller: targets · Drives local and cluster workflows for agent deployment.
- Helm → CRDs: installs · Ships the API types and custom resource definitions.
- Helm → Controller: deploys · Deploys controller, RBAC, and supporting services.
- Helm → Next.js UI: deploys · Packages the front end alongside the control plane.
- Tool Servers → MCP: templates · Reusable MCP server charts and manifests.
- Samples → Python ADK: demonstrates · Reference agent projects exercise the runtime adapters.