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 up the 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"

2. Download the kagent CLI.

   curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash

3. Install kagent to the cluster by using the CLI.

   kagent install

   Example output:

   kagent installed successfully

Accessing the kagent dashboard (UI)#

1. To open the kagent dashboard, run the dashboard command from the CLI. The CLI sets up the port-forward to the UI service running inside the cluster and opens the dashboard.

   kagent dashboard

   kagent dashboard is available at http://localhost:8082
   Press Enter to stop the port-forward...

2. Click Let's Get Started in the welcome wizard.

   

3. Walk through the wizard screen by screen to set up your first agent. At any time, you can exit out of the wizard by clicking Skip wizard.

   • Step 1: Configure AI Model: Choose an existing model such as gpt-4.1-mini.
   • Step 2: Set up the AI Agent: Review the default details for a basic Kubernetes agent.
   • Step 3: Select Tools: Review the preselected tools for your first agent.
   • Step 4: Review Agent Configuration: Review the details of your selections, then click Create kagent/my-first-k8s-agent & Finish.

   

Good job! You created your first agent. You can share your success, or click Finish & Go to Agent.

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.

1. From the kagent UI landing page, find your kagent/my-first-k8s-agent agent. You might have to refresh the page.

   

2. Click your agent, then enter a message such as "What API resources are running in my cluster?", and click Send. The agent uses the available tools as shown in the to help answer the question.

   

3. Click around to explore the UI some more.

   • The menu shows a history of your chats as well as the ability to start a New Chat.
   • The Agent Details panel shows the tools that the agent uses to respond to your messages.
   • The chat interface includes Arguments and Results that you can expand to see more details about how your question was answered. For example, the Results show the output of the kubectl terminal commands that the agent ran to list the API resources in your cluster.

   

Using the CLI#

Interact with kagent in your terminal.

1. Review the available commands.

   kagent help
   
   Available Commands:
     bug-report  Generate a bug report
     completion  Generate the autocompletion script for the specified shell
     dashboard   Open the kagent dashboard
     get         Get a kagent resource
     help        Help about any command
     install     Install kagent
     invoke      Invoke a kagent agent
     uninstall   Uninstall kagent
     version     Print the kagent version

2. List the current agents.

   kagent get agent
   +---+---------------------+----+----------------------------+
   | # | 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 |
   +---+---------------------+----+----------------------------+

3. Interact with an agent with the invoke command. The agent is called and a conversation starts.

   kagent invoke -t "What Helm charts are in my cluster?" --agent helm-agent

   Example output:

   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 from the example, the agent found the kagent Helm chart 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#

• Create your first agent
• Learn about Core Concepts
• Join our Community

Need Help?#

• Visit our GitHub repository
• Ask a question on Discord
• Check out the FAQ