SDK Antigravity: cos'è, come installarlo e creare il primo agente

Che cos'è l'SDK Antigravity?

Un SDK permette a un'applicazione di chiamare una capacità del prodotto in modo supportato. L'SDK Antigravity consente di definire un agente, collegare strumenti approvati e usare un risultato da Python. È adatto ad assistenti interni, test e flussi ripetibili.

La distinzione principale riguarda chi possiede il flusso: l'IDE serve per il lavoro interattivo, la CLI per i comandi da terminale e l'SDK per il programma che orchestra il processo. Possono completarsi, ma non condividono una versione o configurazione universale.

Come installare l'SDK Antigravity per Python

Inizia dalla pagina ufficiale introduttiva dell'SDK e dai metadati PyPI attuali. Controlla Python, extra, autenticazione e import invece di copiare uno snippet vecchio. Usa un ambiente e un progetto usa e getta, conserva i segreti fuori da Git e fai una richiesta reversibile.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. Crea un ambiente isolatoUsa un ambiente virtuale locale per rendere prevedibili la risoluzione dei pacchetti e il rollback.
2. Installa dalla fonte mantenutaSegui le istruzioni ufficiali del pacchetto, inclusi gli eventuali extra o passaggi di autenticazione aggiornati.
3. Blocca la versione solo dopo un test riuscitoEsegui l'esempio più piccolo e registra la versione e il runtime Python che hanno superato la prova.
4. Tieni la configurazione fuori dai commitUsa variabili d'ambiente o un secret store e ignora i file di configurazione locali.
5. Leggi le note di rilascio prima di aggiornareLe API dell'SDK possono cambiare indipendentemente dall'app desktop, dalla CLI o dall'IDE.

Conferma i requisiti Python e le istruzioni attuali prima della produzione.

Crea un primo agente piccolo

Un buon primo agente ha un compito, un'istruzione e un risultato verificabile. Riassumi una nota breve o classifica un fixture locale. Non aggiungere subito browser, shell, database e scrittura: isolare gli errori sarebbe più difficile.

Classi e proprietà dipendono dalla versione corrente dell'SDK. L'esempio mostra il flusso base: configura, richiedi, ispeziona e segui il ciclo documentato. Usalo come schema, non come promessa permanente dell'API.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• Input — Usa un fixture breve con una risposta attesa.
• Risultato — Ispeziona il risultato prima di aggiungere automazione.
• Ciclo di vita — Segui il ciclo di vita e il comportamento dei retry documentati.
• Ripetibilità — Salva prompt, versione, impostazioni e risultato osservato.

Aggiungi gli strumenti uno alla volta

Gli strumenti collegano il ragionamento dell'agente a un'azione esterna. Scegli l'azione minima utile, definisci un contratto di input ristretto, valida gli argomenti e restituisci un risultato limitato. Registra identificatori sicuri; non esporre la home directory e non concedere scrittura quando basta la lettura.

Usa i subagenti per compiti separati

Un subagente è utile quando un'attività ha un ruolo distinto, ad esempio pianificazione, recupero, validazione o formattazione. Dai a ogni ruolo confini chiari di input e output; un planner non dovrebbe ereditare le credenziali del validator.

Inizia in sequenza per rendere ispezionabile ogni passaggio. Aggiungi parallelismo, timeout e retry quando i confini sono stabili, lasciando visibili i fallimenti parziali.

Restituisci un output strutturato affidabile per il programma

Il testo libero è comodo per una persona, ma fragile per la logica. Se il risultato alimenta database, UI, test o agenti, usa l'output strutturato corrente dell'SDK con uno schema piccolo e validalo localmente.

Uno schema non rende vera la risposta: controlla tipi, valori consentiti e campi obbligatori. Separa la diagnostica dall'output destinato all'utente.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• Valida localmente l'oggetto restituito.
• Usa enum e stringhe con lunghezza limitata per scelte finite.
• Tratta i campi mancanti o malformati come un errore visibile.
• Separa la diagnostica dall'output destinato all'utente.

SDK, IDE e CLI: scegli la superficie giusta

L'SDK incorpora un flusso agentico nel codice; l'IDE serve per progetti interattivi e la CLI per comandi e script. Scegli la superficie proprietaria del lavoro, non tre pulsanti per lo stesso flusso.

Le release possono seguire calendari diversi: registra fonte e data del componente usato.

Controlli di sicurezza e affidabilità prima di ampliare l'uso

Un SDK può rendere un agente parte di un'applicazione reale. Esamina provenienza del pacchetto, credenziali, rete, percorsi, argomenti e log. Inizia con un progetto usa e getta e un account di test se accedi a dati esterni.

Mantieni visibile l'approvazione per modificare file, inviare messaggi, spendere, cambiare account o pubblicare. Usa timeout e retry limitati e distingui input non valido, servizio indisponibile, permesso negato e revisione umana.

• Credenziali — Usa un secret store; non salvare token in Git e non inserirli nei prompt.
• Percorsi — Consenti solo le directory del progetto necessarie, non la radice del disco o la home.
• Azioni — Separa letture, scritture, shell, browser e chiamate di rete.
• Osservabilità — Registra ID, durate, esiti e categorie di errore sicure.
• Recupero — Documenta come disabilitare, revocare l'accesso, ripetere un fixture e fare rollback.

Problemi comuni dell'SDK Antigravity

Quando la prima esecuzione fallisce, riduci il sistema a una variabile alla volta.

Il pacchetto si installa ma l'import fallisce

Conferma ambiente e interprete, poi confronta l'import con il quickstart attuale. Controlla i metadati prima di modificare il codice.

L'agente restituisce un errore di autorizzazione

Confronta credenziali, ambito e permessi con la documentazione corrente. Rimuovi i segreti dai log e ripeti la richiesta minima.

Una chiamata allo strumento si blocca o si ripete

Aggiungi un timeout, registra il confine e prova con un input fisso. Limita i retry e non ripetere una scrittura sconosciuta.

L'output strutturato è incompleto

Riduci lo schema e valida localmente i campi obbligatori. Tratta rifiuto, troncamento o dati malformati come revisione.

Snapshot delle versioni e regola della fonte ufficiale

Il 12 settembre 2026 PyPI mostrava google-antigravity v0.1.16. Gli elenchi ufficiali mostravano desktop v2.13.0, CLI v1.2.0 e IDE v2.5.5; avanzano separatamente.

Usa pagine ufficiali aggiornate e registra la versione installata. La pagina dei download resta il riferimento alternativo per desktop e CLI.