truetype/langcode_agent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8dbab53c6deee65e852bb812991b9e93e79d403c
langcode_agent/README.md
T

16 KiB
Raw Blame History

MaxClaw Agent

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

Caratteristiche

  • Indipendente dal provider: Funziona con OpenAI, Ollama, OpenRouter, Anthropic, Google 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 unificati: Gestisci qualsiasi provider con la stessa interfaccia
  • Strumenti personalizzati: Include strumenti per gestire Proxmox e Ollama
  • Completamento shell: Supporta bash e zsh per autocompletamento dei comandi
  • Test completi: Suite di test per garantire la qualità del codice
  • Docker support: Containerizzazione per deployment facile
  • API REST: Server API per accesso remoto
  • Web UI: Interfaccia web per gestione configurazioni
  • Comandi integrati: Comandi speciali con prefisso "/" per gestione rapida
  • Monitoraggio: Sistema di logging e monitoraggio delle performance
  • Sistema di plugin: Estendi le funzionalità con plugin personalizzati
  • Supporto multilingue: Interfaccia in italiano e inglese

Installazione

Installazione Locale

  1. Clona questo repository
  2. Installa i pacchetti richiesti: 
    pip install -r requirements.txt

Installazione con Docker

# Build dell'immagine
docker build -t maxclaw-agent .

# Esecuzione con Docker Compose
docker-compose up -d

# Esecuzione diretta
docker run -it --rm \
  -e MODEL_PROVIDER=ollama \
  -e MODEL_NAME=gemma2:9b \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  maxclaw-agent

Configurazione del Completamento Shell

Bash

# Aggiungi al tuo ~/.bashrc o ~/.bash_profile
source /path/to/maxclaw_agent/completions/maxclaw.bash

Zsh

# Aggiungi al tuo ~/.zshrc
fpath=(/path/to/maxclaw_agent/completions $fpath)
autoload -Uz compinit && compinit

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", "anthropic", "google")
  • MODEL_NAME: Il nome specifico del modello (es. "gpt-4o", "gemma2:9b", "claude-3-5-sonnet")
  • 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)
    • Per Anthropic: ANTHROPIC_API_KEY
    • Per Google: GOOGLE_API_KEY

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"

Anthropic

export MODEL_PROVIDER="anthropic"
export MODEL_NAME="claude-3-5-sonnet-20241022"
export ANTHROPIC_API_KEY="la-tua-chiave-api-anthropic"

Google

export MODEL_PROVIDER="google"
export MODEL_NAME="gemini-1.5-pro"
export GOOGLE_API_KEY="la-tua-chiave-api-google"

2. Configurazione Persistente (Consigliato)

Utilizza la CLI, la TUI o l'interfaccia web 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 dell'Interfaccia Web

Avvia il server API e accedi all'interfaccia web:

# Avvia il server API
python api_server.py

# Accedi all'interfaccia web
# http://localhost:8000

L'interfaccia web include:

  • Gestione completa delle configurazioni
  • Chat con l'agente
  • Monitoraggio dello stato del sistema
  • Test di connessione

Utilizzo

Utilizzo Locale

Esegui l'agente:

python main.py

Comandi Speciali (prefissati con "/")

Quando interagisci con l'agente, puoi usare comandi speciali preceduti da "/" per gestire il sistema senza confonderli con i messaggi di chat:

/help, /?           - Mostra i comandi disponibili
/status             - Mostra lo stato del sistema
/config list        - Elenca tutte le configurazioni
/config active      - Mostra la configurazione attiva
/config test        - Testa la connessione alla configurazione attiva
/config use <name>  - Cambia la configurazione attiva
/models             - Elenca i modelli disponibili per il provider attivo
/clear              - Pulisce lo schermo
/plugins            - Elenca i plugin disponibili
/language           - Cambia la lingua dell'interfaccia
/exit, /quit        - Esci dall'agente

Esempio di sessione:

👤 You: /status
📊 Stato del Sistema:
Provider: ollama
Modello: gemma2:9b
Ollama URL: http://192.168.0.50:11434

