Costruire un agente AI che funziona magnificamente sulla tua macchina locale? Facile. Costruirne uno che sopravvive al contatto con la realtà – gestendo rate limit, evitando loop infiniti, scalando oltre dati hardcoded – è tutta un’altra storia. Non si tratta solo di codice elegante. Si tratta di evitare bollette cloud fuori controllo, danni reputazionali da output allucinati, e il puro incubo operativo di un fallimento silenzioso in produzione.
Per risolvere questi pattern di “architettura fragile”, Google ha lanciato l’AI Agent Clinic. Prima missione: smontare completamente “Titanium” – un agente di ricerca sales promettente ma fragile. Nel primo episodio, Luis Sala si è seduto con Jacob Badish per ricostruirlo da zero. Il lavoro originale di Titanium era ricercare un’azienda target e scrivere un’email di outreach personalizzata. Il prototipo funzionava, ma era lento, si basava su uno script Python monolitico, ed era limitato a una lista hardcoded di appena 12 case study.
Nel corso di un’ora, il team ha demolito e ricostruito l’agente per la produzione. Ecco i breakdown principali, le fix, e le lezioni di ingegneria dall’Episodio 1.
1. Abbandona il monolite per sub-agenti orchestrati
Il problema: L’agente originale girava su un massiccio loop for lineare – uno script monolitico. Se un sub-task falliva (timeout API o allucinazione), l’intero processo si bloccava e falliva silenziosamente.
La fix: Hanno strappato via il monolite e installato un framework distribuito usando l’Agent Development Kit (ADK) di Google. Hanno creato una pipeline SequentialAgent, dividendo il carico di lavoro in nodi specializzati: Company Researcher, Search Planner, Case Study Researcher, Selector, e Email Drafter.
La lezione: Separazione delle responsabilità. Agenti specializzati con task ristretti funzionano più affidabilmente di un singolo LLM che cerca di eseguire un prompt massiccio multi-step.
2. Forza output strutturati (via Pydantic)
Il problema: Originalmente, Titanium forzava output JSON fuori dal modello via hardcoding estensivo direttamente nella stringa del prompt. Risultato: codice sporco, parsing fragile, e token sprecati a descrivere la struttura esatta ancora e ancora.
La fix: Passando ad ADK, hanno eliminato le istruzioni di formattazione schema dal prompt. Invece, hanno iniettato oggetti Pydantic nativi direttamente come definizioni schema esplicite. ADK usa Structured Outputs dinamicamente sotto il cofano per astrarre il boilerplate e forzare l’aderenza. Spostando il “contratto” da una richiesta fuzzy in linguaggio naturale a un oggetto Python validato a runtime, garantiscono integrità strutturale ed eliminano parsing custom fragile.
# PRIMA: Prompt String Bloat
prompt = """
Dammi la risposta in questo formato JSON:
{
"company": "Nome Azienda",
"pain_points": ["punto1", "punto2"]
}
"""
# DOPO: Pydantic Schema Injection in ADK
class CompanyIntel(BaseModel):
company: str
pain_points: list[str]3. Sostituisci lo stato hardcoded con una pipeline RAG dinamica
Il problema: Il corpus di contesto di Titanium era artificialmente minuscolo. Conosceva solo 12 case study hardcoded scritti direttamente nel file Python. Non poteva scalare o imparare senza che uno sviluppatore aggiornasse manualmente il codice.
La fix: Hanno costruito un sistema di intake dati dinamico. Un crawler async (Playwright) gira in background per scrapare autonomamente il sito customer success di Google Cloud e inviarli in batch a Google Cloud Vector Search. Nella pipeline, il Case Study Researcher esegue una vera Hybrid Search sul corpus indicizzato per recuperare i case study ideali.
(Nota: Hybrid Search combina il “significato” semantico di una query con la precisione del keyword matching esatto, assicurando che l’agente non perda termini tecnici specifici).
La lezione: L’hardcoding va bene per un prototipo, ma una pipeline di produzione deve refresharsi da sola. Il vero valore agentico viene dal dare agli agenti gli strumenti per fetch, scale e query autonomamente via Vector Search. Smetti di hardcodare i tuoi limiti di contesto.
4. L’osservabilità non è negoziabile
Il problema: Quando un LLM si confonde in uno script standard, è una “black box”. Sai che qualcosa è fallito, ma non hai idea di quale componente ha causato il break.
La fix: Hanno sfruttato il supporto first-class di ADK per OpenTelemetry su Google Cloud. Out of the box, ADK emette trace distribuite per flussi di esecuzione completi, catturando richieste del modello, token, ed esecuzioni di tool.
# Bootstrapping OTel in ADK è una one-liner
from adk.observability import configure_telemetry
configure_telemetry(project_id="my-gcp-project", enable_sse_stream=True)Hanno accoppiato questo backend OpenTelemetry con un’app streaming Server-Sent Events (SSE) su misura, progettando effettivamente una dashboard di telemetria live elegante per l’utente.
La lezione: Non puoi mettere un agente in produzione senza diagnostica live. Ti servono trace OpenTelemetry per risolvere dispute ground-truth e debuggare latenze dei singoli componenti.
5. Domare il token burn (ottimizzazione costi)
Il problema: I loop agentici sono costosi. Se un agente colpisce un errore e riprova continuamente un prompt senza boundary stretti, brucerà il tuo budget token in minuti.
La fix: Standardizzando pesantemente sull’orchestrazione native di ADK, hanno ereditato ottimizzazioni di costo intrinseche automaticamente. Il framework comprende nativamente exponential backoff, timeout boundary, e retry loop configurabili senza scrivere logica custom nel Python nativo.
La lezione: Installa sempre circuit breaker. Lascia che ADK o il tuo framework di orchestrazione gestisca fallimenti graziosi piuttosto che scrivere complessi loop try-catch retry nativamente.
Vuoi vedere il codice in azione?
Non c’è sostituto per guardare il rebuild del motore dal vivo. Guarda l’Episodio 1 completo dell’AI Agent Clinic per vedere esattamente come Titanium è stato refactorato. Puoi anche forkare il Titanium Repo.
Il tuo agente è rotto, buggy, o bloccato nel purgatorio del prototipo? Google vuole aiutare. Invia il tuo agente e la sua architettura a agent-clinic@google.com per avere la possibilità di vederlo diagnosticato e refactorato live nel prossimo episodio.
