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.

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

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