👤 You: /config list
📋 Configurazioni disponibili:
✅ mio-ollama: ollama - gemma2:9b
   openai-gpt4: openai - gpt-4o

👤 You: Ciao, chi sei?
🤖 MaxClaw: Ciao! Sono MaxClaw, un agente AI configurabile...

👤 You: Elenca i file nella directory corrente
🤖 MaxClaw: [Esegue ls e mostra i file]

👤 You: /exit
👋 Goodbye!

Utilizzo con Docker

# Avvia con Docker Compose
docker-compose up -d

# Accedi al terminale
docker exec -it maxclaw-agent python main.py

# Oppure esegui direttamente
docker run -it --rm maxclaw-agent

Utilizzo dell'API REST

Avvia il server API:

python api_server.py

L'API sarà disponibile su http://localhost:8000

Endpoint API Disponibili

  • GET /: Interfaccia web
  • GET /health: Health check
  • POST /chat: Chat con l'agente
  • GET /configurations: Elenca tutte le configurazioni
  • POST /configurations: Aggiungi una configurazione
  • DELETE /configurations/{name}: Rimuovi una configurazione
  • POST /configurations/{name}/activate: Attiva una configurazione
  • GET /configurations/active: Mostra la configurazione attiva
  • POST /configurations/{name}/test: Testa una configurazione
  • GET /providers: Elenca i provider disponibili

Esempio di Utilizzo dell'API

# Chat con l'agente
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Ciao, chi sei?"}'

# Elenca configurazioni
curl http://localhost:8000/configurations

# Aggiungi una configurazione
curl -X POST http://localhost:8000/configurations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mio-ollama",
    "provider": "ollama",
    "model_name": "gemma2:9b",
    "base_url": "http://192.168.0.50:11434",
    "set_active": true
  }'

Strumenti Unificati per Provider

MaxClaw Agent ora fornisce un'interfaccia unificata per gestire qualsiasi provider LLM. Una volta configurato un provider, puoi usare gli stessi comandi per tutti.

Provider Supportati

MaxClaw Agent supporta i seguenti provider:

  1. Ollama - Modelli locali
  2. OpenAI - GPT-4o, GPT-4o-mini, GPT-4-turbo, ecc.
  3. OpenRouter - Accesso a centinaia di modelli
  4. Anthropic - Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, ecc.
  5. Google - Gemini 1.5 Pro, Gemini 1.5 Flash, ecc.

Strumenti Disponibili per Ogni Provider

Per ogni provider configurato, hai accesso a:

  • {provider}_list_models: Elenca tutti i modelli disponibili
  • {provider}_model_info: Ottieni informazioni dettagliate su un modello
  • {provider}_test_connection: Testa la connessione al provider
  • {provider}_get_default_model: Mostra il modello predefinito
  • {provider}_set_default_model: Imposta un modello predefinito
  • {provider}_info: Mostra informazioni sulla configurazione del provider

Esempi di Utilizzo

# Con Ollama configurato:
"List available Ollama models"
"Test connection to Ollama"
"What's the default model for Ollama?"

# Con OpenAI configurato:
"List available OpenAI models"
"Test connection to OpenAI"
"Show me OpenAI configuration"

# Con OpenRouter configurato:
"List available OpenRouter models"
"Test connection to OpenRouter"
"Show me OpenRouter configuration"

# Con Anthropic configurato:
"List available Anthropic models"
"Test connection to Anthropic"
"Show me Anthropic configuration"

# Con Google configurato:
"List available Google models"
"Test connection to Google"
"Show me Google configuration"

Configurazione Automatica

Gli strumenti vengono caricati automaticamente in base alle variabili d'ambiente configurate:

# Se hai configurato Ollama:
export OLLAMA_BASE_URL="http://192.168.0.50:11434"
# → Verranno caricati automaticamente gli strumenti Ollama

# Se hai configurato OpenAI:
export OPENAI_API_KEY="sk-..."
# → Verranno caricati automaticamente gli strumenti OpenAI

