# Strumenti Registrati (Tools) L'estensione `agy-pi` espone **14 strumenti (tools)** all'agente principale `pi`. Ciascun tool è definito tramite schemi strict `TypeBox` e fornisce istruzioni dettagliate al modello su come e quando utilizzarlo. --- ## Tabella Riassuntiva | Tool | Scopo Principale | Modalità | Timeout Default | |---|---|---|---| | [`agy`](#1-agy) | Subagent generico multi-turno (chat, image, analyze) | Dynamic | 180s | | [`agy_generate`](#2-agy_generate) | Generazione immagini strutturata | Image | 300s | | [`agy_edit`](#3-agy_edit) | Editing immagini controllato (Keep+Change+Add) | Image | 300s | | [`agy_inpaint`](#4-agy_inpaint) | Inpainting / In-place editing di zone specifiche | Image | 300s | | [`agy_style_transfer`](#5-agy_style_transfer) | Trasferimento di stile artistico | Image | 300s | | [`agy_compose`](#6-agy_compose) | Fusione / Composizione di più immagini | Image | 300s | | [`agy_character`](#7-agy_character) | Consistenza del personaggio tra generazioni | Image | 300s | | [`agy_analyze`](#8-agy_analyze) | Analisi file multimediali (immagini, audio, video) | Analyze | 180s | | [`agy_transcribe`](#9-agy_transcribe) | Trascrizione audio nativa via Gemini/enne2 API | API | 120s | | [`agy_video`](#10-agy_video) | Analisi e ispezione scene/codec file video | Analyze | 180s | | [`agy_tts`](#11-agy_tts) | Sintesi vocale Text-To-Speech nativa Gemini | API | 60s | | [`agy_models`](#12-agy_models) | Lista modelli disponibili su agy CLI | CLI | 30s | | [`agy_conversation`](#13-agy_conversation) | Ispezione e gestione stato conversazione | System | Instant | | [`agy_create_verified`](#14-agy_create_verified) | Generazione immagine iterativa con verifica | Image | 300s | --- ## Dettaglio degli Strumenti ### 1. `agy` Tool generico per delegare un task ad `agy`. Mantiene lo stato della conversazione (multi-shot reasoning). - **Parametri**: - `prompt` (`string`, obbligatorio): Il task da inviare ad agy. - `mode` (`"chat" | "image" | "analyze"`, opzionale): Tipo di operazione (default `"chat"`). - `model` (`string`, opzionale): Modello agy (es. `Gemini 3.1 Pro (High)`). - `effort` (`"low" | "medium" | "high"`, opzionale): Livello di reasoning. - `newConversation` (`boolean`, opzionale): Se `true`, azzera lo stato e parte da zero. - `addDir` (`string`, opzionale): Cartella da aggiungere al contesto di workspace agy. - `filePath` (`string`, opzionale): File da allegare. - `yolo` (`boolean`, opzionale): Abilita `--dangerously-skip-permissions`. - `injectContext` (`boolean`, opzionale): Abilita la context injection (default `true`). - `webSearch` (`boolean`, opzionale): Override ricerca web per questo prompt. --- ### 2. `agy_generate` Generazione da zero di immagini basata su formule narrative trasparenti per il modello Gemini Image Generation. - **Formula costruita**: `[Soggetto] + [Azione] + [Luogo] + [Composizione] + [Stile] + [Illuminazione] + [Aspect Ratio]` - **Parametri principali**: - `subject` (`string`, obbligatorio): Descrizione del soggetto primario. - `action`, `location`, `composition`, `style`, `lighting`, `aspectRatio` (`string`, opzionali). - `text` (`string`, opzionale): Testo grafico da incorporare. - `negative` (`string`, opzionale): Elementi da evitare. - `outputDir` (`string`, opzionale): Directory in cui salvare l'immagine generata. --- ### 3. `agy_edit` Modifica controllata di un'immagine esistente basata sulla regola **Keep + Change + Add + Render**. - **Best Practice Gemini**: Viene apportata una sola modifica per turno per evitare degrado dell'immagine base. - **Parametri principali**: - `baseImage` (`string`, obbligatorio): Percorso dell'immagine sorgente. - `keep` (`string`, obbligatorio): Elementi da mantenere inalterati (posa, luci, volto, ecc.). - `change` (`string`, obbligatorio): La modifica principale richiesta. - `add` (`string`, opzionale): Nuovi elementi da aggiungere. - `render` (`string`, opzionale): Target estetico di output (es. *"fotorealismo editoriale"*). - `preserveAspectRatio` (`boolean`, opzionale): Preserva la proporzione originale. --- ### 4. `agy_inpaint` Inpainting / Semantic Masking: modifica un elemento ben circoscritto senza alterare il contesto circostante. - **Parametri**: - `baseImage` (`string`, obbligatorio): Percorso immagine di partenza. - `target` (`string`, obbligatorio): Oggetto/area specifica da cambiare (es. *"la giacca del soggetto"*). - `replacement` (`string`, obbligatorio): Nuova descrizione dell'oggetto (es. *"un giubbotto in pelle nera"*). - `keepRest` (`string`, opzionale): Dettagli da preservare (default: *"tutto il resto"*). --- ### 5. `agy_style_transfer` Trasferimento di stile artistico preservando la composizione e i volumi dell'immagine base. - **Parametri**: - `baseImage` (`string`, obbligatorio): Immagine sorgente. - `style` (`string`, obbligatorio): Stile di destinazione (es. *"Acquerello Impressionista"*, *"Cyberpunk Neon"*, *"Disegno Tecnico"*). - `preserve` (`string`, opzionale): Cosa mantenere (default: *"la composizione originale"*). --- ### 6. `agy_compose` Combina da 2 a 14 immagini in un unico scatto armonioso. - **Parametri**: - `images` (`string[]`, obbligatorio): Elenco dei percorsi immagine. - `instruction` (`string`, obbligatorio): Istruzioni su quali elementi prendere da ciascuna immagine e come fonderli. --- ### 7. `agy_character` Garantisce la consistenza visiva di un personaggio o oggetto attraverso più scatti. - **Parametri**: - `referenceImage` (`string`, obbligatorio): Immagine di riferimento con la fisionomia del personaggio. - `name` (`string`, obbligatorio): Nome/Token identificativo (es. *"Avatar-Elena"*). - `features` (`string`, obbligatorio): Tratti somatici/caratteristici immutabili. - `task` (`string`, obbligatorio): Nuova azione o contesto in cui inserire il personaggio. --- ### 8. `agy_analyze` Analizza in dettaglio qualsiasi file multimediale supportato (immagini, tracce audio o video). - **Parametri**: - `filePath` (`string`, obbligatorio): Percorso del file. - `question` (`string`, opzionale): Domanda di analisi specifica. - `yolo` (`boolean`, opzionale): Auto-approvazione permessi CLI (obbligatorio per audio/video). --- ### 9. `agy_transcribe` Esegue la trascrizione audio ad alta velocità direttamente tramite le API Gemini (`gemini-3.5-flash`) o il server proxy `enne2`. - **Parametri**: - `filePath` (`string`, obbligatorio): File audio (WAV, MP3, OGG, M4A). - `language` (`string`, opzionale): Lingua parlata (es. `"italiano"`). --- ### 10. `agy_video` Ispezione approfondita di clip video: descrizione delle scene, analisi del movimento, verifica traccia audio, codec e risoluzione. - **Parametri**: - `filePath` (`string`, obbligatorio): Percorso del file video MP4/MOV/MKV. - `question` (`string`, opzionale): Quesito specifico sulla clip. --- ### 11. `agy_tts` Converte un testo in parlato e lo riproduce in locale tramite l'API Gemini TTS (`gemini-2.5-flash-preview-tts`). - **Parametri**: - `text` (`string`, obbligatorio): Testo da sintetizzare. - `play` (`boolean`, opzionale): Riproduci subito l'audio (default `true`). - `outputDir` (`string`, opzionale): Cartella di salvataggio del file WAV risultante. --- ### 12. `agy_models` Elenca i modelli LLM e Vision attualmente disponibili nell'installazione di `agy`. --- ### 13. `agy_conversation` Strumento di utilità di sistema per ispezionare o azzerare lo stato della conversazione. - **Parametri**: - `action` (`"id" | "list" | "reset"`, obbligatorio): Action richiesta. --- ### 14. `agy_create_verified` Genera un'immagine **conforme a requisiti specifici** tramite un loop iterativo self-contained: genera → analizza con visione → verifica con OpenCV dinamico → rigenera se necessario. Ideale quando l'orchestratore di `pi` **non ha visione**. Il loop (fino a `maxIterations`): ``` 1. Genera immagine con agy (mode image) dai requisiti 2. Analizza con visione testuale → giudice PASS/FAIL vs requisiti 3. Verifica con OpenCV DINAMICO → script generato dall'LLM ad hoc 4. Se FAIL → rigenera con prompt di correzione (ri-attacca immagine base) ``` La **verifica OpenCV è dinamica**: l'LLM genera a runtime uno script Python/OpenCV specifico per i requisiti dell'immagine (non metriche hardcodate), che restituisce un JSON standard: ```json {"pass": true/false, "score": 0..1, "findings": [...], "errors": [...]} ``` La decisione di conformità combina visione PASS + OpenCV PASS; le `findings` OpenCV vengono iniettate nelle issue per guidare la rigenerazione. - **Parametri**: - `requirements` (`string`, obbligatorio): Requisiti precisi che l'immagine deve soddisfare. - `outputDir` (`string`, opzionale): Cartella di salvataggio dell'immagine finale. - `maxIterations` (`number`, opzionale): Limite iterazioni (default 3, max 5). - `useOpenCV` (`boolean`, opzionale): Esegue la verifica OpenCV dinamica (default `true`). - `model` (`string`, opzionale): Modello agy.