Documentation

Quick Start

This guide will help you get started with kagent, an open-source framework that brings the power of agentic AI to cloud-native environments. We'll walk through setting environment and deploying your first AI agent.

Prerequisites

Before you begin, make sure you have the following tools installed:

  • kind for creating and running a local Kubernetes cluster
  • Helm - for installing the kagent chart
  • kubectl - for interacting with your cluster

To run the AI agents you'll also need an OpenAI API key. You can get one here.

Installing kagent

  1. Set the OpenAI API key as an environment variable:
export OPENAI_API_KEY="your-api-key-here"
  1. Download the kagent CLI:
# Download/run the install script
curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash
Invoke-WebRequest -Uri https://github.com/kagent-dev/kagent/releases/latest/download/kagent_windows_amd64.zip -OutFile kagent.zip
Expand-Archive -Path kagent.zip -DestinationPath .\kagent
Move-Item .\kagent\kagent.exe C:\Windows\System32\
curl -LO https://github.com/kagent-dev/kagent/releases/latest/download/kagent_linux_amd64.tar.gz
tar -xzf kagent_linux_amd64.tar.gz
sudo mv kagent /usr/local/bin/
sudo chmod +x /usr/local/bin/kagent
  1. Install kagent to the cluster using the CLI. First run the CLI:
kagent

Then, once within the CLI environment, run the install command:

install
kagent >> install
kagent installed successfully

Accessing the kagent dashboard (UI)

  1. To open the kagent dashboard, run the dashboard command from the CLI
kagent >> dashboard
kagent dashboard is available at http://localhost:8082
Press Enter to stop the port-forward...

The CLI will set up the port-forward to the service running inside the cluster and open the dashboard.

Kagent dashboard main page
Kagent dashboard main page

Running Your First AI Agent

Once you're in the kagent UI, you can start interacting with the pre-configured sample agents. You can click on the agent card to view the agent details and start a conversation.

Chatting with an agent
Chatting with an agent

Using the CLI

You can run kagent to start the REPL environment and then use commands to interact with kagent:

kagent >> help


Commands:
  clear          clear the screen
  dashboard      Open the kagent dashboard.
  exit           exit the program
  get            get kagent resources.
  help           display help
  install        Install kagent.
  run            Run a kagent agent
  uninstall      Uninstall kagent.
  version        Print the kagent version.

Let's start by listing the current agents:

kagent >> get agents
kagent >> get agents
+---+---------------------+----+----------------------------+
| # | NAME                | ID | CREATED                    |
+---+---------------------+----+----------------------------+
| 0 | helm-agent          | 2  | 2025-03-13T19:08:14.527935 |
| 1 | observability-agent | 3  | 2025-03-13T19:08:14.348957 |
| 2 | istio-agent         | 1  | 2025-03-13T19:08:13.794848 |
+---+---------------------+----+----------------------------+

To start a new agent, run the run chat command:

kagent >> run chat [agent-name] [session-name] [initial-task]

If you don't provide any flags, it will it will prompt you for the values:

kagent >> run chat


Select an agent:
   observability-agent
   istio-agent
 ❯ helm-agent


Select a session:
 ❯ [New Session]
Enter a session name: test
Enter a task: What helm chart are installed in my cluster?

Once a task has been entered, the agent will start running and you'll see the conversation in the CLI:

Event Type: ToolCall(s)
Source: helm_agent
+---+--------------------+-----------------------------------------+
| # | NAME               | ARGUMENTS                               |
+---+--------------------+-----------------------------------------+
| 0 | helm_list_releases | {"all_namespaces":true,"deployed":true} |
+---+--------------------+-----------------------------------------+
----------------------------------


Event Type: TextMessage
Source: helm_agent


I found the following Helm release deployed across all namespaces:


- **Release Name:** kagent
  - **Namespace:** kagent
  - **Revision:** 11
  - **Updated:** 2025-03-13 19:18:49 UTC
  - **Status:** Deployed
  - **Chart:** kagent-v0.0.18-4-g4926e59-dirty


If you need more details about any specific release, let me know!
----------------------------------


Usage: Prompt Tokens: 6573, Completion Tokens: 229
helm-agent--test>

As you can see above, the agent found the kagent release. If anything else is running in your cluster, it will probably find that too.

Now keep chatting with the agent to see what other things it can do :)

Next Steps

Need Help?