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..398b4c7f --- /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 same 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. 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 by selecting an embedding model and setting 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 response generation. | + +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. This lets you 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 # Clear all memories for an agent +``` + +## Limitations + +- **No per-memory deletion.** You can clear 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, 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 (default retention: 15 days). +- 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..df759c18 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 were 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 immediately. + +```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 — useful for clarifying ambiguous requests or collecting configuration preferences. No configuration 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. @@ -108,6 +195,33 @@ Container-based skills are actual, callable capabilities—not just descriptions 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. +### 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 Containerize and store your skills in a specialized registry so that you can reuse them across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. @@ -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 the [Agent Memory](/docs/kagent/concepts/agent-memory) concept guide. + +## Context Management + +Long conversations can exceed LLM context windows. 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 | Default | Description | +|-------|---------|-------------| +| `compactionInterval` | `5` | Number of new user invocations before triggering a compaction. | +| `overlapSize` | `2` | Number of preceding invocations to include for context overlap. | +| `eventRetentionSize` | — | Number of most recent events to always retain. | +| `tokenThreshold` | — | Post-invocation token threshold that triggers compaction. | +| `summarizer` | — | Optional LLM-based summarizer configuration. | + +By default, compacted events are dropped. To preserve a summary, 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..857ed74d 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. Select it by setting `runtime: go` in the agent spec. -Please see the following links for more information on the ADK framework: +Both runtimes support MCP tools, HITL, and agent memory. For more details, see the [Agents](/docs/kagent/concepts/agents#runtime) concept guide. + +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..2130949c 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..44057705 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 [here](/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 d9083c4d..f6367fed 100644 --- a/src/app/docs/kagent/examples/page.mdx +++ b/src/app/docs/kagent/examples/page.mdx @@ -20,11 +20,14 @@ 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..22696596 100644 --- a/src/app/docs/kagent/operations/operational-considerations/page.mdx +++ b/src/app/docs/kagent/operations/operational-considerations/page.mdx @@ -58,20 +58,47 @@ 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 with pgvector is deployed when you install kagent. This bundled instance works out of the box with no external prerequisites. It is a simple instance that is meant for demos, local development, and short proofs of concept. + +For production deployments, bring your own external PostgreSQL instance. + +### Bundled PostgreSQL + +The default bundled PostgreSQL instance is deployed automatically when both `database.postgres.url` and `database.postgres.urlFile` are empty (the default). You can customize the bundled instance configuration. + +**Helm values file:** + +```yaml +database: + postgres: + vectorEnabled: true + bundled: + image: pgvector/pgvector:pg18-trixie + storage: 500Mi + database: postgres + user: postgres + password: kagent +``` + +### External PostgreSQL + +For production environments, use an external PostgreSQL instance instead of the bundled one. To configure the external instance, use the `database.postgres.url` or `database.postgres.urlFile` settings. + +> **Note**: If your external PostgreSQL does not have the `pgvector` extension installed, set `database.postgres.vectorEnabled: false` to disable vector-based memory features. **Helm `--set` flag:** ```bash helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent \ - --set database.type=postgres \ --set database.postgres.url=postgres://user:password@postgres-host:5432/kagent \ --set controller.replicas=3 ``` @@ -80,13 +107,22 @@ 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 false if your external PostgreSQL doesn't have pgvector controller: replicas: 3 ``` +**Using a secret for the database URL:** This configuration expects a Kubernetes secret mounted at `/etc/secrets/database-url` containing the PostgreSQL connection string. + +```yaml +database: + postgres: + urlFile: /etc/secrets/database-url + vectorEnabled: 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..799919a8 100644 --- a/src/app/docs/kagent/resources/helm/page.mdx +++ b/src/app/docs/kagent/resources/helm/page.mdx @@ -118,12 +118,14 @@ 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.database | string | `"postgres"` | Database name for the bundled PostgreSQL instance | +| database.postgres.bundled.image | string | `"pgvector/pgvector:pg18-trixie"` | Container image for the bundled PostgreSQL instance | +| database.postgres.bundled.password | string | `"kagent"` | Password for the bundled PostgreSQL instance | +| database.postgres.bundled.storage | string | `"500Mi"` | Storage size for the bundled PostgreSQL instance | +| database.postgres.bundled.user | string | `"postgres"` | Username for the bundled PostgreSQL instance | +| database.postgres.url | string | `""` | PostgreSQL connection string. Leave empty to deploy the bundled postgres instance. Set this to use an external PostgreSQL. | +| database.postgres.urlFile | string | `""` | Path to a file containing the database URL. Takes precedence over url when set. Leave empty to use the bundled postgres instance. | +| database.postgres.vectorEnabled | bool | `true` | Enable pgvector extension and memory table migration. Requires pgvector to be installed on the PostgreSQL server. Set to false when using an external PostgreSQL that does not have pgvector. | | 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..be1cc1a3 100644 --- a/src/app/docs/kagent/resources/release-notes/page.mdx +++ b/src/app/docs/kagent/resources/release-notes/page.mdx @@ -18,6 +18,132 @@ 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 the main changes from kagent version 0.7 to v0.8, then continue reading for more detailed information. + +* 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 with pgvector is now the only supported database backend. + +## Human-in-the-Loop (HITL) + +You can now use two Human-in-the-Loop mechanisms that 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 tries to call an approval-required tool, the UI presents Approve/Reject buttons. Rejected tool calls include the rejection reason 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`. The agent automatically extracts key information (user intent, key learnings, preferences) every 5th user message. + +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 the [Agent Memory](/docs/kagent/concepts/agent-memory) concept guide. + +## 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 the [Agents](/docs/kagent/concepts/agents#runtime) concept guide and the [blog post](/blog/go-vs-python-runtime). + +## Agents as MCP Servers + +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 the [Agents](/docs/kagent/concepts/agents#git-based-skills) concept guide. + +## 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. | +| `go/core` | Infrastructure: controllers, HTTP server, CLI. | +| `go/adk` | Go Agent Development Kit runtime. | + +## Prompt Templates + +Agent system messages now support Go `text/template` syntax. You can store common prompt fragments (safety guardrails, 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 the [Agents](/docs/kagent/concepts/agents#prompt-templates) concept guide. + +## 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 the [Agents](/docs/kagent/concepts/agents#context-management) concept guide. + +## 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 with pgvector 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 PostgreSQL instance with pgvector is now bundled in the Helm chart by default. This bundled PostgreSQL is deployed automatically when both `database.postgres.url` and `database.postgres.urlFile` are empty. +- New `database.postgres.bundled.*` configuration options allow customizing the bundled PostgreSQL instance (image, storage, credentials). + +**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 will be deployed automatically. You can optionally customize the bundled instance via `database.postgres.bundled.*` (storage size, image, credentials) as needed. See the [Database configuration guide](/operations/operational-considerations/#database-configuration) for details. + +Note that for production deployments, it is recommended to use your own external PostgreSQL instance. If you already are, you can keep your `database.postgres.url` or `database.postgres.urlFile` settings as before the migration. + +## 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 +210,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 +526,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 +547,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 +579,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..bd4c1cc3 --- /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 (pods, deployments, services, etc.). | +| `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",