# Strumenti e Capacità

## Panoramica

Gli strumenti sono le azioni che i tuoi agenti possono compiere durante le conversazioni. Quando un agente ha bisogno di navigare sul web, eseguire un comando, leggere un file o controllare un dispositivo, usa gli strumenti.

Neotask fornisce un ricco set di strumenti integrati che coprono la gestione dei file, l'esecuzione di codice, l'automazione del browser, il controllo dei dispositivi, la messaggistica, la ricerca web e altro ancora.

## Operazioni sui File

Gli agenti possono leggere, scrivere e modificare file nel loro workspace:

- **Read**, Leggi il contenuto dei file
- **Write**, Crea o sovrascrivi file
- **Edit**, Apporta modifiche mirate a parti specifiche di un file
- **Apply Patch**, Applica diff unificati multi-hunk per modifiche complesse ai file

## Esecuzione di Codice

Gli agenti possono eseguire comandi shell con isolamento configurabile:

- **Esecuzione sul Gateway**, Esegui comandi direttamente sulla macchina che ospita il Gateway
- **Esecuzione in sandbox**, Esegui comandi in container Docker isolati con limiti di risorse
- **Esecuzione su nodo**, Esegui comandi su dispositivi companion connessi (nodi macOS, Linux)

### Funzionalità di Esecuzione
- Timeout configurabili (default 30 minuti)
- Gestione dei job in background (elenco, polling, terminazione, pulizia)
- Auto-background per comandi a lunga esecuzione
- Supporto TTY per programmi interattivi
- Modalità elevata per operazioni con privilegi (solo host del gateway)

### Flussi di Approvazione
I comandi sensibili possono richiedere l'approvazione dell'utente prima dell'esecuzione:
- **Allowlist**, Solo i comandi pre-approvati vengono eseguiti
- **Ask**, I comandi sconosciuti richiedono l'approvazione
- **Full**, Nessuna restrizione

## Automazione del Browser

Gli agenti controllano un browser completo basato su Chromium (Chrome, Brave o Edge):

### Azioni
- **Navigate**, Apri URL e naviga tra le pagine
- **Interact**, Clicca, digita, passa il mouse, trascina, seleziona, compila form
- **Capture**, Fai screenshot, esporta PDF
- **Inspect**, Crea snapshot del DOM o dell'albero di accessibilità
- **Execute**, Esegui JavaScript nel contesto della pagina
- **Upload**, Carica file su form web
- **Manage**, Gestisci dialoghi (avvisi, conferme), leggi l'output della console

### Profili del Browser
Più profili browser isolati per separare gli account:
- Ogni profilo ha i propri cookie, storage e cronologia
- Porte CDP assegnate automaticamente per il controllo programmatico
- Supporto browser remoto (connettiti a browser su altre macchine)

## Canvas e A2UI

Il sistema Agent-to-UI (A2UI) permette agli agenti di renderizzare contenuti visivi interattivi sui dispositivi connessi:

- **Present**, Visualizza pagine web o contenuti personalizzati sul canvas di un dispositivo
- **Navigate**, Controlla cosa viene mostrato nella finestra del canvas
- **Evaluate**, Esegui JavaScript nel contesto del canvas
- **Snapshot**, Cattura ciò che viene attualmente visualizzato
- **A2UI Push**, Invia aggiornamenti UI strutturati (payload JSONL) al canvas
- **A2UI Reset**, Cancella lo stato del canvas

Il rendering del canvas è disponibile su macOS (WebKit), iOS (SwiftUI), Android (Jetpack Compose) e web (WebChat).

## Capacità dei Dispositivi Node

Tramite le app companion connesse, gli agenti possono:

### Fotocamera
- **Snap**, Scatta foto (fotocamera frontale o posteriore)
- **Clip**, Registra clip video con durata e FPS configurabili

### Schermo
- **Record**, Cattura registrazioni dello schermo con durata e qualità configurabili

### Posizione
- **Get**, Recupera le coordinate GPS con selezione della precisione

### Notifiche
- **Notify**, Invia notifiche OS native con titolo, corpo e priorità

### Comandi di Sistema
- **Run**, Esegui comandi shell sul dispositivo nodo
- **Which**, Controlla se un comando è disponibile sul nodo

## Messaggistica

Gli agenti possono inviare e gestire messaggi sui canali connessi:

- **Send**, Invia messaggi a qualsiasi canale/destinatario connesso
- **Edit**, Modifica messaggi inviati in precedenza
- **React**, Aggiungi reazioni ai messaggi
- **Thread**, Crea thread e rispondi al loro interno
- **Poll**, Crea sondaggi sulle piattaforme supportate
- **Voice**, Controlla lo stato del canale vocale (Discord)

## Web

- **Search**, Ricerca web tramite Brave Search API
- **Fetch**, Recupera pagine web e converti HTML in markdown/testo

## Memoria e Contesto

- **Memory Search**, Ricerca per somiglianza vettoriale nei file di memoria dell'agente
- **Memory Get**, Recupera file di memoria specifici per nome

## Gestione delle Sessioni

- **List Sessions**, Visualizza le sessioni attive tra gli agenti
- **Session History**, Recupera la trascrizione di qualsiasi sessione
- **Send to Session**, Invia messaggi ad altre sessioni degli agenti
- **Spawn Sub-Agent**, Avvia esecuzioni isolate di sotto-agenti
- **List Agents**, Visualizza gli agenti disponibili

## Automazione

- **Cron**, Crea, modifica, esegui e gestisci job pianificati
- **Gateway**, Riavvia il gateway, applica modifiche alla configurazione, esegui aggiornamenti

## Analisi delle Immagini

Gli agenti possono analizzare immagini usando modelli di visione configurati, descrivere il contenuto, estrarre testo, identificare oggetti e rispondere a domande sul contenuto visivo.

## Gruppi di Strumenti

Gli strumenti sono organizzati in gruppi per una gestione semplice dei permessi:

| Gruppo | Strumenti |
|-------|-------|
| **runtime** | exec, bash, process |
| **fs** | read, write, edit, apply_patch |
| **sessions** | sessions_list, sessions_history, sessions_send, sessions_spawn, session_status |
| **memory** | memory_search, memory_get |
| **web** | web_search, web_fetch |
| **ui** | browser, canvas |
| **automation** | cron, gateway |
| **messaging** | message |
| **nodes** | nodes |