agy-pi/docs/tools.md

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	Subagent generico multi-turno (chat, image, analyze)	Dynamic	180s
agy_generate	Generazione immagini strutturata	Image	300s
agy_edit	Editing immagini controllato (Keep+Change+Add)	Image	300s
agy_inpaint	Inpainting / In-place editing di zone specifiche	Image	300s
agy_style_transfer	Trasferimento di stile artistico	Image	300s
agy_compose	Fusione / Composizione di più immagini	Image	300s
agy_character	Consistenza del personaggio tra generazioni	Image	300s
agy_analyze	Analisi file multimediali (immagini, audio, video)	Analyze	180s
agy_transcribe	Trascrizione audio nativa via Gemini/enne2 API	API	120s
agy_video	Analisi e ispezione scene/codec file video	Analyze	180s
agy_tts	Sintesi vocale Text-To-Speech nativa Gemini	API	60s
agy_models	Lista modelli disponibili su agy CLI	CLI	30s
agy_conversation	Ispezione e gestione stato conversazione	System	Instant
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:

{"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.