Skip to content

Commit d5b609c

Browse files
artbergerartberger
authored
Merge pull request #333 from kagent-dev/add-comprehensive-docs
v0.8 release docs
2 parents bd245a6 + 06c7b6e commit d5b609c

15 files changed

Lines changed: 936 additions & 134 deletions

File tree

‎public/sitemap.xml‎

Lines changed: 123 additions & 109 deletions
Large diffs are not rendered by default.

‎src/app/docs/kagent/concepts/agent-memory/page.mdx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: "Agent Memory"
3+
pageOrder: 5
4+
description: "Enable vector-backed long-term memory for agents to learn from past interactions."
5+
---
6+
7+
export const metadata = {
8+
title: "Agent Memory",
9+
description: "Enable vector-backed long-term memory for agents to learn from past interactions.",
10+
author: "kagent.dev"
11+
};
12+
13+
# Agent Memory
14+
15+
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.
16+
17+
## Overview
18+
19+
Agent memory provides the following capabilities.
20+
21+
- **Vector-backed.** A basic vector store uses embedding models to encode memories as 768-dimensional vectors.
22+
- **Searchable.** Agents retrieve relevant memories via cosine similarity.
23+
- **Automatic.** Agents extract and save user intent, key learnings, and preferences without explicit user action.
24+
- **Time-bounded.** Memories expire after a configurable TTL (default 15 days).
25+
- **Shared storage.** Memory uses the kagent database (PostgreSQL), not a separate database.
26+
27+
## Configuration
28+
29+
### Enable Memory on an Agent
30+
31+
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.
32+
33+
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.
34+
35+
```yaml
36+
apiVersion: kagent.dev/v1alpha2
37+
kind: Agent
38+
metadata:
39+
name: memory-agent
40+
namespace: kagent
41+
spec:
42+
type: Declarative
43+
declarative:
44+
modelConfig: default-model-config
45+
systemMessage: "You are a helpful assistant with long-term memory."
46+
memory:
47+
modelConfig: default-model-config # References the embedding provider
48+
```
49+
50+
### Custom TTL
51+
52+
To change the default memory retention period, set the `ttlDays` field.
53+
54+
```yaml
55+
memory:
56+
modelConfig: default-model-config
57+
ttlDays: 30 # Memories expire after 30 days instead of the default 15
58+
```
59+
60+
## How Memory Works
61+
62+
### Automatic Save Cycle
63+
64+
1. The agent processes user messages normally.
65+
2. Every 5th user message, the agent automatically extracts key information such as user intent, key learnings, and preferences.
66+
3. The agent summarizes extracted memories and encodes them as embedding vectors.
67+
4. The agent stores the vectors in the database with metadata and timestamps.
68+
69+
### Memory Retrieval (Prefetch)
70+
71+
Before generating a response, the agent performs the following steps.
72+
73+
1. Encodes the current user message as an embedding vector.
74+
2. Searches stored memories by cosine similarity.
75+
3. Injects the most relevant memories into the agent's context.
76+
77+
### Memory Tools
78+
79+
When you enable memory, the agent receives three additional tools.
80+
81+
| Tool | Description |
82+
|------|-------------|
83+
| `save_memory` | Explicitly save a piece of information. |
84+
| `load_memory` | Search for relevant memories by query. |
85+
| `prefetch_memory` | Automatically run before the agent generates a response to retrieve relevant memories. |
86+
87+
You can also instruct the agent to use `save_memory` or `load_memory` explicitly during a conversation.
88+
89+
### Viewing Memories
90+
91+
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.
92+
93+
## Memory Management via API
94+
95+
The following API endpoints let you manage memories programmatically.
96+
97+
```
98+
POST /api/memories/sessions # Add a memory
99+
POST /api/memories/sessions/batch # Add memories in batch
100+
POST /api/memories/search # Search memories by cosine similarity
101+
GET /api/memories?agent_name=X&user_id=Y # List memories
102+
DELETE /api/memories?agent_name=X&user_id=Y # Delete all memories for an agent
103+
```
104+
105+
## Limitations
106+
107+
- **No per-memory deletion.** You can delete all memories for an agent, but you cannot delete individual memory entries.
108+
- **No cross-agent memory sharing.** Each agent has its own isolated memory store. You cannot share memories across agents.
109+
- **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.
110+
111+
## Technical Details
112+
113+
- Embedding vectors are normalized to 768 dimensions.
114+
- Background TTL pruning runs periodically with a default retention of 15 days. Memories older than the retention period are automatically deleted.
115+
- Memories include timestamps and source session references.

‎src/app/docs/kagent/concepts/agents/page.mdx‎

Lines changed: 177 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,60 @@ Instructions are an important part of the agent's behavior. They define the agen
3434

