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.

Diagnostica (/agy:status)

Il comando /agy:status apre un overlay TUI con lo stato dell'estensione:

• binario agy (trovato/non trovato) e versione
• chiave Gemini valida/mancante (mascherata) e stato
• modello attivo, backend STT, notifiche TTS
• ultimo errore significativo dai log di agy

Chiudi con Enter o Esc.

Context Injection (Fase 2) — pi → agy

Quando il tool agy (o altri con l'opzione injectContext) invia un prompt a Gemini, l'estensione inietta automaticamente un blocco di contesto prima della richiesta utente, seguendo le best practice di context engineering:

<environment_snapshot>   ← cwd, OS, data/ora, git branch + file modificati
<session_state>          ← ultimi messaggi utente pi (compatti, non il transcript)
<durable_memory>         ← archivio fatti chiave (memory.json, auto-aggiornato)
<web_context>            ← risultati ricerca web (Strada A, se pertinente)
--------------------------------
[ RICHIESTA UTENTE ]      ← sempre per ultima (anti lost-in-the-middle)

• Tag XML e richiesta per ultima (evidenze “Lost in the Middle”, TACL 2024)
• Token cap default ~1500 (chiave contextTokens)
• Memoria durevole automatica: oltre una soglia di turni, i punti chiave vengono condensati in ~/.config/agy-pi/memory.json invece di rigirare tutto
• Ricerca web (Strada A): con webSearch=auto|on l'estensione cerca con l'API Gemini (googleSearch grounding) e inietta i risultati nel <web_context>

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)
contextInject	true	Iniezione contesto nel prompt agy
contextTokens	1500	Token cap per il contesto iniettato
webSearch	auto	Ricerca web Strada A: auto | on | off
vocalPlanningMode	true	Piano + conferma in overlay dopo il vocale

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.

Con vocalPlanningMode=true (default) il flusso è a 2 fasi con overlay TUI: dopo la trascrizione, l'estensione genera un piano e mostra un popup di conferma con la trascrizione e il piano proposto:

🎙️ Conferma vocale
   Trascrizione: "Aggiorna i docs..."
   📋 Piano proposto: ...
   Enter esegui • Esc annulla • E modifica • F12 registra di nuovo

• Enter → esegue il piano (invia il risultato a pi)
• Esc → annulla, nessuna azione
• E → modifica il testo del piano manualmente
• F12 → registra di nuovo

Questa modalità evita che l'interpretazione vocale avvii autonomamente loop agentici o modifiche a sorpresa: la direttiva di Gemini è "produci solo il piano, non eseguire nulla", e l'esecuzione parte solo dopo la tua conferma. Per tornare all'esecuzione diretta, imposta vocalPlanningMode=false con /agy:config set vocalPlanningMode false.

Il testo scritto nel campo editor prima di avviare la registrazione viene letto (getEditorText) e combinato con la trascrizione audio nel piano, poi l'editor viene svuotato per evitare reinvii duplicati.

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