Guida Mirage per sviluppatori

Guida Mirage per sviluppatori

Indice dei Contenuti – Guida Mirage per sviluppatori

1. Introduzione: il problema che Mirage risolve

2. Origini e fondatore: strutko.ai e il lancio del 2026

3. A cosa serve Mirage

4. Architettura di Mirage

5. Installazione e configurazione

6. Esempi pratici con Python

7. Esempi pratici con TypeScript

8. Integrazione con i framework AI più diffusi

9. Il sistema di caching

10. Best practice, pro e contro

11. Conclusioni e formazione continua

1. Introduzione: il problema che Mirage risolve

Se stai sviluppando agenti AI che devono accedere a più servizi contemporaneamente, un bucket S3, un canale Slack, una repository GitHub, un documento su Google Drive, sai bene quanto può diventare complessa la gestione delle integrazioni. Per ogni servizio occorre un SDK diverso, configurazioni separate, e codice di glue che cresce in modo difficilmente manutenibile.

Mirage nasce proprio per eliminare questa complessità: è un filesystem virtuale unificato per agenti AI, che monta servizi eterogenei come se fossero cartelle di un unico disco. Il risultato è che un agente LLM può leggere un file CSV da S3, cercare messaggi su Slack e aprire un documento Google Docs usando gli stessi comandi bash che già conosce.

2. Origini e fondatore: strukto.ai e il lancio del 2026

Se si scrive una Guida Mirage per sviluppatori non si può non iniziare dalle sue origini. Mirage è un progetto open source sviluppato da strukto.ai, una startup focalizzata sull’infrastruttura per agenti AI. Il repository pubblico è stato creato il 6 maggio 2026 su GitHub, dove ha rapidamente raccolto centinaia di star grazie alla semplicità concettuale e alla forte utilità pratica.

Il progetto è distribuito con licenza Apache 2.0, dispone di SDK ufficiali per Python (>= 3.12) e TypeScript/Node.js (>= 20), ed è supportato da una documentazione dedicata su docs.mirage.strukto.ai. La prima release pubblica (v0.0.1) è uscita a maggio 2026, segnalando che il progetto è ancora in fase early-stage ma già funzionante e integrabile in progetti reali.

3. A cosa serve Mirage

Mirage risolve uno dei problemi architetturali più comuni nello sviluppo di agenti AI moderni: la frammentazione delle sorgenti dati. In un tipico workflow multi-agente, un LLM deve:

• leggere file da storage cloud (S3, GCS, R2)
• consultare documenti aziendali (Google Drive, Notion, Trello)
• interagire con comunicazioni di team (Slack, Discord, Gmail)
• accedere a repository di codice (GitHub, Linear)
• lavorare con database (MongoDB, Redis)

Tradizionalmente tutto questo richiedeva integrazioni separate per ogni sorgente. Con Mirage, ogni servizio viene montato come una directory sotto un unico albero filesystem. L’agente, che sia Claude Code, OpenAI Agents SDK, LangChain o qualsiasi sistema capace di eseguire bash, interagisce con tutti i backend attraverso comandi familiari come ls, cat, cp, grep.

Il principio chiave è brillante nella sua semplicità: i modelli LLM moderni sono stati addestrati su enormi quantità di testo che include documentazione bash e Unix. Sfruttare questo vocabolario già presente nel modello, invece di insegnare nuove API, riduce il friction e aumenta la affidabilità degli agenti.

4. Architettura di Mirage – Guida Mirage per sviluppatori

L’architettura di Mirage è stratificata in tre livelli principali:

• Layer Applicazione/Agente: il tuo agente AI o la tua applicazione comunica con Mirage tramite comandi bash o tramite SDK Python/TypeScript. Questo layer è compatibile con Claude Code, Codex, OpenAI Agents SDK, Vercel AI SDK, LangChain e altri framework.
• Layer VFS + Bash: il nucleo del sistema. Espone un’interfaccia filesystem virtuale (VFS) e un interprete bash che traduce i comandi in operazioni sui backend sottostanti. Ogni mount point (/s3, /slack, /github, ecc.) corrisponde a un Resource specifico.
• Layer Dispatcher + Cache: gestisce il routing delle operazioni verso i backend reali (S3, Google Drive, Slack, etc.) e implementa un sistema di caching a due livelli (index cache e file cache) per minimizzare le chiamate di rete.

Il Workspace è l’oggetto centrale: rappresenta l’ambiente di lavoro dell’agente, contiene tutti i mount point e permette di eseguire comandi. I Workspace sono portabili: possono essere serializzati in file .tar, clonati e spostati tra macchine senza riconfigurazioni.

5. Installazione e configurazione

Installazione Python

# Installa il pacchetto mirage-ai con uv (raccomandato)

uv add mirage-ai

# Oppure con pip tradizionale

pip install mirage-ai

Installazione TypeScript/Node.js

# Per applicazioni Node.js e CLI

npm install @struktoai/mirage-node

# Per applicazioni browser/edge

npm install @struktoai/mirage-browser

# Primitives runtime-agnostici

npm install @struktoai/mirage-core