3535
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.
3636

37+
### Prompt templates
38+
39+
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.
40+
41+
```yaml
42+
apiVersion: kagent.dev/v1alpha2
43+
kind: Agent
44+
metadata:
45+
name: k8s-agent
46+
namespace: kagent
47+
spec:
48+
type: Declarative
49+
declarative:
50+
modelConfig: default-model-config
51+
promptTemplate:
52+
dataSources:
53+
- kind: ConfigMap
54+
name: kagent-builtin-prompts
55+
alias: builtin
56+
- kind: ConfigMap
57+
name: my-custom-prompts
58+
systemMessage: |
59+
You are a Kubernetes management agent named {{.AgentName}}.
60+
61+
{{include "builtin/safety-guardrails"}}
62+
{{include "builtin/tool-usage-best-practices"}}
63+
{{include "my-custom-prompts/k8s-specific-rules"}}
64+
65+
Your tools: {{.ToolNames}}
66+
Your skills: {{.SkillNames}}
67+
```
68+
69+
The `kagent-builtin-prompts` ConfigMap ships with five reusable templates.
70+
71+
| Template Key | Description |
72+
|-------------|-------------|
73+
| `skills-usage` | Instructions for discovering and using skills. |
74+
| `tool-usage-best-practices` | Best practices for tool invocation. |
75+
| `safety-guardrails` | Safety and operational guardrails. |
76+
| `kubernetes-context` | Kubernetes-specific operational context. |
77+
| `a2a-communication` | Agent-to-agent communication guidelines. |
78+
79+
The following template variables are available in system messages.
80+
81+
| Variable | Description |
82+
|----------|-------------|
83+
| `{{.AgentName}}` | Name of the Agent resource. |
84+
| `{{.AgentNamespace}}` | Namespace of the Agent resource. |
85+
| `{{.Description}}` | Agent description. |
86+
| `{{.ToolNames}}` | Comma-separated list of tool names. |
87+
| `{{.SkillNames}}` | Comma-separated list of skill names. |
88+
89+
> **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.
90+
3791
## Tools
3892

3993
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
48102

49103
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.
50104

105+
## Human-in-the-Loop
106+
107+
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.
108+
109+
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).
110+
111+
### Tool approval
112+
113+
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.
114+
115+
```yaml
116+
tools:
117+
- type: McpServer
118+
mcpServer:
119+
name: kagent-tool-server
120+
kind: RemoteMCPServer
121+
apiGroup: kagent.dev
122+
toolNames:
123+
- k8s_get_resources # runs immediately
124+
- k8s_describe_resource # runs immediately
125+
- k8s_delete_resource # pauses for approval
126+
- k8s_apply_manifest # pauses for approval
127+
requireApproval:
128+
- k8s_delete_resource
129+
- k8s_apply_manifest
130+
```
131+
132+
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.
133+
134+
### Ask User
135+
136+
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.
137+
51138
## Skills
52139

53140
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
106193

107194
Container-based skills are actual, callable capabilities—not just descriptions of capabilities.
108195

