Guida Flue Framework

Guida Flue Framework

Il nuovo standard per costruire agenti AI autonomi in TypeScript

Indice dei Contenuti – Guida Flue Framework

1. Introduzione: cos’è Flue Framework
2. La filosofia Agent = Model + Harness
3. Architettura e componenti principali
4. Installazione e primo agente: esempio pratico
5. Skills, ruoli e sessioni: il cuore di Flue
6. Deployment: dove e come pubblicare gli agenti
7. Casi d’uso reali
8. Best Practice, Pro e Contro
9. Formazione continua: corsi AI Generativa per il tuo team
10. Conclusioni e contatti

1. Introduzione: cos’è Flue Framework

Nel panorama degli strumenti per lo sviluppo di intelligenza artificiale, il 2026 ha visto l’emergere di un nuovo protagonista: Flue Framework. Presentato da Fred K. Schott (già noto alla community come il creatore di Astro) il 1° Maggio 2026, Flue si posiziona come il primo vero Agent Harness Framework in TypeScript. Non è l’ennesimo SDK per chiamare API di modelli linguistici: è un framework completo per costruire agenti autonomi, programmabili e dispiegabili ovunque. Il suo claim è lapidario quanto preciso: “Agent = Model + Harness”. In questa guida vedremo cosa significa nella pratica, come funziona l’architettura, e come iniziare a costruire il proprio primo agente AI con Flue.

2. La filosofia Agent = Model + Harness

Per capire Flue bisogna prima capire cosa distingue un agente AI da un semplice chatbot o da uno script che chiama un LLM. La risposta è il concetto di harness (letteralmente “imbracatura”) ovvero lo strato software che permette al modello di pianificare, raccogliere contesto, scrivere file, eseguire comandi shell, lanciare sub-agenti e risolvere problemi in modo autonomo.

Questo è esattamente il pattern architetturale che rende potenti strumenti come Claude Code o OpenAI Codex. Flue porta questa architettura nelle mani di qualsiasi sviluppatore TypeScript, in modo headless, programmabile e senza assunzioni su interfacce grafiche o operatori umani. La logica dell’agente vive quasi interamente in file Markdown (skills, roles, AGENTS.md), mentre il framework gestisce sessioni, sandbox, sub-agenti e deployment.

3. Architettura e componenti principali – Guida Flue Framework

Flue è strutturato in quattro livelli sovrapposti:

• Model: il livello base (token, tool, prompt) — qualsiasi LLM supportato via OpenRouter o direttamente.
• Harness: il cuore del framework: gestisce skills, memory e sessions. È qui che risiede l’intelligenza operativa dell’agente.
• Sandbox: ambiente sicuro in cui l’agente esegue comandi shell (bash), legge e scrive il filesystem. Può essere virtuale (zero-config, built-in) o remoto (es. Daytona, Cloudflare Workers).
• Filesystem: interfaccia unificata per operazioni read/write/grep/glob, accessibile dall’agente tramite bash.

Il progetto è organizzato in due package principali: @flue/sdk (SDK core con build system, session management, harness e tools) e @flue/cli (interfaccia a riga di comando per avviare, eseguire e fare build degli agenti).

4. Installazione e primo agente: esempio pratico – Guida Flue Framework

Installare Flue è immediato. Da terminale:

npm install @flue/sdk @flue/cli

Ogni agente è un file TypeScript dentro la cartella agents/. Ecco un esempio minimo — un agente che riceve un messaggio e risponde:

import type { FlueContext } from '@flue/sdk/client';

export const triggers = { webhook: true };

export default async function ({ init, payload }: FlueContext) {

  const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });

  const session = await agent.session();

  return await session.prompt(

    `Rispondi a questa domanda: ${payload.message}`

  );

}

Per avviare il server di sviluppo in modalità watch (ricarica automatica ad ogni modifica):

flue dev --target node

Il server si avvia di default sulla porta 3583 (che su una tastiera telefonica corrisponde a “FLUE”). Per invocare l’agente via HTTP: POST /agents/hello/:id con body JSON { “message”: “Ciao!” }.

