langcode_agent/README.md

MaxClaw Agent

Un agente configurabile basato su DeepAgents che supporta più provider LLM.

Caratteristiche

• Indipendente dal provider: Funziona con OpenAI, Ollama, OpenRouter e qualsiasi altro provider supportato da init_chat_model di LangChain
• Basato su DeepAgents: Include pianificazione, accesso al filesystem, sub-agenti e gestione del contesto out of the box
• Configurazione semplice: Imposta le variabili d'ambiente per scegliere il tuo provider e modello
• Configurazione persistente: Gestisci e conserva le configurazioni tramite CLI o TUI
• Estensibile: Aggiungi strumenti personalizzati, modifica i prompt e configura i sub-agenti secondo le tue esigenze
• Strumenti personalizzati: Include strumenti per gestire Proxmox e Ollama

Installazione

1. Clona questo repository
2. Installa i pacchetti richiesti:

   pip install -r requirements.txt
   

Configurazione

Puoi configurare MaxClaw Agent in diversi modi:

1. Variabili d'ambiente (Avvio Rapido)

Imposta le seguenti variabili d'ambiente per configurare il tuo provider LLM:

• MODEL_PROVIDER: Il provider da utilizzare (es. "openai", "ollama", "openrouter")
• MODEL_NAME: Il nome specifico del modello (es. "gpt-4o", "gemma2:9b")
• Variabili specifiche per il provider:
  • Per OpenAI: OPENAI_API_KEY
  • Per Ollama: OLLAMA_BASE_URL (predefinito a http://localhost:11434)
  • Per OpenRouter: OPENROUTER_API_KEY e opzionalmente OPENROUTER_BASE_URL (predefinito a https://openrouter.ai/api/v1)

Esempi di Configurazione

OpenAI

export MODEL_PROVIDER="openai"
export MODEL_NAME="gpt-4o"
export OPENAI_API_KEY="la-tua-chiave-api-openai"

Ollama (locale)

export MODEL_PROVIDER="ollama"
export MODEL_NAME="gemma2:9b"
export OLLAMA_BASE_URL="http://192.168.0.50:11434"

OpenRouter

export MODEL_PROVIDER="openrouter"
export MODEL_NAME="anthropic/claude-3.5-sonnet"
export OPENROUTER_API_KEY="la-tua-chiave-api-openrouter"

2. Configurazione Persistente (Consigliato)

Utilizza la CLI o la TUI per gestire le configurazioni che persistono tra le sessioni.

Utilizzo della CLI

# Elenca le configurazioni
python config_cli.py list

# Cerca configurazioni
python config_cli.py search "ollama"

# Aggiungi una nuova configurazione interattivamente
python config_cli.py add

# Aggiungi una nuova configurazione in modo non interattivo
python config_cli.py add --name "mio-ollama" --provider "ollama" --model "gemma2:9b" --base-url "http://192.168.0.50:11434" --set-active

# Rimuovi una configurazione
python config_cli.py remove "mio-ollama"

# Imposta la configurazione attiva
python config_cli.py set-active "mio-ollama"

# Mostra la configurazione attiva
python config_cli.py active

# Testa la connessione a una configurazione
python config_cli.py test "mio-ollama"

# Esporta configurazioni in JSON
python config_cli.py export --format json --output backup

# Importa configurazioni da JSON
python config_cli.py import backup.json

Utilizzo della TUI

# Avvia l'Interfaccia Utente Testuale
python config_tui.py

Naviga usando le frecce direzionali, premi Invio per selezionare e 'q' per uscire.

La TUI ora include:

• Ricerca e filtro delle configurazioni
• Esportazione/importazione in JSON/YAML
• Test di connessione diretto
• Navigazione migliorata

Utilizzo

Esegui l'agente:

python main.py

Puoi quindi interagire con l'agente nel terminale. Digita 'exit' per uscire.

Strumenti Personalizzati

MaxClaw Agent include strumenti personalizzati per gestire il tuo ambiente:

Strumenti Proxmox

Configura le variabili d'ambiente per abilitare gli strumenti Proxmox:

export PROXMOX_HOST="192.168.0.100"
export PROXMOX_USER="root"
export PROXMOX_PASSWORD="tua-password"  # oppure
export PROXMOX_TOKEN="tuo-api-token"

Strumenti disponibili:

• proxmox_list_vms: Elenca tutte le VM nel cluster
• proxmox_vm_status: Ottieni lo stato di una VM specifica
• proxmox_start_vm: Avvia una VM
• proxmox_stop_vm: Ferma una VM
• proxmox_restart_vm: Riavvia una VM
• proxmox_create_snapshot: Crea uno snapshot
• proxmox_list_snapshots: Elenca gli snapshot di una VM

Strumenti Ollama

Gli strumenti Ollama sono sempre disponibili e utilizzano l'URL configurato in OLLAMA_BASE_URL.

Strumenti disponibili:

• ollama_list_models: Elenca tutti i modelli disponibili
• ollama_model_info: Ottieni informazioni dettagliate su un modello
• ollama_pull_model: Scarica un nuovo modello
• ollama_delete_model: Elimina un modello
• ollama_generate: Genera una completion
• ollama_status: Controlla se Ollama è in esecuzione
• ollama_running_models: Mostra i modelli attualmente in esecuzione

Personalizzazione

Per personalizzare l'agente, modifica main.py:

• Cambia il prompt di sistema predefinito in create_maxclaw_agent
• Aggiungi strumenti personalizzati alla chiamata create_deep_agent
• Configura i sub-agenti o altre funzionalità di DeepAgents

Test

Esegui lo script di test:

python test_agent.py

Sicurezza

MaxClaw Agent implementa misure di sicurezza avanzate:

• Crittografia a riposo: Tutte le informazioni sensibili (chiavi API) sono crittografate usando la crittografia simmetrica Fernet
• Permessi di file sicuri: La directory di configurazione e i file sono impostati con accesso solo al proprietario (700 per le directory, 600 per i file)
• Gestione automatica delle chiavi: Le chiavi di crittografia vengono generate e memorizzate automaticamente in modo sicuro
• Validazione completa: Tutte le configurazioni vengono validate prima del salvataggio per prevenire errori

Licenza

MIT

Contribuire

I contributi sono i benvenuti! Sentiti libero di aprire issue o inviare pull request.

Contatti

Per domande o supporto, apri una issue nel repository.