Cosa insegna Shippy sul costruire agenti AI affidabili

Ai2 racconta l’architettura di Shippy, l’agente del team Skylight per il maritime domain awareness in tempo reale. In un dominio ad alto rischio, dove una risposta sbagliata può mandare un pattugliatore nella direzione errata, il lavoro vero non è il modello ma costruire un sistema affidabile, che resti entro i propri limiti e regga su una gamma ampia di task, verificato sui dati live di Skylight.

Anatomia dell’agente: soul, skills e config

Il team descrive Shippy come tre componenti. La soul è il system prompt che definisce persona e confini di comportamento. Le skills spiegano come gestire tipi specifici di richieste e seguono l’agent-skills spec usata da tool di coding come Claude Code e Codex, cioè file markdown con frontmatter strutturato. Soul e skills sono impacchettate in un’immagine Docker versionata. La config copre il resto: quale harness (OpenClaw, framework open source), quale LLM (attualmente Claude Opus 4.6) e i runtime setting. Cambiare modello o harness è una modifica di config, non un rebuild. I limiti sono espliciti nel prompt: Shippy non emette valutazioni legali e non specula oltre ciò che i dati supportano, scelte auditabili invece che implicite nel fine-tuning.

Tool deterministici e isolamento

Poiché gli agenti sono non deterministici, il team rende prevedibili i tool. Shippy non costruisce chiamate API grezze: usa una CLI dedicata che gestisce autenticazione, paginazione e output strutturato, scritto su file JSON locale invece che nella shell. Nei primi prototipi le chiamate costruite da zero producevano bug sottili, come paginazione malformata o errori di encoding delle geometrie. La stratificazione (API tipizzata, CLI deterministica, skills che richiamano i comandi della CLI) permette di testare ogni componente in isolamento. Sul fronte multi-tenant, Skylight serve oltre 300 partner in più di 70 paesi: ogni utente parla con Shippy in una sessione effimera e isolata, provisionata da Mothership, piattaforma che crea un deployment Kubernetes dedicato per sessione con il JWT dell’utente iniettato a runtime.

Valutare un agente, non un modello

I benchmark generici non catturano come un agente seleziona i tool, interroga dati live e sa dove fermarsi. Ai2 ha quindi costruito un eval che valuta l’intero agente (modello, skills e sandbox) contro dati reali: esperti di dominio scrivono scenari e rubriche, pesano i criteri per task e annotano le risposte come corrette o meno; un LLM judge assegna un punteggio da 0 a 1 con motivazione scritta, e l’aggregato pesato viene confrontato con una soglia fissa. La suite gira su Harbor a ogni cambio di skill, modello o dati, e una versione che regredisce non arriva agli utenti.

• Separare soul, skills e config rende il comportamento dell’agente versionato, auditabile e modificabile senza rebuild.
• Interporre una CLI tipizzata tra agente e API riduce i bug rispetto a lasciare che il modello costruisca chiamate grezze.
• Tra i prossimi passi: model routing verso modelli più piccoli per le richieste semplici, controllo diretto della UI della mappa e memoria cross-thread.

Fonte: What building Shippy taught us about building agents — https://huggingface.co/blog/allenai/shippy-tech-blog