109-
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.
196+
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.
197+
198+
### Git-based skills
199+
200+
You can also load skills directly from Git repositories, as an alternative to OCI images.
201+
202+
```yaml
203+
skills:
204+
gitRefs:
205+
- url: https://github.com/myorg/agent-skills.git
206+
ref: main
207+
- url: https://github.com/myorg/monorepo.git
208+
ref: main
209+
path: skills/kubernetes # Use a subdirectory
210+
```
211+
212+
For private repositories, configure authentication via HTTPS token or SSH key.
213+
214+
```yaml
215+
skills:
216+
gitAuthSecretRef:
217+
name: git-credentials # Secret containing a `token` key
218+
gitRefs:
219+
- url: https://github.com/myorg/private-skills.git
220+
ref: main
221+
```
222+
223+
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`.
110224

111225
### Best practices for skills
112226

@@ -122,6 +236,68 @@ When creating skills for your agents, consider the following best practices. Age
122236

123237
To learn more about using skills in your agents, see the [Skills example guide](/docs/kagent/examples/skills).
124238

239+
## Runtime
240+
241+
You can choose between two Agent Development Kit (ADK) runtimes for declarative agents: **Python** (default) and **Go**.
242+
243+
| Feature | Python ADK | Go ADK |
244+
|---------|-----------|--------|
245+
| Startup time | ~15 seconds | ~2 seconds |
246+
| Ecosystem | Google ADK, LangGraph, CrewAI integrations | Native Go implementation |
247+
| Resource usage | Higher (Python runtime) | Lower (compiled binary) |
248+
| Default | Yes | No |
249+
| Memory support | Yes | Yes |
250+
| MCP support | Yes | Yes |
251+
| HITL support | Yes | Yes |
252+
253+
Select the runtime via the `runtime` field in the declarative agent spec.
254+
255+
```yaml
256+
spec:
257+
type: Declarative
258+
declarative:
259+
runtime: go # or "python" (default)
260+
modelConfig: default-model-config
261+
systemMessage: "You are a helpful agent."
262+
```
263+
264+
**Choose Go when** fast startup matters (autoscaling, cold starts), lower resource consumption is important, or you don't need Python-specific framework integrations.
265+
266+
**Choose Python when** you need Google ADK-native features, CrewAI/LangGraph/OpenAI framework integrations, or Python-based custom tools.
267+
268+
For more benchmarks and details, see the [Go vs Python runtime blog post](/blog/go-vs-python-runtime).
269+
270+
## Memory
271+
272+
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.
273+
274+
For configuration details, supported storage backends, API endpoints, and limitations, see [Agent Memory](/docs/kagent/concepts/agent-memory).
275+
276+
## Context Management
277+
278+
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.
279+
280+
```yaml
281+
spec:
282+
type: Declarative
283+
declarative:
284+
modelConfig: default-model-config
285+
systemMessage: "You are a helpful agent for extended sessions."
286+
context:
287+
compaction:
288+
compactionInterval: 5 # Compact every 5 user invocations
289+
```
290+
291+
| Field | Type | Default | Description |
292+
|-------|------|---------|-------------|
293+
| `compactionInterval` | integer | `5` | Number of new user invocations before triggering a compaction. |
294+
| `overlapSize` | integer | `2` | Number of preceding invocations to include for context overlap. |
295+
| `eventRetentionSize` | integer | — | Number of most recent events to always retain. |
296+
| `tokenThreshold` | integer | — | Post-invocation token threshold that triggers compaction. |
297+
| `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. |
298+
299+
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.
300+
125301
## Agents as Tools
126302

127303
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.

‎src/app/docs/kagent/concepts/architecture/page.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,14 @@ In the future, we envision more features for the controller, such as:
2828

2929
## App/Engine
3030

31-
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.
31+
The kagent engine is the core component of kagent. It runs the agent's conversation loop and supports two runtimes:
3232

33-
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`.
33+
- **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.
34+
- **Go ADK** — A native Go implementation that provides faster startup (~2 seconds vs ~15 seconds) and lower resource consumption.
3435

35-
Please see the following links for more information on the ADK framework:
36+
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).
37+
38+
For more information on the Google ADK framework:
3639

3740
- [Agents](https://google.github.io/adk-docs/agents/)
3841
- [Tools](https://google.github.io/adk-docs/tools/)

‎src/app/docs/kagent/concepts/page.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,5 +24,12 @@ import QuickLink from '@/components/quick-link';
2424
<QuickLink title="Architecture" description="Learn about the architecture of kagent." href="/docs/kagent/concepts/architecture" />
2525
<QuickLink title="Agents" description="Learn about AI agents." href="/docs/kagent/concepts/agents" />
2626
<QuickLink title="Tools" description="Learn about tools and MCP." href="/docs/kagent/concepts/tools" />
27+
<QuickLink title="Tools Ecosystem" description="Comprehensive catalog of built-in tools for Kubernetes, Helm, Istio, Prometheus, Grafana, Cilium, and Argo Rollouts." href="/docs/kagent/resources/tools-ecosystem" />
28+
<QuickLink title="Human-in-the-Loop" description="Configure tool approval gates and interactive user prompts for agent oversight." href="/docs/kagent/examples/human-in-the-loop" />
29+
<QuickLink title="Agent Memory" description="Enable vector-backed long-term memory for agents to learn from past interactions." href="/docs/kagent/concepts/agent-memory" />
30+
<QuickLink title="Prompt Templates" description="Compose reusable prompt fragments from ConfigMaps using Go template syntax." href="/docs/kagent/concepts/agents#prompt-templates" />
31+
<QuickLink title="Multi-Runtime Support" description="Choose between Go and Python ADK runtimes for your agents." href="/docs/kagent/examples" />
32+
<QuickLink title="Git-Based Skills" description="Load markdown knowledge documents from Git repositories to guide agent behavior." href="/docs/kagent/concepts/agents#git-based-skills" />
33+
<QuickLink title="Context Management" description="Automatically manage conversation history to stay within LLM context windows." href="/docs/kagent/concepts/agents#context-management" />
2734
</div>
2835
</div>

‎src/app/docs/kagent/concepts/tools/page.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Kagent comes with a set of built-in tools that you can use to interact with your
1818

1919
## Built-in Tools
2020

21-
You can check out the full list of built-in tools [here](/tools).
21+
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.
2222

2323
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.
2424

0 commit comments

Comments
 (0)