# Se hai configurato OpenRouter:
export OPENROUTER_API_KEY="sk-or-..."
# → Verranno caricati automaticamente gli strumenti OpenRouter

# Se hai configurato Anthropic:
export ANTHROPIC_API_KEY="sk-ant-..."
# → Verranno caricati automaticamente gli strumenti Anthropic

# Se hai configurato Google:
export GOOGLE_API_KEY="AIza..."
# → Verranno caricati automaticamente gli strumenti Google

Strumenti Personalizzati

MaxClaw Agent include anche 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 (Legacy)

Gli strumenti Ollama specifici sono ancora disponibili per retrocompatibilità:

  • 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

Sistema di Plugin

MaxClaw Agent include un sistema di plugin per estendere le funzionalità.

Plugin Inclusi

  • Example Plugin: Plugin di esempio che dimostra come creare plugin

Creare un Plugin

Per creare un plugin, crea un file Python nella directory plugins/:

from plugins.base import BasePlugin
from langchain.tools import Tool

class MyPlugin(BasePlugin):
    def __init__(self):
        super().__init__(
            name="my_plugin",
            version="1.0.0",
            description="My custom plugin"
        )
    
    def get_tools(self):
        return [
            Tool(
                name="my_tool",
                func=self.my_tool_func,
                description="My custom tool"
            )
        ]
    
    def get_commands(self):
        return {
            "/mycommand": self.my_command_func
        }
    
    def my_tool_func(self):
        return "Hello from my plugin!"
    
    def my_command_func(self, args=None):
        return "My command executed!"

Gestire i Plugin

# Elenca i plugin disponibili
/plugins

# Carica tutti i plugin
python -c "from plugins.manager import plugin_manager; plugin_manager.load_all_plugins()"

# Usa un tool di un plugin
"Use my_tool from my_plugin"

# Usa un comando di un plugin
/mycommand

Supporto Multilingue

MaxClaw Agent supporta più lingue per l'interfaccia utente.

Lingue Disponibili

  • Italiano (it) - Predefinito
  • Inglese (en)

Cambiare Lingua

# Usa la variabile d'ambiente
export MAXCLAW_LANGUAGE=en

# Oppure usa il comando /language
/language en

Aggiungere una Nuova Lingua

Per aggiungere una nuova lingua:

  1. Crea un file JSON nella directory i18n/ (es. fr.json)
  2. Copia la struttura da en.json o it.json
  3. Traduci tutti i valori
  4. L'agente rileverà automaticamente la nuova lingua

Test

Esegui la suite di test:

# Esegui tutti i test
pytest tests/

# Esegui test specifici
pytest tests/test_config_manager.py
pytest tests/test_provider_tools.py

# Esegui con output verboso
pytest tests/ -v

Docker

Build dell'Immagine

docker build -t maxclaw-agent .

Esecuzione con Docker Compose

# Avvia tutti i servizi
docker-compose up -d

# Visualizza i log
docker-compose logs -f

# Ferma i servizi
docker-compose down

Variabili d'Ambiente Docker

Puoi configurare il container Docker con le seguenti variabili d'ambiente:

docker run -it --rm \
  -e MODEL_PROVIDER=ollama \
  -e MODEL_NAME=gemma2:9b \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e OPENAI_API_KEY=sk-... \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GOOGLE_API_KEY=AIza... \
  -e PROXMOX_HOST=192.168.0.100 \
  -e PROXMOX_USER=root \
  -e PROXMOX_PASSWORD=password \
  -e MAXCLAW_LANGUAGE=it \
  maxclaw-agent

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
  • Crea plugin per estendere le funzionalità

Monitoraggio e Logging

MaxClaw Agent include un sistema di monitoraggio e logging:

  • Log dettagliati: Tutte le azioni vengono registrate in ~/.maxclaw/logs/
  • Statistiche di sistema: Monitoraggio di uptime, richieste, errori
  • Metriche di performance: Tempi di risposta, utilizzo cache
  • Report di stato: Visualizzazione completa dello stato del sistema

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.

Reference in new issue View Git Blame Copy Permalink