Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aiadvocat/kagentic
Flask-based agentic AI chat assistant using OpenAI's GPT-4. Supports tool registration and management for dynamic responses. Deployed on Kubernetes for scalability and reliability. Features retry mechanisms, session management, and health checks. Ideal for integrating AI-driven chat with external tools.
https://github.com/aiadvocat/kagentic
Last synced: 3 days ago
JSON representation
Flask-based agentic AI chat assistant using OpenAI's GPT-4. Supports tool registration and management for dynamic responses. Deployed on Kubernetes for scalability and reliability. Features retry mechanisms, session management, and health checks. Ideal for integrating AI-driven chat with external tools.
- Host: GitHub
- URL: https://github.com/aiadvocat/kagentic
- Owner: aiadvocat
- License: mit
- Created: 2024-12-09T15:45:07.000Z (30 days ago)
- Default Branch: main
- Last Pushed: 2024-12-19T00:13:02.000Z (21 days ago)
- Last Synced: 2024-12-19T01:21:30.258Z (21 days ago)
- Language: Python
- Size: 43 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome_ai_agents - Kagentic - Flask-based agentic AI chat assistant using OpenAI's GPT-4. Supports tool registration and management for dynamic responses. Deployed on … (Building / Deployment)
- awesome_ai_agents - Kagentic - Flask-based agentic AI chat assistant using OpenAI's GPT-4. Supports tool registration and management for dynamic responses. Deployed on … (Building / Deployment)
README
# 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
```mermaid
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
```
## 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):
```bash
# 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:
```bash
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:
```bash
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:
```bash
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
```
2. Install dependencies:
```bash
for dir in */requirements.txt; do
pip install -r "$dir"
done
```
3. Set environment variables:
```bash
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:
```bash
kubectl get pods -n kagentic
kubectl logs -f -n kagentic
```
View tool registry database:
```bash
kubectl exec -it -n kagentic -- psql -U kagentic -d tool_registry
```
## Troubleshooting
1. **Pods not starting**
```bash
kubectl describe pod -n kagentic
kubectl logs -n kagentic
```
2. **Database connection issues**
```bash
kubectl exec -it -n kagentic -- env | grep DATABASE_URL
```
3. **Tool registration failing**
```bash
kubectl logs -f -n kagentic
```
## License
[MIT License](LICENSE)
## Kind Cluster Setup
1. **Install kind**
```bash
# 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**
```bash
# 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**
```bash
# 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:
```bash
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**
```bash
# Verify images are loaded
docker exec -it kagentic-control-plane crictl images
```
2. **Storage issues**
```bash
# Check storage class
kubectl get storageclass
# Check PVC status
kubectl get pvc -n kagentic
```
3. **Port access issues**
```bash
# Verify port mappings
docker ps --format "{{.Names}}\t{{.Ports}}" | grep kagentic
```
4. **Clean up**
```bash
# 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
```