CLI globale

# Installazione rapida via script

curl -fsSL https://strukto.ai/mirage/install.sh | sh

# Oppure via npm

npm install -g @struktoai/mirage-cli

Le credenziali per ogni servizio (AWS, Google, Slack, etc.) vengono configurate tramite variabili d’ambiente o file .env, come da prassi standard. Il file .env.example nel repository offre un template di partenza.

6. Esempi pratici con Python

Vediamo un esempio realistico: un agente che copia un report da S3, conta gli alert nel log e salva un documento su Google Docs.

from mirage import Workspace

from mirage.resource.ram import RAMResource

from mirage.resource.s3 import S3Config, S3Resource

from mirage.resource.slack import SlackConfig, SlackResource

from mirage.resource.gdocs import GDocsConfig, GDocsResource

# Crea il workspace con i mount point necessari

ws = Workspace({

    '/data':  RAMResource(),               # storage in-memory

    '/s3':    S3Resource(S3Config(bucket='my-bucket')),

    '/slack': SlackResource(SlackConfig()),

    '/docs':  GDocsResource(GDocsConfig()),

})

# Copia un report da S3 alla RAM locale

await ws.execute('cp /s3/report.csv /data/report.csv')

# Conta le righe con la parola 'alert' nel log

count = await ws.execute('grep alert /s3/data/log.jsonl | wc -l')

# Salva uno snapshot dell'intero workspace

ws.snapshot('backup-demo.tar')

Un aspetto molto utile è la possibilità di registrare comandi personalizzati e di fare override di comandi esistenti per specifici tipi di file:

# Registra un comando personalizzato disponibile su tutti i mount

ws.command('summarize', my_summarize_fn)

# Override: 'cat' su file Parquet restituisce JSON invece di bytes

ws.command('cat', {'resource': 's3', 'filetype': 'parquet'}, my_parquet_reader)

# Ora si può usare così:

await ws.execute('summarize /s3/reports/Q1.md')

await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')

7. Esempi pratici con TypeScript

La stessa logica funziona in TypeScript, con pieno supporto per Node.js e ambienti browser:

import {

  Workspace,

  RAMResource,

  S3Resource,

  SlackResource,

  GDocsResource,

} from '@struktoai/mirage-browser';

// Configura il workspace con i servizi necessari

const ws = new Workspace({

  '/data':  new RAMResource(),

  '/s3':    new S3Resource({ bucket: 'my-bucket' }),

  '/slack': new SlackResource({}),

  '/docs':  new GDocsResource({}),

});

// Copia il report e analizza il log

await ws.execute('cp /s3/report.csv /data/report.csv');

await ws.execute('grep alert /s3/data/log.jsonl | wc -l');

È possibile anche usare la CLI per operazioni scriptate o pipeline CI/CD:

# Crea un workspace da file YAML di configurazione

mirage workspace create ws.yaml --id demo

# Esegui un comando nel workspace

mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"

# Salva uno snapshot portabile

mirage workspace snapshot demo demo.tar

# Ripristina su un'altra macchina

mirage workspace load demo.tar --id demo-restored

8. Integrazione con i framework AI più diffusi

Mirage si integra nativamente con i principali framework per agenti AI. Vediamo due esempi:

OpenAI Agents SDK (Python)

from agents import Runner

from agents.run import RunConfig

from agents.sandbox import SandboxAgent, SandboxRunConfig

from mirage.agents.openai_agents import MirageSandboxClient

# Collega il workspace all'OpenAI Agents SDK come sandbox

client = MirageSandboxClient(ws)

agent = SandboxAgent(

    name='Mirage Sandbox Agent',

    model='gpt-5.4-nano',

    instructions=ws.file_prompt,  # prompt che descrive i mount

)

result = await Runner.run(

    agent,

    'Summarize /s3/data/report.parquet into /report.txt.',

    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),

)

Vercel AI SDK (TypeScript)

import { generateText } from 'ai';

import { openai } from '@ai-sdk/openai';

import { mirageTools } from '@struktoai/mirage-agents/vercel';

import { buildSystemPrompt } from '@struktoai/mirage-agents/openai';

// Espone il workspace come tool set per il Vercel AI SDK

const { text } = await generateText({

  model: openai('gpt-5.4-nano'),

  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),

  prompt: 'Read /docs/paper.pdf and describe its content.',

  tools: mirageTools(ws),  // tutti i mount diventano strumenti

});

Adattatori equivalenti sono disponibili per LangChain, Pydantic AI, CAMEL, OpenHands e Mastra.

9. Il sistema di caching

Proseguiamo la nostra Guida Mirage per sviluppatori. Ogni Workspace include un sistema di cache a due livelli che riduce drasticamente le chiamate di rete verso i backend remoti:

• Index cache: memorizza listing e metadati delle directory. La prima scansione di una cartella chiama l’API; le successive servono dalla cache fino alla scadenza del TTL (default 10 minuti).
• File cache: memorizza il contenuto dei file. La prima lettura scarica da S3/Drive/etc.; le successive leggono dalla cache locale.

