DOCSEARCHbyAlgolia
Submit Docs

kagent Documentation

repository·main·Indexed 25 days ago

https://github.com/kagent-dev/kagent

A Kubernetes-native framework for building and managing AI agents. kagent allows developers to define agents, LLM configurations, and tools as Kubernetes custom resources, integrating AI orchestration into cloud-native workflows. It features support for the Model Context Protocol (MCP), the A2A communication protocol, and Human-in-the-Loop (HITL) tool approval flows. The system consists of a central kagent-controller, Agent Pods using Python or Go ADK Runtimes, and MCP Tool Servers.

Tokens
60.3K
Snippets
127
Records
372
Agent score
86%

What's inside kagent

  1. Overview of ACP Sandbox Images

    main

    The ACP (Agent Client Protocol) sandbox images are a prototype family for kagent's ACP integration. Every image uses acp-shim as the ENTRYPOINT, which exposes a stdio ACP agent over a WebSocket at ws://0.0.0.0:9000/acp. This endpoint is reachable via Substrate's atenet ingress.

    Agent Layer Contract:

    • The ENTRYPOINT is always acp-shim.
    • The agent layer is provided as CMD arguments after --, or via the ACP_SHIM_CHILD environment variable.

  2. Overview of OIDC Authentication Integration (EP-476)

    main

    KAgent is transitioning from an unsecure authentication mechanism (UnsecureAuthenticator) to an enterprise-grade OIDC (OpenID Connect) client. This integration allows KAgent to work with any compliant OIDC provider (such as Keycloak, Auth0, Okta, Azure AD, Google, or Dex) instead of relying on unvalidated user IDs provided via query parameters or headers.

    Key Features:

    • Standardized Authentication: Uses OAuth2/OIDC flows for secure, token-based identity.
    • External Identity Management: KAgent does not manage users locally; it relies on external providers for identity and user management.
    • Session Management: Supports secure token storage, refreshing, and revocation.
    • RBAC Foundation: Enables group-based role mapping using OIDC claims.
    • Multi-Interface Support: Supports web flows for UI users and device code or browser flows for CLI users.

  4. Overview of kagent

    main
    kagent is a Kubernetes-native framework designed for building, deploying, and managing AI agents. It leverages Kubernetes orchestration to treat AI agents and their tools as standard Kubernetes resources, allowing developers to use familiar kubectl workflows for AI agent lifecycle management.

  5. Overview of Kagent Go packages

    main

    The go/ directory is a single Go module (github.com/kagent-dev/kagent/go) comprising three main package trees:

    • api: Contains shared types including CRD definitions, ADK model types, database models, and the HTTP client SDK.
    • core: Provides infrastructure such as Kubernetes controllers, the HTTP server, the CLI, and database implementations.
    • adk: The Go Agent Development Kit (ADK) used for building and running agents.

  6. Use the Model Context Protocol (MCP) for Tools

    main

    Agents in Kagent connect to tool servers using the MCP protocol.

    Implementation Details:

    • Transport Types: Supports Streamable HTTP (preferred, single multiplexed endpoint) and SSE (legacy).
    • Discovery: The RemoteMCPServer CRD defines tool server locations. The controller discovers tools during reconciliation and stores them in the database.
    • Runtime Connection: The agent runtime connects to MCP servers at startup using configuration from config.json.
    • Execution: Tool calls during a conversation are dispatched via MCP to the designated tool server.

  7. Understand Substrate Resource Ownership

    main

    In the runtime: substrate model, resource ownership is distributed as follows:

    ResourceOwner
    WorkerPool capacityPlatform/Helm
    WorkerPool deploymentSubstrate
    ActorTemplate (generated)kagent
    ActorTemplate golden snapshot processSubstrate
    Actor lifecyclekagent (via ate-api)

    Important: kagent does not create or delete WorkerPool resources. The generated ActorTemplate is owned by the AgentHarness via an owner reference, allowing Kubernetes garbage collection to handle its deletion.

  8. Understand kagent Security Architecture and Actors

    main

    kagent is an AI agent platform for Kubernetes. Understanding its security posture requires knowing its core components:

    • Controller: Manages the lifecycle of AI agents and their dependencies by watching kagent custom resources.
    • Engine: The runtime engine (built on the ADK framework) that handles agent execution, tool invocation, and session management.
    • CLI: Used for interacting with kagent resources, deploying agents, and managing configurations.
    • UI: A web interface for managing agents, viewing logs, and monitoring performance.
    • Agents: AI entities that perform tasks and interact with Kubernetes resources or external systems.
    • MCP Servers: Model Context Protocol servers providing tools for Kubernetes, Istio, Helm, Argo, Prometheus, Grafana, and Cilium.

    Security Boundaries:

    • kagent operates within existing Kubernetes security boundaries and does not replace RBAC or cluster security policies.
    • It does not host LLM models; it integrates with external providers (OpenAI, Anthropic, Azure OpenAI, Google Vertex AI, Ollama).
    • API keys and credentials are managed via Kubernetes secrets.

  9. Understand kagent Python package structure

    main
    The kagent engine is organized into several sub-packages within the package directory. Each supported framework has its own dedicated package. The top-level kagent package serves as the main entry point for the engine.

  10. Understand Raw Claims Passthrough

    main

    The kagent backend implements a 'raw claims passthrough' design. Instead of mapping specific JWT claims (like email or name) to fixed internal fields, the backend passes the entire JWT payload through to the frontend.

    This means:

    • The /api/me endpoint returns the full JWT payload as-is.
    • You do not need to configure specific claim mappings (e.g., AUTH_JWT_CLAIM_EMAIL).
    • The system is compatible with any OIDC provider (Cognito, Okta, Azure AD, etc.) because the frontend can adapt to whatever claim names the provider uses (e.g., name, preferred_username, or email).

  11. Key Architectural Principles

    main

    When building or extending Kagent, keep these architectural decisions in mind:

    • CRDs as Source of Truth: Agent configuration is defined in Kubernetes CRDs; the database acts as a read-optimized cache.
    • Controller-as-Proxy: The UI communicates with the controller's HTTP server, which proxies A2A requests to agent pods. This centralizes authentication, routing, and observability.
    • Config via Secret: Agent runtime configuration (system prompts, model credentials, MCP connections) is provided via a config.json file mounted from a Kubernetes Secret.
    • Dual Runtime: Agents can run on the Python ADK (full features) or Go ADK (faster startup). The runtime field in the CRD determines the container image and readiness probe.
    • Template Resolution: Prompt templates are resolved by the controller during reconciliation, so agents receive fully resolved strings at runtime.
    • HITL (Human-in-the-loop): Tool approval is handled via the Google ADK's request_confirmation() mechanism.

  12. Understand the A2A Communication Protocol

    main

    Kagent uses the A2A protocol for communication between the controller and agent pods. It utilizes JSON-RPC 2.0 over HTTP with streaming support via Server-Sent Events (SSE).

    Key Concepts:

    • Task: A unit of work consisting of a user message and the agent's response.
    • Message: Contains parts which can be TextPart, DataPart, or FilePart.
    • DataPart: Used for structured data such as tool calls and results.
    • TaskState: Transitions through submitted → working → completed (or input_required, auth_required, failed).
    • Streaming: Events are streamed via SSE within the JSON-RPC response.