Documentation

Prerequisites

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

This guide will walk you through all the steps you need to get started with tracing your kagent agents. However, we recommend starting with the other getting-started guides first to get a better understanding of how kagent works.

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

  • kubectl - for interacting with your cluster

Installing Jaeger

In order to demonstrate tracing, we'll first need to install Jaeger. We will use the Jaeger all in one mode to demonstrate the tracing capabilities without needing to install any other components.

Firstly create a file called jaeger.yaml with the following content:

provisionDataStore:
  cassandra: false
allInOne:
  enabled: true
storage:
  type: memory
agent:
  enabled: false
collector:
  enabled: false
query:
  enabled: false

Then install Jaeger using the following command:

helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo update
helm upgrade --install jaeger jaegertracing/jaeger \
  --namespace jaeger \
  --create-namespace \
  --history-max 3 \
  --values jaeger.yaml

Installing kagent

  1. Set the OpenAI API key as an environment variable:
export OPENAI_API_KEY="your-api-key-here"
  1. Install the Helm chart with CRDs:
helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
    --namespace kagent \
    --create-namespace \
  1. Create a file called kagent-tracing.yaml with the following content:
otel:
  tracing:
    enabled: true
    exporter:
      otlp:
        endpoint: http://jaeger-collector.jaeger.svc.cluster.local:4317
  1. Install the kagent Helm chart:
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.openAI.apiKey=$OPENAI_API_KEY \
    --values kagent-tracing.yaml

Tracing your first agent

Now that we have Jaeger installed and kagent configured to use it, we can start tracing our first agent.

  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

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 the k8s-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. For the purpose of this guide, we'll use the k8s-agent agent. Specifically we'll use the k8s-agent agent to get the list of pods in the cluster.

For testing purposes, we'll use the k8s-agent agent to get the list of pods in the cluster.

Chatting with an agent
Chatting with an agent

Once that query is complete, we can go take a look at the data in Jaeger.

kubectl port-forward svc/jaeger-query -n devops 16686:16686

Once the port-forward is set up, you can open the Jaeger UI in your browser at http://localhost:16686.

From the Jaeger UI, select the kagent service on the top-left and then hit "search" to see the traces for the k8s-agent agent.

Specifically the result we're looking for should resemble the following:

Jaeger results page
Jaeger results page

Once you've found the trace, you can click on it to see the details.

Jaeger trace details
Jaeger trace details

That's it! You've now traced your first agent.

Next Steps

Need Help?