Per default entrambi i layer usano la RAM (zero configurazione, ideale per notebook e app single-process). Per ambienti serverless o multi-replica si può usare Redis:

import { RedisFileCacheStore, RedisIndexCacheStore, Workspace } from 'mirage/node';

const ws = new Workspace(

  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },

  {

    // Cache file con Redis, limite 8 GB

    cache: new RedisFileCacheStore({

      url: 'redis://localhost:6379/0',

      limit: '8GB'

    }),

    // Cache indice con TTL 600 secondi

    index: new RedisIndexCacheStore({

      url: 'redis://localhost:6379/0',

      ttl: 600

    }),

  }

);

10. Best practice, pro e contro

Best practice

• Usa la RAM cache per prototipi, Redis in produzione: la cache RAM è sufficiente in sviluppo, ma in ambienti multi-worker o serverless usa Redis per condividere la cache tra istanze.
• Separa i mount point per concern: crea path logici chiari (/raw, /processed, /output) per rendere il codice dell’agente più leggibile e manutenibile.
• Sfrutta i comandi custom: registra comandi specializzati (es. ‘summarize’, ‘validate’, ‘transform’) per incapsulare logica di business e renderla riutilizzabile su qualsiasi mount.
• Usa snapshot per riproducibilità: salva lo stato del workspace prima di operazioni critiche. Gli snapshot .tar sono portabili e permettono di ripristinare un run in un altro ambiente.
• Imposta TTL sensati: TTL troppo bassi aumentano le chiamate di rete; troppo alti rischiano dati stale. Calibra in base alla frequenza di aggiornamento dei dati sorgente.
• Leggi il file_prompt generato: ws.file_prompt produce un system prompt che descrive i mount all’LLM. Controllalo per assicurarti che rifletta correttamente la struttura del workspace.

Pro

• Astrazione uniforme su decine di backend eterogenei, zero lock-in su un SDK specifico
• Compatibile con qualsiasi LLM già addestrato su bash/Unix, senza training aggiuntivo
• Cache integrata che riduce latenza e costi API dei servizi remoti
• Workspace portabili tramite snapshot, utili per debugging e CI/CD
• Supporto nativo ai principali framework agentici (LangChain, OpenAI Agents, Vercel AI SDK, ecc.)
• Licenza open source Apache 2.0, community attiva su Discord
• SDK disponibili sia in Python che TypeScript, con supporto browser

Contro

• Progetto in early-stage (v0.0.1 a maggio 2026): API potrebbero cambiare in versioni future
• Richiede Python >= 3.12 o Node.js >= 20, versioni non sempre presenti in ambienti legacy
• Il layer di astrazione aggiunge latenza rispetto a chiamate dirette alle API native
• Alcune risorse (FUSE-based mount) richiedono macOS o Linux; Windows non è supportato
• Documentazione ancora in espansione: per casi d’uso avanzati potrebbe essere necessario leggere il codice sorgente
• La gestione della concorrenza e delle race condition su mount condivisi è ancora in evoluzione

11. Conclusioni e formazione continua

Mirage rappresenta un cambio di paradigma nell’infrastruttura per agenti AI. L’idea di usare il filesystem come API universale, sfruttando il vocabolario bash già presente nei modelli LLM, è elegante, pragmatica e facilmente adottabile da qualsiasi team di sviluppo con competenze Unix di base.

Il progetto è ancora giovane, ma la direzione è chiara: semplificare la complessità multi-servizio degli agenti AI moderni, rendendo ogni backend accessibile con gli stessi comandi familiari. Man mano che l’ecosistema si consolida, ci aspettiamo integrazioni ancora più profonde con i principali cloud provider e framework agentici.

Il mercato dell’intelligenza artificiale è in continua e rapida evoluzione: nuovi strumenti come Mirage emergono ogni settimana, cambiando le best practice di sviluppo nel giro di mesi. L’unico modo per rimanere competitivi, come singolo sviluppatore o come team, è investire nella formazione continua. Aggiornarsi su tool come Mirage, sui nuovi pattern per agenti AI generativa, sulle ultime evoluzioni di LangChain, OpenAI Agents SDK e Vercel AI SDK non è un optional: è una necessità strategica per chi vuole essere protagonista, e non spettatore, della trasformazione digitale in corso.

Formazione finanziata con Fondimpresa

Se fai parte di un’azienda con dipendenti, puoi accedere ai fondi Fondimpresa per finanziare percorsi di formazione professionale su AI generativa, sviluppo agenti, Python, TypeScript e molto altro, spesso a costo zero per l’azienda. È un’opportunità concreta per portare il tuo team allo stato dell’arte, senza impattare il budget.

Per informazioni sui corsi disponibili, sui percorsi formativi in AI generativa e sulle modalità di accesso alla formazione finanziata, contattaci:

📧  info@innovaformazione.net

📞  TEL. 347 101 2275 — Dario Carrassi

🌐  innovaformazione.net

Richiedi subito informazioni o un preventivo personalizzato per il tuo team!

Per altri articoli tecnici consigliamo di navigare sul nostro blog QUI.

(fonte) (fonte) (fonte)