diff --git a/public/sitemap.xml b/public/sitemap.xml index 719d0582..cffb7e27 100644 --- a/public/sitemap.xml +++ b/public/sitemap.xml @@ -2,763 +2,777 @@ https://kagent.dev/agents - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/blog - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/community - 2026-03-15 + 2026-03-18 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/concepts/agent-memory + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/concepts/agents - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/concepts/architecture - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/concepts - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/concepts/tools - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-agents - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-byo - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/agents-mcp - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/crewai-byo - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/discord-a2a - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/documentation - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/human-in-the-loop - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/langchain-byo - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/skills - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/examples/slack-a2a - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-mcp-tool - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/local-development - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/quickstart - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/system-prompts - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/introduction/installation - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/introduction - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/introduction/what-is-kagent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/observability/audit-prompts - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/observability/launch-ui - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/observability - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/observability/tracing - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/operations/debug - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/operations/operational-considerations - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/operations - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/operations/uninstall - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/operations/upgrade - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/api-ref - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-add-mcp - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-bug-report - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-build - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-completion - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-dashboard - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-deploy - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-get - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-help - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-init - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-install - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-invoke - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-mcp - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-run - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-uninstall - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-version - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/faq - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/helm - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/resources/release-notes - 2026-03-15 + 2026-03-18 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/resources/tools-ecosystem + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/amazon-bedrock - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/anthropic - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/azure-openai - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/byo-openai - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/gemini - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/google-vertexai - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/ollama - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/openai - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/install-controller - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/deploy - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/server - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/develop/fastmcp-python - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/develop/mcp-go - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/develop - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/introduction - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/quickstart - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/api-ref - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-add-tool - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-build - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-completion - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-deploy - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-help - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-init - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-install - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-run - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-secrets - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/reference - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs/kmcp/secrets - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/docs - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/enterprise - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/page.tsx - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/argo-rollouts-conversion-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/cilium-crd-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/helm-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/istio-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/k8s-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/kgateway-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/observability-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/agents/promql-agent - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/istio - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/kubernetes - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/prometheus - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/documentation - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/helm - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/argo - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/grafana - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/other - 2026-03-15 + 2026-03-18 weekly 0.8 https://kagent.dev/tools/cilium - 2026-03-15 + 2026-03-18 weekly 0.8 diff --git a/src/app/docs/kagent/concepts/agent-memory/page.mdx b/src/app/docs/kagent/concepts/agent-memory/page.mdx new file mode 100644 index 00000000..d7a79b19 --- /dev/null +++ b/src/app/docs/kagent/concepts/agent-memory/page.mdx @@ -0,0 +1,115 @@ +--- +title: "Agent Memory" +pageOrder: 5 +description: "Enable vector-backed long-term memory for agents to learn from past interactions." +--- + +export const metadata = { + title: "Agent Memory", + description: "Enable vector-backed long-term memory for agents to learn from past interactions.", + author: "kagent.dev" +}; + +# Agent Memory + +With agent memory, your agents can automatically save and retrieve relevant context across conversations using vector similarity search. Memory is built on top of the Google ADK memory implementation. + +## Overview + +Agent memory provides the following capabilities. + +- **Vector-backed.** A basic vector store uses embedding models to encode memories as 768-dimensional vectors. +- **Searchable.** Agents retrieve relevant memories via cosine similarity. +- **Automatic.** Agents extract and save user intent, key learnings, and preferences without explicit user action. +- **Time-bounded.** Memories expire after a configurable TTL (default 15 days). +- **Shared storage.** Memory uses the kagent database (PostgreSQL), not a separate database. + +## Configuration + +### Enable Memory on an Agent + +To enable memory, set the `memory` field on the declarative agent spec, as shown in the following YAML example. The `modelConfig` field references a `ModelConfig` object whose embedding provider generates memory vectors. + +You can also configure memory in the kagent UI when you create or edit an agent. In the UI, select an embedding model and set the memory TTL. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: memory-agent + namespace: kagent +spec: + type: Declarative + declarative: + modelConfig: default-model-config + systemMessage: "You are a helpful assistant with long-term memory." + memory: + modelConfig: default-model-config # References the embedding provider +``` + +### Custom TTL + +To change the default memory retention period, set the `ttlDays` field. + +```yaml +memory: + modelConfig: default-model-config + ttlDays: 30 # Memories expire after 30 days instead of the default 15 +``` + +## How Memory Works + +### Automatic Save Cycle + +1. The agent processes user messages normally. +2. Every 5th user message, the agent automatically extracts key information such as user intent, key learnings, and preferences. +3. The agent summarizes extracted memories and encodes them as embedding vectors. +4. The agent stores the vectors in the database with metadata and timestamps. + +### Memory Retrieval (Prefetch) + +Before generating a response, the agent performs the following steps. + +1. Encodes the current user message as an embedding vector. +2. Searches stored memories by cosine similarity. +3. Injects the most relevant memories into the agent's context. + +### Memory Tools + +When you enable memory, the agent receives three additional tools. + +| Tool | Description | +|------|-------------| +| `save_memory` | Explicitly save a piece of information. | +| `load_memory` | Search for relevant memories by query. | +| `prefetch_memory` | Automatically run before the agent generates a response to retrieve relevant memories. | + +You can also instruct the agent to use `save_memory` or `load_memory` explicitly during a conversation. + +### Viewing Memories + +In the kagent UI, you can view the memories that an agent has saved. With saved memories, you can inspect what the agent has learned and retained from past interactions. + +## Memory Management via API + +The following API endpoints let you manage memories programmatically. + +``` +POST /api/memories/sessions # Add a memory +POST /api/memories/sessions/batch # Add memories in batch +POST /api/memories/search # Search memories by cosine similarity +GET /api/memories?agent_name=X&user_id=Y # List memories +DELETE /api/memories?agent_name=X&user_id=Y # Delete all memories for an agent +``` + +## Limitations + +- **No per-memory deletion.** You can delete all memories for an agent, but you cannot delete individual memory entries. +- **No cross-agent memory sharing.** Each agent has its own isolated memory store. You cannot share memories across agents. +- **Not pluggable.** Memory is built on the Google ADK memory implementation and cannot be swapped for an alternative memory solution (such as Cognee). However, if an alternative memory solution exposes an [MCP server](/docs/kagent/concepts/tools#mcp-tools), you can add it as a tool and instruct the agent to use it instead of the built-in memory. + +## Technical Details + +- Embedding vectors are normalized to 768 dimensions. +- Background TTL pruning runs periodically with a default retention of 15 days. Memories older than the retention period are automatically deleted. +- Memories include timestamps and source session references. diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx index 4aeb1c18..a7dc8811 100644 --- a/src/app/docs/kagent/concepts/agents/page.mdx +++ b/src/app/docs/kagent/concepts/agents/page.mdx @@ -34,6 +34,60 @@ Instructions are an important part of the agent's behavior. They define the agen Writing good instructions is an art and a science. It requires a good understanding of the task at hand, the tools available, and the user's needs. In order to make it easier to write good instructions, we've created a [system prompt tutorial](/docs/kagent/getting-started/system-prompts) that can help you get started. +### Prompt templates + +You can use Go `text/template` syntax in system messages to compose reusable fragments stored in ConfigMaps. Instead of duplicating safety guidelines and tool usage instructions across every agent, store them once and reference them with `{{include "alias/key"}}` syntax. The controller resolves templates during reconciliation, so the final system message is fully expanded before reaching the agent runtime. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: k8s-agent + namespace: kagent +spec: + type: Declarative + declarative: + modelConfig: default-model-config + promptTemplate: + dataSources: + - kind: ConfigMap + name: kagent-builtin-prompts + alias: builtin + - kind: ConfigMap + name: my-custom-prompts + systemMessage: | + You are a Kubernetes management agent named {{.AgentName}}. + + {{include "builtin/safety-guardrails"}} + {{include "builtin/tool-usage-best-practices"}} + {{include "my-custom-prompts/k8s-specific-rules"}} + + Your tools: {{.ToolNames}} + Your skills: {{.SkillNames}} +``` + +The `kagent-builtin-prompts` ConfigMap ships with five reusable templates. + +| Template Key | Description | +|-------------|-------------| +| `skills-usage` | Instructions for discovering and using skills. | +| `tool-usage-best-practices` | Best practices for tool invocation. | +| `safety-guardrails` | Safety and operational guardrails. | +| `kubernetes-context` | Kubernetes-specific operational context. | +| `a2a-communication` | Agent-to-agent communication guidelines. | + +The following template variables are available in system messages. + +| Variable | Description | +|----------|-------------| +| `{{.AgentName}}` | Name of the Agent resource. | +| `{{.AgentNamespace}}` | Namespace of the Agent resource. | +| `{{.Description}}` | Agent description. | +| `{{.ToolNames}}` | Comma-separated list of tool names. | +| `{{.SkillNames}}` | Comma-separated list of skill names. | + +> **Security Note:** Only ConfigMaps are supported as data sources. Secret references are intentionally excluded to avoid leaking sensitive data into prompts sent to LLM providers. + ## Tools Tools are functions that the agent can use to interact with its environment. For example, a Kubernetes agent might have tools to list pods, get pod logs, and describe services. @@ -48,6 +102,39 @@ Some tools support additional configuration that can be set in when adding the t Kagent comes with a set of built-in tools that you can use to interact with your environment. Kagent also supports the [MCP (Model Configuration Protocol)](https://modelcontextprotocol.io/introduction) tools. Using MCP, you can bring any external tool into kagent and make it available for your agents to run. +## Human-in-the-Loop + +Kagent supports Human-in-the-Loop (HITL) to keep humans in control of agent actions. You can require user approval before an agent executes sensitive tools, and agents can ask users questions when they need clarification. + +For a hands-on tutorial that walks through setting up HITL with tool approval and the `ask_user` tool, see the [Human-in-the-Loop example](/docs/kagent/examples/human-in-the-loop). + +### Tool approval + +Add `requireApproval` to your agent's tool specification to gate destructive operations. Tools listed in `requireApproval` pause execution and present Approve/Reject buttons in the UI. Tools not listed run without waiting for approval. + +```yaml +tools: + - type: McpServer + mcpServer: + name: kagent-tool-server + kind: RemoteMCPServer + apiGroup: kagent.dev + toolNames: + - k8s_get_resources # runs immediately + - k8s_describe_resource # runs immediately + - k8s_delete_resource # pauses for approval + - k8s_apply_manifest # pauses for approval + requireApproval: + - k8s_delete_resource + - k8s_apply_manifest +``` + +When you reject a tool call, you can provide a reason. This reason is passed back to the LLM as context, so the agent can adjust its approach. + +### Ask User + +Every agent automatically has the built-in `ask_user` tool. It allows agents to pause and ask users questions with optional predefined choices, which is useful for clarifying ambiguous requests or collecting configuration preferences. No configuration for the `ask_user` tool is required. + ## Skills Skills are descriptions or even executable implementations of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals. @@ -106,7 +193,34 @@ These skills contain instructions, scripts, and resources that are loaded from c Container-based skills are actual, callable capabilities—not just descriptions of capabilities. -Kagent's skills are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports. +Kagent's skills are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: you can use kagent's skills with any LLM provider, not just Anthropic Claude. This means your agents can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports. + +### Git-based skills + +You can also load skills directly from Git repositories, as an alternative to OCI images. + +```yaml +skills: + gitRefs: + - url: https://github.com/myorg/agent-skills.git + ref: main + - url: https://github.com/myorg/monorepo.git + ref: main + path: skills/kubernetes # Use a subdirectory +``` + +For private repositories, configure authentication via HTTPS token or SSH key. + +```yaml +skills: + gitAuthSecretRef: + name: git-credentials # Secret containing a `token` key + gitRefs: + - url: https://github.com/myorg/private-skills.git + ref: main +``` + +A single `gitAuthSecretRef` applies to all Git repositories in the agent. You can combine Git and OCI skills in the same agent by specifying both `refs` and `gitRefs`. ### Best practices for skills @@ -122,6 +236,68 @@ When creating skills for your agents, consider the following best practices. Age To learn more about using skills in your agents, see the [Skills example guide](/docs/kagent/examples/skills). +## Runtime + +You can choose between two Agent Development Kit (ADK) runtimes for declarative agents: **Python** (default) and **Go**. + +| Feature | Python ADK | Go ADK | +|---------|-----------|--------| +| Startup time | ~15 seconds | ~2 seconds | +| Ecosystem | Google ADK, LangGraph, CrewAI integrations | Native Go implementation | +| Resource usage | Higher (Python runtime) | Lower (compiled binary) | +| Default | Yes | No | +| Memory support | Yes | Yes | +| MCP support | Yes | Yes | +| HITL support | Yes | Yes | + +Select the runtime via the `runtime` field in the declarative agent spec. + +```yaml +spec: + type: Declarative + declarative: + runtime: go # or "python" (default) + modelConfig: default-model-config + systemMessage: "You are a helpful agent." +``` + +**Choose Go when** fast startup matters (autoscaling, cold starts), lower resource consumption is important, or you don't need Python-specific framework integrations. + +**Choose Python when** you need Google ADK-native features, CrewAI/LangGraph/OpenAI framework integrations, or Python-based custom tools. + +For more benchmarks and details, see the [Go vs Python runtime blog post](/blog/go-vs-python-runtime). + +## Memory + +Your agents can save and retrieve relevant context across conversations using vector similarity search. When you enable memory on an agent, it receives three additional tools (`save_memory`, `load_memory`, `prefetch_memory`) and automatically extracts key information every 5th user message. + +For configuration details, supported storage backends, API endpoints, and limitations, see [Agent Memory](/docs/kagent/concepts/agent-memory). + +## Context Management + +Long conversations can exceed LLM context windows. The context window is the maximum amount of text (tokens) that an LLM can process in a single request. You can enable **event compaction** to automatically summarize older messages while preserving key information. + +```yaml +spec: + type: Declarative + declarative: + modelConfig: default-model-config + systemMessage: "You are a helpful agent for extended sessions." + context: + compaction: + compactionInterval: 5 # Compact every 5 user invocations +``` + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `compactionInterval` | integer | `5` | Number of new user invocations before triggering a compaction. | +| `overlapSize` | integer | `2` | Number of preceding invocations to include for context overlap. | +| `eventRetentionSize` | integer | — | Number of most recent events to always retain. | +| `tokenThreshold` | integer | — | Post-invocation token threshold that triggers compaction. | +| `summarizer` | object | — | Optional LLM-based summarizer configuration. When set, uses an LLM to generate a summary of compacted events instead of discarding them. Requires a `modelConfig` reference. | + +Compaction removes older conversation events to free up space in the context window. By default, compacted events are discarded. To preserve a summary of compacted events, configure the `summarizer` field with a `modelConfig` reference. Enable compaction for agents that handle long-running conversations, call many tools with large outputs, or need to support extended interactions. + ## Agents as Tools Kagent also supports using agents as tools. Any agent you create can be referenced and used by other agents you have. An example use case would be to have a PromQL agent that knows how to create PromQL queries from natural language. Then you'd create a second agent that would use the PromQL agent whenever it needs to create a PromQL query. diff --git a/src/app/docs/kagent/concepts/architecture/page.mdx b/src/app/docs/kagent/concepts/architecture/page.mdx index 7274c847..638887d1 100644 --- a/src/app/docs/kagent/concepts/architecture/page.mdx +++ b/src/app/docs/kagent/concepts/architecture/page.mdx @@ -28,11 +28,14 @@ In the future, we envision more features for the controller, such as: ## App/Engine -The kagent engine is the core component of kagent. It is a Python application that is responsible for running the agent's conversation loop. It is built on top of the [ADK](https://google.github.io/adk-docs/) framework. +The kagent engine is the core component of kagent. It runs the agent's conversation loop and supports two runtimes: -The ADK team did a wonderful job of creating a flexible, powerful, and most importantly extensible framework for building AI agents. We take full advantage of this by using the framework by adding our own `Agents`, and `Tools`. +- **Python ADK** (default) — Built on top of the [Google ADK](https://google.github.io/adk-docs/) framework. Supports Google ADK-native features and integrations with CrewAI, LangGraph, and OpenAI frameworks. +- **Go ADK** — A native Go implementation that provides faster startup (~2 seconds vs ~15 seconds) and lower resource consumption. -Please see the following links for more information on the ADK framework: +Select the runtime by setting the `runtime` field in the agent spec (e.g., `runtime: go`). Both runtimes support MCP tools, HITL, and agent memory. For more details, see [Agents](/docs/kagent/concepts/agents#runtime). + +For more information on the Google ADK framework: - [Agents](https://google.github.io/adk-docs/agents/) - [Tools](https://google.github.io/adk-docs/tools/) diff --git a/src/app/docs/kagent/concepts/page.mdx b/src/app/docs/kagent/concepts/page.mdx index 70f9a285..f2e326fb 100644 --- a/src/app/docs/kagent/concepts/page.mdx +++ b/src/app/docs/kagent/concepts/page.mdx @@ -24,5 +24,12 @@ import QuickLink from '@/components/quick-link'; + + + + + + + diff --git a/src/app/docs/kagent/concepts/tools/page.mdx b/src/app/docs/kagent/concepts/tools/page.mdx index f61b7d51..81329a5e 100644 --- a/src/app/docs/kagent/concepts/tools/page.mdx +++ b/src/app/docs/kagent/concepts/tools/page.mdx @@ -18,7 +18,7 @@ Kagent comes with a set of built-in tools that you can use to interact with your ## Built-in Tools -You can check out the full list of built-in tools [here](/tools). +You can check out the full list of [built-in tools](/tools), or see the [Tools Ecosystem](/docs/kagent/resources/tools-ecosystem) reference for a detailed catalog of tools organized by MCP server. The built-in tools are meant as a good starting point for any agents running in kubernetes, however we don't envision them covering all possible use-cases, so we support multiple tool extension points to allow you to bring in your own tools. diff --git a/src/app/docs/kagent/examples/page.mdx b/src/app/docs/kagent/examples/page.mdx index c527ac6e..6f565580 100644 --- a/src/app/docs/kagent/examples/page.mdx +++ b/src/app/docs/kagent/examples/page.mdx @@ -20,12 +20,15 @@ import QuickLink from '@/components/quick-link';
- + + + + - +
diff --git a/src/app/docs/kagent/getting-started/page.mdx b/src/app/docs/kagent/getting-started/page.mdx index 7ea836ec..aa21af3f 100644 --- a/src/app/docs/kagent/getting-started/page.mdx +++ b/src/app/docs/kagent/getting-started/page.mdx @@ -22,6 +22,7 @@ import QuickLink from '@/components/quick-link'; + - \ No newline at end of file + diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index a40ff04d..011a1f3e 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -197,6 +197,10 @@ Another way to install kagent is using Helm. Review the following advanced configuration options that you might want to set up for your kagent installation. +### Database configuration + +For production environments, set up kagent with an external PostgreSQL instance. For more information, see the [Database configuration guide](/operations/operational-considerations/#database-configuration). + ### Configure controller environment variables You can configure the controller by using environment variables for settings such as service names, connection details, and more. diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx index 90fd281d..8a0df343 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -58,21 +58,78 @@ controller: ### More considerations for HA -- **Database requirement**: When using multiple controller replicas, use PostgreSQL as the database backend. The default in-memory database does not support multiple replicas. +- **Database requirement**: PostgreSQL is the default database backend and supports multiple controller replicas. The bundled PostgreSQL instance is deployed automatically unless you configure an external PostgreSQL. - **Leader election**: Leader election uses Kubernetes leases and is handled automatically. - **Failover**: If the leader fails, another replica automatically becomes the leader. -### Use PostgreSQL for scaling +## Database configuration -To scale the controller to multiple replicas, configure PostgreSQL as the database backend. You can enable PostgreSQL by using the Helm `--set` flag or values file. +Kagent uses PostgreSQL as the database backend. + +By default, a bundled PostgreSQL instance is deployed when you install kagent. This bundled instance works out of the box without any external prerequisites. It is a simple instance that is meant for demos, local development, and short proofs of concept. + +> **Note:** The default bundled image (`postgres:18`) does not include the pgvector extension. If you need vector features such as long-term memory, either use an external PostgreSQL with pgvector installed and set `database.postgres.vectorEnabled: true`, or override the bundled image to a pgvector image. + +For production deployments, bring your own external PostgreSQL instance. + +### How database connection is determined + +The `database.postgres.bundled.enabled` and `database.postgres.url`/`database.postgres.urlFile` settings are independent controls. + +- **`bundled.enabled`** controls whether the bundled PostgreSQL pod and its PVC are deployed. It does not affect which database the controller connects to. +- **`url` / `urlFile`** controls what the controller connects to. When either is set, the controller uses it. When both are empty, the controller connects to the bundled instance. + +**Connection precedence (controller):** + +``` +urlFile > url > bundled connection string +``` + +| Scenario | `bundled.enabled` | `url` / `urlFile` | Bundled pod deployed? | Controller connects to | +|---|---|---|---|---| +| Default (dev/eval) | `true` | unset | yes | bundled | +| External DB, no bundled pod | `false` | set | no | external | +| External DB, bundled pod kept running | `true` | set | yes | external | +| Bundled disabled, no external set | `false` | unset | no | error (misconfigured) | + +**Migration**: This means that you can keep the bundled pod running while the controller points at an external database, which is useful for migrating data. + + +### Bundled PostgreSQL + +The bundled PostgreSQL instance is deployed by default (`database.postgres.bundled.enabled: true`). The database name, username, and password are all hardcoded to `kagent`. Credentials are stored in a Kubernetes Secret. + +You can customize the storage size and image: + +**Helm values file:** + +```yaml +database: + postgres: + bundled: + enabled: true # default + storage: 500Mi + image: + registry: docker.io + repository: library + name: postgres + tag: "18" +``` + +### External PostgreSQL + +For production environments, use an external PostgreSQL instance instead of the bundled one. Set `database.postgres.bundled.enabled: false` and configure the connection with `database.postgres.url` or `database.postgres.urlFile`. + +> **Note**: If your external PostgreSQL has the `pgvector` extension installed and you want to use vector-based memory features, set `database.postgres.vectorEnabled: true`. The default is `false`. **Helm `--set` flag:** ```bash helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent \ - --set database.type=postgres \ + --set database.postgres.bundled.enabled=false \ --set database.postgres.url=postgres://user:password@postgres-host:5432/kagent \ + --set database.postgres.vectorEnabled=true \ --set controller.replicas=3 ``` @@ -80,13 +137,35 @@ helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ ```yaml database: - type: postgres postgres: url: postgres://user:password@postgres-host:5432/kagent + vectorEnabled: true # Set to true if your external PostgreSQL has pgvector + bundled: + enabled: false controller: replicas: 3 ``` +**Using a secret for the database URL:** Mount a Kubernetes secret that contains the PostgreSQL connection string using `controller.volumes` and `controller.volumeMounts`, then reference the mount path with `urlFile`. This keeps credentials out of Helm values. + +```yaml +database: + postgres: + urlFile: /var/secrets/db-url + vectorEnabled: true + bundled: + enabled: false +controller: + volumes: + - name: db-secret + secret: + secretName: my-postgres-url-secret + volumeMounts: + - name: db-secret + mountPath: /var/secrets + readOnly: true +``` + ## Secure execution environment Kagent supports Kubernetes security contexts to run agents and tool servers with reduced privileges. Configure `securityContext` and `podSecurityContext` on your Agent or ToolServer resources to enforce secure execution. diff --git a/src/app/docs/kagent/resources/helm/page.mdx b/src/app/docs/kagent/resources/helm/page.mdx index be1741a9..1e168975 100644 --- a/src/app/docs/kagent/resources/helm/page.mdx +++ b/src/app/docs/kagent/resources/helm/page.mdx @@ -118,12 +118,20 @@ A Helm chart for kagent, built with Google ADK | controller.volumeMounts | list | `[]` | | | controller.volumes | list | `[]` | | | controller.watchNamespaces | list | [] (watches all available namespaces) | Namespaces the controller should watch. If empty, the controller will watch ALL available namespaces. | -| database.postgres.url | string | `"postgres://postgres:kagent@pgsql-postgresql.kagent.svc.cluster.local:5432/postgres"` | | -| database.postgres.urlFile | string | `""` | | -| database.postgres.vectorEnabled | bool | `true` | | -| database.sqlite.databaseName | string | `"kagent.db"` | | -| database.sqlite.vectorEnabled | bool | `true` | | -| database.type | string | `"sqlite"` | | +| database.postgres.bundled.enabled | bool | `true` | Deploy the bundled PostgreSQL pod and PVC. Set to `false` to disable the bundled instance and provide your own via `url` or `urlFile`. | +| database.postgres.bundled.image.registry | string | `"docker.io"` | Bundled PostgreSQL image registry. | +| database.postgres.bundled.image.repository | string | `"library"` | Bundled PostgreSQL image repository (org/namespace). | +| database.postgres.bundled.image.name | string | `"postgres"` | Bundled PostgreSQL image name. | +| database.postgres.bundled.image.tag | string | `"18"` | Bundled PostgreSQL image tag. | +| database.postgres.bundled.image.pullPolicy | string | `"IfNotPresent"` | Bundled PostgreSQL image pull policy. | +| database.postgres.bundled.storage | string | `"500Mi"` | PersistentVolumeClaim size for the bundled PostgreSQL instance. | +| database.postgres.bundled.resources.requests.cpu | string | `"250m"` | CPU request for the bundled PostgreSQL container. | +| database.postgres.bundled.resources.requests.memory | string | `"256Mi"` | Memory request for the bundled PostgreSQL container. | +| database.postgres.bundled.resources.limits.cpu | string | `"500m"` | CPU limit for the bundled PostgreSQL container. | +| database.postgres.bundled.resources.limits.memory | string | `"512Mi"` | Memory limit for the bundled PostgreSQL container. | +| database.postgres.url | string | `""` | External PostgreSQL connection string. Always used if set, regardless of `bundled.enabled`. | +| database.postgres.urlFile | string | `""` | Path to a file containing the database URL. Takes precedence over `url` when set. Always used if set, regardless of `bundled.enabled`. | +| database.postgres.vectorEnabled | bool | `false` | Enable pgvector extension and memory table migration. Set to `true` when using a PostgreSQL server that has pgvector installed. Required for vector-based memory features. | | fullnameOverride | string | `""` | | | grafana-mcp.grafana.serviceAccountToken | string | `""` | | | grafana-mcp.grafana.url | string | `"grafana.kagent:3000/api"` | | diff --git a/src/app/docs/kagent/resources/page.mdx b/src/app/docs/kagent/resources/page.mdx index b40ac326..9f0451c2 100644 --- a/src/app/docs/kagent/resources/page.mdx +++ b/src/app/docs/kagent/resources/page.mdx @@ -21,7 +21,8 @@ import QuickLink from '@/components/quick-link';
- + + @@ -29,4 +30,4 @@ import QuickLink from '@/components/quick-link';
- \ No newline at end of file + diff --git a/src/app/docs/kagent/resources/release-notes/page.mdx b/src/app/docs/kagent/resources/release-notes/page.mdx index 85a70868..01f6dfa8 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -18,6 +18,135 @@ The kagent documentation shows information only for the latest release. If you r For more details on the changes between versions, review the [kagent GitHub releases](https://github.com/kagent-dev/kagent/releases). +# v0.8 + +Review this summary of significant changes from kagent version 0.7 to v0.8. + +* Human-in-the-Loop (HITL) — tool approval gates and interactive `ask_user` tool. +* Agent Memory — vector-backed long-term memory for agents. +* Go ADK runtime — new Go-based agent runtime for faster startup and lower resource usage. +* Agents as MCP servers — expose A2A agents via MCP for cross-tool interoperability. +* Skills — markdown knowledge documents loaded from OCI images or Git repositories. +* Go workspace restructure — the Go codebase is split into `api`, `core`, and `adk` modules for composability. +* Prompt templates — reusable prompt fragments from ConfigMaps using Go template syntax. +* Context management — automatic event compaction for long conversations. +* AWS Bedrock support — new model provider for AWS Bedrock. +* **PostgreSQL-only database backend** — SQLite support has been removed. PostgreSQL is now the only supported database backend. + +## Human-in-the-Loop (HITL) + +You can now use two Human-in-the-Loop mechanisms that can pause agent execution and wait for user input. + +**Tool Approval** — You can mark specific tools as requiring user confirmation before execution by using the `requireApproval` field in the Agent CR. When the agent calls a tool that requires approval, the UI presents Approve/Reject buttons. The reason provided for rejection gets used as context for the LLM. + +**Ask User** — A built-in `ask_user` tool is automatically added to every agent. Agents can pose questions to users with predefined choices (single-select, multi-select) or free-text input during execution. + +For more information, see the [Human-in-the-Loop example](/docs/kagent/examples/human-in-the-loop) and the [blog post](/blog/human-in-the-loop-kagent). + +## Agent Memory + +Your agents can now automatically save and retrieve relevant context across conversations using vector similarity search. Memory is built on the Google ADK memory implementation and uses the same kagent database (PostgreSQL). + +When you enable memory on an agent, it receives three additional tools: `save_memory`, `load_memory`, and `prefetch_memory`. Every 5th user message, the agent automatically extracts key information, such as user intent, key learnings, preferences. + +You can configure memory in the Agent CR or through the UI when you create or edit an agent by selecting an embedding model and TTL. + +For more information, see [Agent Memory](/docs/kagent/concepts/agent-memory). + +## Go ADK Runtime + +You can now choose between two Agent Development Kit runtimes: **Python** (default) and **Go**. The Go ADK provides significantly faster startup (~2 seconds vs ~15 seconds for Python) and lower resource consumption. + +Select the runtime via the `runtime` field in the declarative agent spec. + +```yaml +spec: + type: Declarative + declarative: + runtime: go +``` + +The Go ADK includes built-in tools: `SkillsTool`, `BashTool`, `ReadFile`, `WriteFile`, and `EditFile`. + +For more information, see [Agents](/docs/kagent/concepts/agents#runtime) and the [blog post](/blog/go-vs-python-runtime). + +## Agents as MCP Servers + +Agent-to-Agent (A2A) agents are now exposed as MCP servers via the kagent controller HTTP server. This enables cross-tool interoperability — any MCP-compatible client can consume agents, not just the A2A protocol. + +## Skills + +Your agents can now load markdown-based knowledge documents (skills) that provide domain-specific instructions, best practices, and procedures. Skills load at agent startup and are discoverable through the built-in `SkillsTool`. + +You can load skills from two sources. + +- **OCI images.** Container images containing skill files. +- **Git repositories.** Clone skills directly from Git repos, with support for private repos via HTTPS token or SSH key authentication. + +For more information, see [Agents](/docs/kagent/concepts/agents#git-based-skills). + +## Go Workspace Restructure + +The Go code now uses a Go workspace with three modules: `api`, `core`, and `adk`. This makes the codebase more composable for you if you want to pull in parts of kagent (such as the API types or ADK) without importing all dependencies. + +| Module | Purpose | +|--------|---------| +| `go/api` | Shared types: CRDs, ADK config types, database models, HTTP client. Import this module to work with kagent's API types without pulling in the full codebase. | +| `go/core` | Infrastructure: controllers, HTTP server, CLI. This module contains the main kagent controller logic. | +| `go/adk` | Go Agent Development Kit runtime. Import this module to build custom Go-based agents. | + +## Prompt Templates + +Agent system messages now support Go `text/template` syntax. You can store common prompt fragments, such as safety guardrails or tool usage best practices, in ConfigMaps and reference them with `{{include "alias/key"}}` syntax. + +The `kagent-builtin-prompts` ConfigMap ships with five reusable templates: `skills-usage`, `tool-usage-best-practices`, `safety-guardrails`, `kubernetes-context`, and `a2a-communication`. + +For more information, see [Agents](/docs/kagent/concepts/agents#prompt-templates). + +## Context Management + +Long conversations can now be automatically compacted to stay within LLM context windows. You can configure the `context.compaction` field to enable periodic summarization of older events while preserving key information. + +For more information, see [Agents](/docs/kagent/concepts/agents#context-management). + +## AWS Bedrock Support + +You can now use AWS Bedrock as a model provider, allowing your agents to use Bedrock-hosted models. + +## PostgreSQL-Only Database Backend + +SQLite support has been removed from kagent. PostgreSQL is now the only supported database backend. + +**What changed:** +- The `database.type` configuration option is removed. +- SQLite-related Helm values (`database.sqlite.*`) are removed. +- A bundled PostgreSQL instance is deployed by default via `database.postgres.bundled.enabled: true`. The bundled image is `postgres:18` (standard PostgreSQL without pgvector). +- `database.postgres.vectorEnabled` now defaults to `false`. Set it to `true` only when using a PostgreSQL server that has the pgvector extension installed. +- `database.postgres.bundled.enabled` and `url`/`urlFile` are now independent controls. You can keep the bundled pod running while pointing the controller at an external database, which is useful for migration. +- The bundled instance database name, username, and password are hardcoded to `kagent`. Credentials are stored in a Kubernetes Secret instead of a ConfigMap. +- The `database.postgres.bundled.database`, `bundled.user`, and `bundled.password` configuration options are removed. + +**Why this change:** +- SQLite lacks pgvector support, requiring separate code paths for memory and vector search. +- SQLite's single-writer constraint prevents horizontal scaling of the controller. +- Divergent SQL dialects between SQLite and PostgreSQL required maintaining duplicate code paths. +- PostgreSQL was already the recommended production backend. + +**Migration:** + +If you were using the default SQLite backend, no migration is needed. The bundled PostgreSQL is deployed automatically. You can optionally customize the bundled instance via `database.postgres.bundled.*` (storage size, image) as needed. See the [Database configuration guide](/docs/kagent/operations/operational-considerations/#database-configuration) for details. + +Note that for production deployments, use your own external PostgreSQL instance. If you already are, you can keep your `database.postgres.url` or `database.postgres.urlFile` settings as before. If your external PostgreSQL has the pgvector extension and you were using vector-based memory features, set `database.postgres.vectorEnabled: true` since the default has changed to `false`. + +## Additional Changes + +- **API key passthrough** for ModelConfig. +- **Custom service account** override in agent CRDs. +- **Voice support** for agents. +- **UI dynamic provider model discovery** for easier model configuration. +- **CLI `--token` flag** for `kagent invoke` API key passthrough. +- **CVE fixes** across Go, Python, and container images. + # v0.7 Review the main changes from kagent version 0.6 to v0.7, then continue reading for more detailed information. @@ -84,7 +213,7 @@ Review the main changes from kagent version 0.5 to v0.6, then continue reading f * API string references to resources in other namespaces in the format `namespace/name` now fail. Instead, the APIs have a separate field for you to specify the namespace of the resource. * The Tools API moves or eliminates some APIs entirely in favor of new kmcp APIs. * The Agents APIs now require a top-level `type` field to support the new BYO agent functionality. -* The ModelConfig APIs rename the secret name field from `apiKeySecret` to `apiKeySecret`. +* The ModelConfig APIs rename the secret name field from `apiKeySecretRef` to `apiKeySecret`. * Memory APIs are not supported in ADK. ## Upgraded API version @@ -400,7 +529,7 @@ This change supports the new type for BYO agents.
-[v1alpha2 Example](https://github.com/kagent-dev/kagent/blob/eitanya/byo/helm/agents/k8s/templates/agent.yaml): Note that the entire agent configuration is now nested under the `inline` setting. +[v1alpha2 Example](https://github.com/kagent-dev/kagent/blob/eitanya/byo/helm/agents/k8s/templates/agent.yaml): Note that the entire agent configuration is now nested under the `declarative` setting. ```yaml apiVersion: kagent.dev/v1alpha2 @@ -421,7 +550,7 @@ This change supports the new type for BYO agents. **Key Changes:** * Added `type: Declarative` field to specify agent type - * Agent configuration now under `inline` section + * Agent configuration now under `declarative` section * Supports new BYO deployment model
@@ -453,7 +582,7 @@ spec: ## ModelConfig API -The secret name field is renamed from `apiKeySecret` to `apiKeySecret`. +The secret name field is renamed from `apiKeySecretRef` to `apiKeySecret`. ### ModelInfo removed diff --git a/src/app/docs/kagent/resources/tools-ecosystem/page.mdx b/src/app/docs/kagent/resources/tools-ecosystem/page.mdx new file mode 100644 index 00000000..69f582af --- /dev/null +++ b/src/app/docs/kagent/resources/tools-ecosystem/page.mdx @@ -0,0 +1,252 @@ +--- +title: "Tools Ecosystem" +pageOrder: 3 +description: "Explore the built-in MCP tools for Kubernetes, Helm, Istio, Prometheus, Grafana, Cilium, and Argo Rollouts." +--- + +export const metadata = { + title: "Tools Ecosystem", + description: "Explore the built-in MCP tools for Kubernetes, Helm, Istio, Prometheus, Grafana, Cilium, and Argo Rollouts.", + author: "kagent.dev" +}; + +# Tools Ecosystem + +You can use a rich set of built-in tools through **Model Context Protocol (MCP)** servers, plus add your own custom tools. Two primary MCP servers serve the tools: `kagent-tool-server` (Kubernetes, Helm, Istio, Cilium, Argo) and `kagent-grafana-mcp` (Grafana, Prometheus, Loki, Incidents). + +## kagent-tool-server Tools + +### Kubernetes + +The following tools provide comprehensive cluster management. + +| Tool | Description | +|------|-------------| +| `k8s_get_resources` | Query resources, such as pods, deployments, and services. | +| `k8s_describe_resource` | Get detailed resource information. | +| `k8s_get_resource_yaml` | Get YAML representation of a resource. | +| `k8s_get_pod_logs` | Retrieve pod logs. | +| `k8s_get_events` | Get cluster events. | +| `k8s_get_available_api_resources` | List supported API resources. | +| `k8s_get_cluster_configuration` | Retrieve cluster configuration. | +| `k8s_check_service_connectivity` | Test service connectivity. | +| `k8s_execute_command` | Execute commands in pods. | +| `k8s_patch_resource` | Patch resources with strategic merge. | +| `k8s_label_resource` | Add labels to resources. | +| `k8s_remove_label` | Remove labels from resources. | +| `k8s_annotate_resource` | Add annotations to resources. | +| `k8s_remove_annotation` | Remove annotations from resources. | +| `k8s_delete_resource` | Delete resources. | +| `k8s_apply_manifest` | Apply YAML manifests. | +| `k8s_create_resource` | Create a resource from a local file. | +| `k8s_create_resource_from_url` | Create a resource from a URL. | +| `k8s_generate_resource` | Generate YAML for Istio, Gateway API, or Argo resources. | +| `k8s_rollout` | Manage rollouts (restart, status, history). | +| `k8s_scale` | Scale a resource (deployment, statefulset, etc.). | + +### Helm + +| Tool | Description | +|------|-------------| +| `helm_list_releases` | List installed releases. | +| `helm_get_release` | Get details of a specific release. | +| `helm_upgrade` | Upgrade a release. | +| `helm_uninstall` | Remove a release. | +| `helm_repo_add` | Add a chart repository. | +| `helm_repo_update` | Update chart repositories. | + +### Istio + +| Tool | Description | +|------|-------------| +| `istio_proxy_status` | Check proxy synchronization status. | +| `istio_proxy_config` | Inspect proxy configuration. | +| `istio_install_istio` | Install Istio. | +| `istio_generate_manifest` | Generate installation manifests. | +| `istio_analyze_cluster_configuration` | Analyze Istio configuration for issues. | +| `istio_version` | Get Istio version info. | +| `istio_remote_clusters` | Manage remote cluster configuration. | +| `istio_waypoint_status` | Get waypoint proxy status. | +| `istio_list_waypoints` | List waypoint proxies. | +| `istio_generate_waypoint` | Generate waypoint configuration. | +| `istio_apply_waypoint` | Apply waypoint configuration. | +| `istio_delete_waypoint` | Delete a waypoint proxy. | +| `istio_ztunnel_config` | Inspect ztunnel configuration. | + +### Argo Rollouts + +| Tool | Description | +|------|-------------| +| `argo_verify_argo_rollouts_controller_install` | Verify the Argo Rollouts controller is running. | +| `argo_rollouts_list` | List Argo Rollouts in a namespace. | +| `argo_promote_rollout` | Promote a paused rollout. | +| `argo_pause_rollout` | Pause a rollout. | +| `argo_set_rollout_image` | Set the image of a rollout. | +| `argo_check_plugin_logs` | Check Argo Rollouts plugin logs. | +| `argo_verify_kubectl_plugin_install` | Verify the kubectl Argo Rollouts plugin is installed. | +| `argo_verify_gateway_plugin` | Verify the Argo Rollouts gateway plugin. | + +### Cilium + +The following table shows a subset of Cilium tools. Cilium has 30+ tools available. + +| Tool | Description | +|------|-------------| +| `cilium_status_and_version` | Check Cilium status and version. | +| `cilium_install_cilium` | Install Cilium. | +| `cilium_upgrade_cilium` | Upgrade Cilium. | +| `cilium_toggle_cluster_mesh` | Enable or disable cluster mesh. | +| `cilium_show_cluster_mesh_status` | View cluster mesh status. | +| `cilium_list_bgp_peers` | View BGP peers. | +| `cilium_list_bgp_routes` | View BGP routes. | +| `cilium_get_endpoints_list` | List endpoints. | +| `cilium_get_endpoint_details` | Get endpoint details. | +| `cilium_validate_cilium_network_policies` | Validate network policies. | +| `cilium_toggle_hubble` | Enable or disable Hubble observability. | + +### Kubescape + +| Tool | Description | +|------|-------------| +| `kubescape_check_health` | Check Kubescape health status. | +| `kubescape_list_vulnerabilities` | List vulnerabilities. | +| `kubescape_get_vulnerability_details` | Get details of a specific vulnerability. | +| `kubescape_list_vulnerability_manifests` | List vulnerability manifests. | +| `kubescape_list_configuration_scans` | List configuration scans. | +| `kubescape_get_configuration_scan` | Get a specific configuration scan. | +| `kubescape_list_application_profiles` | List application profiles. | +| `kubescape_get_application_profile` | Get a specific application profile. | +| `kubescape_list_network_neighborhoods` | List network neighborhoods. | +| `kubescape_get_network_neighborhood` | Get a specific network neighborhood. | + +## kagent-grafana-mcp Tools + +A separate `kagent-grafana-mcp` MCP server (`RemoteMCPServer`) serves tools for Prometheus, Grafana, Loki, and incident management. + +### Prometheus + +| Tool | Description | +|------|-------------| +| `query_prometheus` | Execute PromQL queries. | +| `list_prometheus_metric_names` | List available metric names. | +| `list_prometheus_metric_metadata` | Get metric metadata. | +| `list_prometheus_label_names` | List available label names. | +| `list_prometheus_label_values` | List values for a specific label. | + +### Grafana + +| Tool | Description | +|------|-------------| +| `search_dashboards` | Search dashboards. | +| `update_dashboard` | Update a dashboard. | +| `get_dashboard_by_uid` | Get a dashboard by UID. | +| `get_dashboard_panel_queries` | Get panel queries from a dashboard. | +| `list_datasources` | List data sources. | +| `get_datasource` | Get a data source by name or UID. | +| `alerting_manage_rules` | Manage alert rules (list, create, update, delete). | +| `alerting_manage_routing` | Manage alerting routing, notification policies, and contact points. | + +### Loki + +| Tool | Description | +|------|-------------| +| `query_loki_logs` | Query logs via Loki. | +| `query_loki_stats` | Query Loki statistics. | +| `list_loki_label_names` | List Loki label names. | +| `list_loki_label_values` | List Loki label values. | + +### Incidents & On-Call + +| Tool | Description | +|------|-------------| +| `list_incidents` | List incidents. | +| `get_incident` | Get incident details. | +| `create_incident` | Create a new incident. | +| `add_activity_to_incident` | Add activity to an incident. | +| `list_oncall_users` | List on-call users. | +| `get_current_oncall_users` | Get current on-call users. | +| `list_oncall_schedules` | List on-call schedules. | + +## Agent Built-in Tools + +The following tools are automatically available to every agent without any configuration. + +| Tool | Description | +|------|-------------| +| `ask_user` | Pose questions to users with optional choices. | +| `SkillsTool` | Discover and load skills (Go ADK). | +| `bash` | Execute shell commands (Python ADK). | +| `read_file` | Read file contents with pagination (Python ADK). | +| `write_file` | Write file content (Python ADK). | +| `edit_file` | Edit files via string replacement (Python ADK). | + +## Configuring Tools on an Agent + +### Single MCP Server + +The following example shows how to configure an agent with a single MCP server. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: k8s-agent + namespace: kagent +spec: + type: Declarative + declarative: + modelConfig: default-model-config + systemMessage: "You manage Kubernetes clusters." + tools: + - type: McpServer + mcpServer: + apiGroup: kagent.dev + name: kagent-tool-server + kind: RemoteMCPServer + toolNames: + - k8s_get_resources + - k8s_describe_resource + - k8s_get_pod_logs + - k8s_get_events +``` + +### With Tool Approval + +You can require user approval for sensitive tools by adding `requireApproval`. + +```yaml +tools: + - type: McpServer + mcpServer: + apiGroup: kagent.dev + name: kagent-tool-server + kind: RemoteMCPServer + toolNames: + - k8s_get_resources + - k8s_describe_resource + - k8s_delete_resource + - k8s_apply_manifest + requireApproval: # These tools pause for user approval + - k8s_delete_resource + - k8s_apply_manifest +``` + +### Agent as Tool (A2A) + +You can use another agent as a tool via the A2A protocol. + +```yaml +tools: + - type: Agent + agent: + name: specialist-agent +``` + +## Community / Contrib MCP Servers + +You can find additional MCP servers in `contrib/tools/`. + +| Server | Description | +|--------|-------------| +| **GitHub MCP Server** | GitHub Copilot MCP server with tools for issues, PRs, repos, actions, and more. | +| **k8sgpt MCP Server** | K8sGPT integration for AI-powered Kubernetes diagnostics. | diff --git a/src/config/navigation.json b/src/config/navigation.json index 2db06167..b37fdb45 100644 --- a/src/config/navigation.json +++ b/src/config/navigation.json @@ -83,6 +83,11 @@ "title": "Tools", "href": "/docs/kagent/concepts/tools", "description": "Understand the different types of tools kagent can use, including built-in, MCP, and HTTP tools, and how tool discovery works." + }, + { + "title": "Agent Memory", + "href": "/docs/kagent/concepts/agent-memory", + "description": "Enable vector-backed long-term memory for agents to learn from past interactions." } ] }, @@ -259,6 +264,11 @@ "href": "/docs/kagent/resources/helm", "description": "kagent Helm chart configuration reference" }, + { + "title": "Tools Ecosystem", + "href": "/docs/kagent/resources/tools-ecosystem", + "description": "Explore the built-in MCP tools for Kubernetes, Helm, Istio, Prometheus, Grafana, Cilium, and Argo Rollouts." + }, { "title": "FAQs", "href": "/docs/kagent/resources/faq",