5. Skills, ruoli e sessioni: il cuore di Flue

Uno degli aspetti più interessanti di Flue è che la maggior parte della logica dell’agente non vive nel codice TypeScript, ma in file Markdown strutturati. Questo rende il sistema facilmente manutenibile anche da chi non è un esperto di LLM.

Skills

Le skills sono workflow riutilizzabili con input e output tipizzati. Si definiscono in .flue/skills/*.md con frontmatter YAML per gli schemi. Dal codice si invocano così:

const triage = await session.skill('triage', {

  args: { issueNumber: payload.issueNumber },

  result: v.object({

    severity: v.picklist(['low', 'medium', 'high', 'critical']),

    summary: v.string(),

  }),

});

Ruoli (Roles)

I ruoli sono sub-agenti specializzati, definiti in .flue/roles/*.md. Permettono di assegnare all’agente un contesto e una “personalità” specifica per determinati task. Si applicano così:

return await session.prompt(payload.message, { role: 'data-analyst' });

AGENTS.md e sessioni

Il file AGENTS.md nella root del workspace fornisce il contesto globale dell’agente: istruzioni generali, vincoli, stile di risposta. Le sessioni (session) mantengono lo stato tra più prompt, permettendo all’agente di ricordare il lavoro svolto nell’arco di un task complesso, esattamente come Claude Code o Codex operano in modalità interattiva.

6. Deployment: dove e come pubblicare gli agenti

Una volta sviluppato, l’agente si compila in un server HTTP autonomo con un singolo comando:

flue build --target node

Flue supporta nativamente i seguenti ambienti di deployment:

• Node.js (server standalone)
• Cloudflare Workers (edge computing, serverless)
• GitHub Actions (CI/CD, esecuzione automatica su eventi)
• GitLab CI/CD
• Vercel, Netlify, Railway, Render, Fly.io (guide in arrivo)

Per deployment in Cloudflare Workers, flue build produce una entry TypeScript non bundled che wrangler si occupa di ottimizzare. La gestione dei segreti (API key, token) avviene tramite env, con controllo granulare per singolo prompt: il modello non vede mai i token sensibili direttamente.

7. Casi d’uso reali

Flue brilla in tutti gli scenari dove serve un agente autonomo che agisca su sistemi reali. Alcuni esempi pratici già documentati nel repository ufficiale:

• Issue Triage Agent: analizza automaticamente le issue GitHub in CI, ne valuta severità e riproducibilità, e posta un commento strutturato; in 22 righe di TypeScript, senza bisogno di strumenti come Greptile o CodeRabbit.
• Data Analyst Agent: monta il filesystem locale, accede ai file del progetto con bash, usa Python per analizzare dati e risponde a domande in linguaggio naturale.
• Coding Agent: si connette a un container remoto Daytona, clona un repository, installa le dipendenze e lavora in autonomia sul codice.
• Support Agent: gira su Cloudflare Workers, monta un bucket R2 come base di conoscenza e risponde ai clienti cercando le informazioni con grep e glob, senza container.

8. Best Practice, Pro e Contro

Di seguito le raccomandazioni principali per chi inizia a usare Flue:

• Tenere la logica di business nei file Markdown (skills, roles) e il codice TypeScript al minimo: il framework è progettato per questo.
• Usare la sandbox virtuale built-in per sviluppo e test; passare a sandbox remote (Daytona, Cloudflare) solo in produzione.
• Non esporre mai token e API key direttamente all’agente: gestirli sempre tramite env con granularità per prompt.
• Strutturare AGENTS.md in modo chiaro: è il “system prompt” globale e influenza il comportamento di tutti i task.
• Usare flue run per invocazioni one-shot in CI/CD e flue dev per iterazione locale veloce.

Pro di Flue Framework

• Approccio framework-first con convenzioni forti: meno boilerplate, più produttività rispetto a soluzioni DIY come LangGraph.
• Developer experience eccellente: se già conosci Astro o Next.js, il modello mentale di Flue è immediatamente familiare.
• Markdown-first: la logica delle skills e dei ruoli è leggibile e modificabile senza toccare il codice.
• Sandbox zero-config integrata: niente configurazione di ambienti complessi per iniziare.
• Deploy ovunque: Node.js, Cloudflare Workers, GitHub Actions, un singolo comando.
• Controllo totale sullo stack: agente, harness e sandbox sono tutti nelle tue mani.
• Multi-modello: compatibile con Claude (Anthropic), GPT (OpenAI), modelli via OpenRouter.

Contro di Flue Framework

• Progetto molto recente (maggio 2026): ecosistema ancora in fase di maturazione, documentazione in crescita.
• Solo TypeScript nativamente: gli sviluppatori Python devono affidarsi a porting non ufficiali come PyFlue.
• Curva di apprendimento per il paradigma harness: chi viene da SDK tradizionali deve cambiare approccio mentale.
• Comunità ancora piccola: meno risorse di community, Stack Overflow, tutorial rispetto a soluzioni consolidate.
• Alcuni target di deployment (Vercel, Netlify, Railway) non hanno ancora guide ufficiali.

9. Formazione continua: corsi AI Generativa per il tuo team

Strumenti come Flue Framework rappresentano il nuovo standard dello sviluppo AI: agenti autonomi, harness programmabili, deployment su infrastrutture cloud moderne. Per lavorare efficacemente con questi paradigmi, non basta leggere la documentazione: è necessaria una formazione strutturata che accompagni il team nella transizione verso lo sviluppo AI-first.

InnovaFormazione propone percorsi formativi dedicati all’AI Generativa appositamente studiati per sviluppatori software e team tecnici aziendali. I corsi coprono i fondamenti dell’intelligenza artificiale generativa, l’utilizzo dei principali modelli LLM, lo sviluppo con framework agentici come Flue, la prompt engineering avanzata e l’integrazione di agenti AI nei workflow di sviluppo e produzione.

I corsi sono attivati per aziende su richiesta, con preventivo dedicato e calendario da concordare in base alle esigenze organizzative. Scopri il catalogo completo dei corsi AI Generativa sul seguente LINK.

Grazie ai fondi paritetici Fondimpresa, le aziende aderenti possono accedere alla formazione finanziata per i propri dipendenti, riducendo o azzerando i costi di investimento nella crescita professionale del team. InnovaFormazione supporta le aziende anche nella gestione delle pratiche di accesso al finanziamento.

10. Conclusioni e contatti

Flue Framework rappresenta un salto qualitativo nel modo in cui costruiamo agenti AI. Non è una libreria da aggiungere al proprio stack: è un cambio di paradigma che porta l’architettura harness (quella che rende potenti strumenti come Claude Code) nelle mani di ogni sviluppatore TypeScript. La sua filosofia “framework-first”, il Markdown come linguaggio di logica, la sandbox integrata e la portabilità verso qualsiasi infrastruttura lo rendono uno degli strumenti più promettenti del 2026.

Il mercato tecnologico è in continua e accelerata evoluzione: ogni mese emergono nuovi framework, nuovi modelli, nuovi pattern architetturali. In questo contesto, l’unico modo per mantenere il proprio team competitivo e aggiornato è investire nella formazione continua degli sviluppatori. Non si tratta solo di tenersi al passo: si tratta di anticipare il cambiamento, di avere le competenze per valutare criticamente i nuovi strumenti e integrarli consapevolmente nei propri processi.

Se vuoi approfondire l’AI Generativa con il tuo team o ricevere informazioni sui corsi disponibili e su come accedere alla formazione finanziata tramite Fondimpresa, contattaci senza impegno:

Richiedi informazioni e preventivo

Email: info@innovaformazione.net

Telefono: TEL. 3471012275 — Dario Carrassi

Corsi AI Generativa

(fonte) (fonte) (fonte)