Costruire un agente è soprattutto un processo di gestione: strumenti, stato, regole di controllo, scalabilità da un singolo agente a molti. CUGA (con comando "pip install cuga"), abbreviazione di Configurable Generalist Agent, è il framework per agenti open-source di IBM che si occupa proprio di quest'aspetto, permettendoti di focalizzarti solo sulla lista degli strumenti e sul prompt.
Per dimostrare quanto ciò faciliti lo sviluppo, IBM ha realizzato due dozzine di app demo, ognuna costituita da un file singolo FastAPI che avvolge un'istanza di CugaAgent, dagli consiglieri di film agli architetti di reti IBM Cloud. Puoi navigare e interagire con queste esemplificazioni tramite la galleria online.
L'articolo introduce una di queste applicazioni, spiega come CUGA gestiscagli aspetti complicati e mostra come lo stesso codice possa essere regolato in produzione senza riscrittura.
Cosa evita di dover programmare CUGA?
L'idea comune di ogni spazio dedicato alle applicazioni agentiche è: cosa ti permette di non riscrivere? CUGA risponde che evita di rigenerare una volta per volta l'integrazione attorno a un modello.
Esso pianifica prima di agire, quindi esegue con una combinata di chiamate agli strumenti e codice generato (CodeAct). Nelle compiti lunghe che si sviluppano su molteplici passi, la cosa che rompe la maggior parte degli agenti non è l'approccio iniziale ma il perdersi i risultati intermedi e reinterpretarli male. CUGA tratta lo stato come memoria e introduce una fase di riflessione in grado di rivedere una decisione malriportata senza procedere meccanicamente, mantenendo l'impostazione coerente. Per questo motivo si colloca all'avanguardia in benchmark come AppWorld e WebArena.
Modabilità e configurabilità
Puoi regolare le preferenze su costo/latenza semplicemente attraverso la configurazione, non la programmazione diretta: modi di ragionamento Fast, Balanced e Accurate, con codice eseguito in qualsiasi sandbox tu preferisci (locale, Docker/Podman o cloud E2B). La stessa definizione dell'agente, diversi scenari: questo dettaglio appare più significativo di quanto sembri.
La maggior parte degli strumenti di supporto aiuta un modello di frontiera nella riparazione quando la pianificazione si rovescia; CUGA si occupa di tutto questo lavoro autonomamente, riducendo il carico sul modello. Questa capacità di pianificare, riflettere e mantenere il tracciamento variabile permette a modelli open-source più piccoli di svolgere compiti di livello dove normalmente non sarebbero adeguati. Per la galleria ospitata, funziona su gpt-oss-120b piuttosto che su un modello di frontiera API.
Nessun singolo elemento del pacchetto di CUGA è esclusivo. La differenza sta nel fatto che vengono forniti già integrati, configurabili non installati. L'utente ha a disposizione solo una semplice API — costruisci un CugaAgent con una lista di strumenti e un prompt — e inoltre puoi richiamare asincronamente "agent.invoke(...)."
Differenti strumenti, un unico framework
Nel concreto, CUGA fornisce strumenti intercambiabili (OpenAPI, MCP, e funzioni LangChain si vincolano allo stesso formato), una pianificazione a orizzonte lungo con gestione variabile e autocorrezione, regole preventive, delega multi-agente su A2A, RAG alimentato da Docling, cambio provider dichiarativo con una variabile di ambiente e supporto alle piattaforme più note (OpenAI, Watsonx, Ollama e altri), tutte installabili con "pip install cuga".
I vantaggi di base
L'avverbio iniziale del nome è essenziale: "Configurable". Le parti complicate sono gestite in automatico, lasciando a te soltanto il lavoro legato al compito.
Consigliatore IBM Cloud
Consideriamo ad esempio l'agente CUGA che consiglia servizi IBM Cloud specifici per un'architettura; l'app intera si sviluppa in un unico file: un "main.py" che incapsula il costruttore dell'agente, gli strumenti utilizzati e il prompt, più un piccolo interfaccia grafica.
Gli invariabili utilizzati
Quattro argomenti sono centrali: il modello utilizzato proviene da un piccolo costruttore (createllm) che è capace di comunicare con OpenAI, Anthropic, Watsonx, LiteLLM o Ollama in base a una variabile d'ambiente. Il codice dell'app non sa in anticipo a quale modello si affidi. Il "cugafolder" è il punto dove l'app memorizza lo stato e le politiche utilizzate. Gli argomenti chiave dell'app sono "tools" e "special_instructions" che determinano il funzionamento.
Piano strumentale
Questa organizzazione si mantiene costante in ogni app: una scissione tra strumenti MCP e strumenti inline. La capacità generale e senza stato deriva dai server MCP condivisi; "loadtools(['web'])" include la ricerca web senza bisogno di hostare niente. Qualsiasi funzione specifica a questa applicazione è scritta inline come una funzione Python normale, tipo "searchibm_catalog", di cui il costruttore legge la descrizione per decidere quando invocarla. Scrivi lo strumento tuo e presta gli altri.
Insieme, promemoria e azione
Il prompt di questo assistente su IBM Cloud richiama il catalogo prima di nominare un servizio, consiglia da tre a sette servizi con il loro ruolo nel design e mai invenzioni. Quest'ultima regola si ripaga: un consigliere IBM Cloud che fa nomi di servizi inesistenti è peggio di nessun consigliere, quindi il prompt obbliga ogni raccomandazione ad attraversare prima una ricerca nel catalogo. Promemoria scritti in passaggi ordinati con regole esplicite "non inventare" funzionano bene; promemoria scritti come personaggi immaginari vanno spesso male.
Architettura di base
Sull'interfaccia: una struttura chiara. C'è uno strumento, una procedura, quattro righe di costruttore. Il codice FastAPI che lo circonda è software web comune: il browser presenta una domanda a un endpoint "/ask", e il pannello visualizza lo stato in tempo reale percorrendo "/session/{threadid}". Non c'è bisogno di un database; lo stato è un dizionario Python per threadid, che soltanto l'agente modifica attraverso i suoi strumenti. Nel momento in cui l'agente chiama uno strumento durante l'esecuzione, il pannello si rigenera. Non vi è un secondo set di logiche nella UI; essa mostra lo stato modificato dall'agente.
Convenzione critica
Un dettaglio che potrebbe sembrare insignificante rivela una funzionalità cruciale: ogni strumento inline restituisce lo stesso piccolo contenitore. Successo apparirà come {"ok": true, "data": {...}}; errore apparirà come {"ok": false, "code": "...", "error": "..."}