Kagentic - Extensible AI System

A microservices-based AI system running in Kubernetes that allows for dynamic tool registration and usage. The system consists of a chat interface, an AI agent that can use various tools, and a collection of tools that can register themselves with the agent.

System Architecture

The system consists of the following components running in the Kubernetes namespace 'kagentic':

• Frontend: Streamlit-based chat interface
• AI Agent: Core service that processes requests and coordinates with tools
• Tool Registry: PostgreSQL database for tool management
• Tools:
  • Calculator Tool: Handles mathematical operations
  • Search Tool: Performs web searches using SearchAPI.io

graph TD
    subgraph User Interaction
        A[User]
        B[Flask-based Web Interface]
    end
    subgraph AI Processing
        C[OpenAI GPT-4]
        D[Tool Management Module]
    end
    subgraph Infrastructure
        E[Kubernetes Cluster]
        F[External Tools/Systems]
    end

    A -->|Interacts with| B
    B -->|Sends queries to| C
    C -->|Generates responses| B
    C -->|Interacts with| D
    D -->|Manages| F
    B -->|Deployed on| E
    C -->|Deployed on| E
    D -->|Deployed on| E

Loading

Prerequisites

• Kubernetes cluster (minikube, kind, or cloud provider)
• kubectl configured to access your cluster
• Docker installed
• Python 3.9+
• OpenAI API key
• SearchAPI.io API key

Quick Start

1. Install kind (if not already installed):

   # On macOS
   brew install kind
   
   # On Linux
   curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
   chmod +x ./kind
   sudo mv ./kind /usr/local/bin/kind

2. Clone the repository and set up environment:

   git clone https://github.com/yourusername/kagentic.git
   cd kagentic
   
   # Set required API keys
   export OPENAI_API_KEY='your-openai-api-key'
   export SEARCH_API_KEY='your-searchapi-key'

3. Run the setup script:

   chmod +x setup-kind.sh
   ./setup-kind.sh

4. Access the application: The frontend will be available at http://localhost:30501

Detailed Setup

Local Development

1. Set up Python virtual environment:

   python -m venv venv
   source venv/bin/activate  # or venv\Scripts\activate on Windows

2. Install dependencies:

   for dir in */requirements.txt; do
       pip install -r "$dir"
   done

3. Set environment variables:

   export OPENAI_API_KEY='your-openai-api-key'
   export SEARCH_API_KEY='your-searchapi-key'

Database Setup

The tool registry database will be automatically initialized when the PostgreSQL container starts. The schema is defined in tool-registry/init.sql.

Monitoring

Check service status:

kubectl get pods -n kagentic
kubectl logs -f <pod-name> -n kagentic

View tool registry database:

kubectl exec -it <tool-registry-pod> -n kagentic -- psql -U kagentic -d tool_registry

Troubleshooting

1. Pods not starting

   kubectl describe pod <pod-name> -n kagentic
   kubectl logs <pod-name> -n kagentic

2. Database connection issues

   kubectl exec -it <ai-agent-pod> -n kagentic -- env | grep DATABASE_URL

3. Tool registration failing

   kubectl logs -f <tool-pod> -n kagentic

License

MIT License

Kind Cluster Setup

1. Install kind

   # On Linux
   curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
   chmod +x ./kind
   sudo mv ./kind /usr/local/bin/kind
   
   # On macOS
   brew install kind

2. Create the cluster

   # Create cluster using our config
   kind create cluster --config kind-config.yaml
   
   # Verify cluster is running
   kubectl cluster-info --context kind-kagentic

3. Load Docker images into kind

   # After running ./build.sh, load the images into kind
   kind load docker-image kagentic-base:latest --name kagentic
   kind load docker-image kagentic-tool-registry:latest --name kagentic
   kind load docker-image kagentic-ai-agent:latest --name kagentic
   kind load docker-image kagentic-frontend:latest --name kagentic
   kind load docker-image kagentic-search-tool:latest --name kagentic
   kind load docker-image kagentic-calculator-tool:latest --name kagentic

4. Special Considerations for kind

   • Images must be loaded into kind cluster after building
   • Use NodePort or ClusterIP instead of LoadBalancer
   • Access services via localhost and mapped ports
   • For persistent storage, use local-path provisioner:

   kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml
   kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

5. Access the Application The frontend will be available at http://localhost:30501

Troubleshooting kind Setup

1. Image pulling errors

   # Verify images are loaded
   docker exec -it kagentic-control-plane crictl images

2. Storage issues

   # Check storage class
   kubectl get storageclass
   
   # Check PVC status
   kubectl get pvc -n kagentic

3. Port access issues

   # Verify port mappings
   docker ps --format "{{.Names}}\t{{.Ports}}" | grep kagentic

4. Clean up

   # Delete cluster
   kind delete cluster --name kagentic
   
   # Remove all built images
   docker rmi tool-registry:latest ai-agent:latest frontend:latest search-tool:latest calculator-tool:latest