agy-pi/README.md

agy-pi

Estensione per pi che integra Google Antigravity CLI (agy) come subagent multimodale.

Anche se il modello di pi è text-only, questa estensione permette a pi di delegare a agy (che usa Gemini multimodale) task che richiedono immagini, audio e video, oltre a conversazioni di ragionamento multi-turno.

Capacità

Capacità	Tool	Esempio
Conversazione multi-turno	agy	agy(prompt="Analizza questo problema...")
Generazione immagini (strutturata)	agy_generate	agy_generate(subject="un gatto", style="fotorealistico")
Editing controllato (Keep+Change+Add+Render)	agy_edit	agy_edit(baseImage=..., change="...", keep="...")
Editing zona specifica (inpainting)	agy_inpaint	agy_inpaint(baseImage=..., target="il divano", replacement="blu navy")
Style transfer	agy_style_transfer	agy_style_transfer(baseImage=..., style="Van Gogh")
Composizione multi-immagine	agy_compose	agy_compose(images=[...], instruction="...")
Consistenza personaggio	agy_character	agy_character(referenceImage=..., name="Maya", task="...")
Analisi file (imm/audio/video)	agy_analyze	agy_analyze(filePath=..., question="...")
Trascrizione audio	agy_transcribe	agy_transcribe(filePath="voce.wav", language="italiano")
Analisi video	agy_video	agy_video(filePath="clip.mp4", question="...")
Elenco modelli	agy_models	agy_models()
Gestione stato conversazione	agy_conversation	agy_conversation(action="id" | "list" | "reset")

L'agente (pi) decide autonomamente quale strumento usare in base al task richiesto.

Configurazione persistente (/agy:config)

Tutte le impostazioni dell'estensione si gestiscono con il comando /agy:config (salvate in ~/.config/agy-pi/config.json, permessi 600):

/agy:config                    # elenca tutte le impostazioni
/agy:config get <chiave>       # mostra una chiave
/agy:config set <chiave> <valore>  # imposta una chiave
/agy:config reset              # ripristina i default

Dialog TUI per la chiave Gemini (/agy:key)

Per inserire/modificare la chiave API Gemini con un'interfaccia grafica in sovrimpressione (dialog TUI, campo mascherato) usa il comando /agy:key:

/agy:key

Apre un overlay centrato nel terminale:

• mostra la chiave attuale mascherata (AIza...yfDY)
• campo di input mascherato (digiti la chiave, vedi •)
• Enter conferma (salva in config + ~/.agy-chat/gemini-key)
• Esc annulla

È il modo interattivo e sicuro per impostare geminiApiKey senza digitarla in chiaro nella cronologia del terminale.

Chiave	Default	Descrizione
geminiApiKey	—	Chiave API Google Gemini (STT/TTS)
enne2ApiKey	—	Token per il server proxy ai.enne2.net (opzionale)
sttBackend	gemini	Backend trascrizione: gemini | enne2
sttUrl	https://ai.enne2.net	URL base backend enne2
sttModel	gemma4:E4B	Modello STT backend enne2
sttMaxDuration	120	Durata max registrazione (secondi)
ttsBackend	gemini	Backend TTS: gemini | enne2
ttsNotify	true	Notifiche vocali automatiche
ttsModel	gemini-2.5-flash-preview-tts	Modello TTS Gemini
agyBin	agy	Path del binario agy
agyDefaultModel	—	Modello predefinito per le chiamate agy
agyTimeoutMs	180000	Timeout esecuzione agy (ms)

Le variabili d'ambiente (GEMINI_API_KEY, AGY_STT_BACKEND, ecc.) hanno priorità sul file di config quando impostate.

Registrazione microfono (F12)

Premi F12 per avviare/fermare la registrazione dal microfono (max 2 min). Il flusso: registra → taglia il silenzio → trascrive con la Gemini API diretta (gemini-3.5-flash, veloce e affidabile — agy CLI non supporta file audio) → interpreta con Gemini usando il contesto della conversazione → inserisce il risultato come prompt su pi.

Requisito: la key Gemini API in ~/.agy-chat/gemini-key (chmod 600) o nella variabile d'ambiente GEMINI_API_KEY.

# una volta sola
echo "LA_TUA_KEY" > ~/.agy-chat/gemini-key && chmod 600 ~/.agy-chat/gemini-key

Backend di trascrizione (variabile AGY_STT_BACKEND):

Backend	Descrizione	Configurazione
gemini (default)	Gemini API (gemini-3.5-flash), veloce e affidabile	key in ~/.agy-chat/gemini-key
enne2	Server locale ai.enne2.net con gemma4:E4B (supporta audio), ~2-3s	AGY_STT_URL (default https://ai.enne2.net), AGY_STT_MODEL (default gemma4:E4B)

# usa il server locale
export AGY_STT_BACKEND="enne2"

Comandi: /agy:record (toggle), /agy:record:stop (ferma).

Installazione

Requisito: agy installato e autenticato (una volta: agy, poi login OAuth nel browser).

# da un repo git
pi install git:github.com/<tuo-utente>/agy-pi

# oppure da una cartella locale
pi install /percorso/a/agy-pi

Per provare senza installare:

pi -e /percorso/a/agy-pi

Uso

Come tool (chiamato automaticamente dal modello)

Quando chiedi a pi di generare un'immagine, analizzare un file, o ragionare insieme a un secondo agente, pi può chiamare il tool agy. Esempi di prompt:

Genera un'immagine di un paesaggio marziano al tramonto.
Analizza l'immagine /home/utente/foto.jpg e descrivila.
Trascrivi il file audio /home/utente/voce.wav.
Chiedi a agy di ragionare su questo problema e poi confronta la sua risposta con la tua.

Come comando interattivo

/agy <prompt>        # invia un prompt a agy
/agy:new             # forza una nuova conversazione
/agy:list            # mostra la conversazione corrente
/agy:reset           # azzera lo stato conversazione

Parametri del tool agy

Parametro	Tipo	Descrizione
prompt	string (obbligatorio)	Il task/prompt per agy
mode	chat | image | analyze	Tipo di operazione (default chat)
model	string	Modello agy (es. Gemini 3.1 Pro (High), Claude Opus 4.6 (Thinking))
effort	low | medium | high	Livello di ragionamento
newConversation	boolean	Forza una nuova conversazione
addDir	string	Cartella da aggiungere al workspace agy
filePath	string	File (immagine/audio/video) da analizzare
yolo	boolean	--dangerously-skip-permissions (necessario per audio/video)

Multi-turno

L'estensione mantiene l'ID della conversazione agy in ~/.agy-chat/conversation_id. Ogni chiamata a agy continua la conversazione precedente, così agy ricorda i turni precedenti (ragionamento multi-shot). Usa newConversation: true per ripartire da zero.

Note di sicurezza

• yolo: true auto-approva tutti gli strumenti di agy. Usalo solo in ambienti fidati.
• Le estensioni pi girano con i permessi completi del sistema. Rivedi il codice prima di installare pacchetti di terze parti.

Struttura

agy-pi/
├── package.json          # manifest pi
├── extensions/index.ts   # estensione (tool + comandi)
├── bin/agy-chat.sh       # wrapper bash standalone (opzionale)
└── README.md