Come far eseguire a Claude un Graph di osFoundry sul tuo desktop e attendere il risultato

Alla fine, una chat di Claude avvia uno dei tuoi Graph salvati in osFoundry, i programmi di agenti a più passaggi che si ramificano, si distribuiscono in parallelo e ritentano, e l'esecuzione avviene sul tuo desktop, non in Claude e non su un server. Claude riceve subito un ticket, controlla lo stato mentre il desktop lavora e risponde con il risultato del Graph. Se a metà cambi idea, Claude può annullarlo.

Chi fa cosa

	Lato Claude	Lato osFoundry
Accesso	Il tuo account Claude, invariato	La connessione che hai approvato, aggiunta a un progetto
Cosa può vedere	Nome, descrizione, slug, versione e stato di ogni sessione di Graph condivisa	Il programma del Graph, i suoi agenti e i tuoi file restano sul desktop
Quali Graph	Sceglie tra quelli di list_graph_sessions	Solo le sessioni che hai spuntato per quel progetto nell'app desktop
Dove viene eseguito	Da nessuna parte. Claude mette solo in coda e legge	Sul tuo desktop, che preleva l'esecuzione in coda e la esegue in locale
Attesa	Chiama get_graph_run finché lo stato non è definitivo	Riporta un unico risultato di dimensione limitata quando l'esecuzione finisce
Approvazioni	La richiesta di conferma dello strumento di Claude prima di run_graph_session	Gli strumenti impostati per chiedere ogni volta vengono rifiutati durante l'esecuzione; non c'è nessuno a cliccare

Configurazione

Si dà per scontato che il connettore Claude esista già (icona della chiave → Connected → Add assistant, poi https://api.osfoundry.io/api/v1/external-mcp aggiunto in Claude come connettore personalizzato).

1. Avere una sessione di Graph salvata sul desktop

I Graph vivono sul dispositivo. Li scrivi o modifichi con Maestro, con un agente o con osStudio, e ognuno, una volta salvato, riceve un ID di sessione nel formato gs_ più 32 caratteri esadecimali. La schermata Graph dell'app desktop li elenca. Un Graph che hai visto solo nel browser non si può condividere, perché il browser non può eseguirlo.

Esempio: la schermata Graph dell'app desktop con le sessioni Graph salvate

2. Aggiungere la connessione Claude a un progetto

In icona della chiave → Connected, seleziona la connessione Claude. Sotto Projects, scegli un progetto e fai clic su Add to project (aggiungi al progetto). Quel progetto è l'unico posto in cui Claude cercherà i Graph.

Esempio: La sezione Projects di una connessione Claude, con un progetto aggiunto

3. Condividere la sessione di Graph in quel progetto

Più in basso nella stessa scheda Connected, solo nell'app desktop, c'è una sezione chiamata Share desktop Graph sessions (condividi le sessioni di Graph del desktop). Vi compare ogni progetto di tua proprietà, con le sessioni di Graph salvate su questo dispositivo come caselle di spunta:

Share desktop Graph sessions
Choose the saved Graph sessions to share with each project, then enable that project.
Your desktop must be open and signed in.

Launch plan · workspace                      [ Share selected Graphs ]
  [x] Weekly KPI digest
  [ ] Release notes draft

Esempio: Share desktop Graph sessions con una sessione selezionata per un progetto

Prima spunta le sessioni, poi fai clic su Share selected Graphs. Se non hai spuntato nulla, l'app ti blocca con "Choose at least one Graph session for this project first." Condividere un progetto non condivide tutti i Graph del dispositivo. Ogni sessione è una scelta a sé, progetto per progetto.

4. Lasciare aperto il desktop

L'app desktop controlla il progetto in cerca di esecuzioni in coda ogni 20 secondi, e subito quando cambi ciò che è condiviso. Se l'app è chiusa, la richiesta di Claude resta in coda finché non viene riaperta.

5. Chiedere a Claude

In osFoundry, run the Weekly KPI digest Graph in the Launch plan project
for week 2026-W45, and tell me the three biggest changes.

Un'esecuzione reale

Il progetto, il Graph e i numeri qui sotto sono dati di esempio. I nomi degli strumenti e degli argomenti sono quelli che il server reale elenca in tools/list. In Claude Code gli stessi strumenti compaiono come mcp__osfoundry__run_graph_session e così via.

Esempio

Claude → list_granted_resources {}
       ← projects: Launch plan
Claude → list_graph_sessions {"project_id": "<Launch plan>"}
       ← Weekly KPI digest  (gs_3f…, weekly-kpi-digest v3, ready)
         Release notes draft non è elencato: non è mai stato spuntato
Claude → run_graph_session {"graph_session_id": "gs_3f…",
                            "arguments": {"week": "2026-W45"},
                            "idempotency_key": "kpi-2026-w45-a"}
       [Claude ti chiede di consentire questa chiamata allo strumento → Allow]
       ← command_id "8c1e…", status queued
Claude → get_graph_run {"command_id": "8c1e…"}
       ← queued            (il desktop non ha ancora interrogato il server)
Claude → get_graph_run {"command_id": "8c1e…"}
       ← running
Claude → get_graph_run {"command_id": "8c1e…"}
       ← completed
         result: {"execution_id": "GR-0007L", "status": "completed",
                  "result": {...}, "total_tokens": 18412, "reported_cost": 0.07}

Claude: Settimana 45: iscrizioni +18%, conversione da prova a pagamento scesa dal 9.1% al 7.4%,
        e i ticket di supporto sono raddoppiati dopo il rilascio di martedì.

Il primo get_graph_run che risponde queued non è un ritardo da parte di Claude. Niente viene spinto verso il tuo desktop. È il desktop a chiedere lavoro al server, e fino al controllo successivo l'esecuzione semplicemente aspetta. Una volta prelevata, il desktop esegue il Graph con lo stesso comando usato dalla schermata Graph, poi invia indietro il risultato. L'ultima lettura di Claude è quel risultato inviato, non uno stream in diretta.

L'esecuzione viene anche archiviata sotto il progetto Launch plan sul desktop. Il contesto del progetto e la ricerca nella cronologia delle chat durante l'esecuzione usano quel progetto e niente di più ampio.

Per fermarla, Claude chiama cancel_graph_run con lo stesso command_id. Un'esecuzione ancora in coda viene annullata del tutto e non parte mai. Una già in corso riceve una richiesta di annullamento, che il desktop controlla ogni 3 secondi e passa al Graph in esecuzione.

Dov'è il confine

Il Graph non lascia il dispositivo. list_graph_sessions restituisce solo metadati: nome, descrizione, slug, versione e stato. Claude non vede mai lo script, gli agenti che chiama o i file che toccano. Per lo stesso motivo Claude passa gli arguments senza vedere uno schema. Descrivi gli input nella descrizione del Graph se vuoi che Claude li compili bene.

L'esecuzione spetta al desktop perché gli agenti del Graph, i modelli locali, le cartelle e le impostazioni di approvazione stanno tutti lì. Il server conserva solo la coda e il risultato finale. Se il desktop è offline, le esecuzioni in coda lo aspettano. Claude non può mandarle da nessun'altra parte.

Durante l'esecuzione nessuno guarda. Gli strumenti impostati per chiedere ogni volta vengono rifiutati invece di mostrare la richiesta, perché una richiesta a cui nessuno risponde bloccherebbe l'esecuzione per minuti e poi fallirebbe comunque. Gli strumenti che non chiedono funzionano normalmente. Se un Graph dipende da uno strumento che approvi a mano, esegui quel Graph tu stesso dalla schermata Graph.

Ciò che torna indietro ha un limite. Il risultato è l'ID dell'esecuzione, lo stato, il risultato, il conteggio dei token e il costo riportato, e solo se sta in 100,000 caratteri di JSON. Un risultato più grande torna come ID e stato con result_truncated: true, e il record completo resta nella cronologia delle esecuzioni sul desktop. Gli errori vengono tagliati a 2,000 caratteri.

Solo l'agente che ha avviato un'esecuzione può leggerla o annullarla. Un'altra connessione che chiede lo stesso command_id riceve "Graph run not found or access removed", la stessa risposta data per un ID che non esiste.

La condivisione si può revocare in qualsiasi momento prima che l'esecuzione parta. Se togli la spunta dalla sessione o fai clic su Stop sharing (interrompi la condivisione) mentre un'esecuzione è in coda, il desktop ricontrolla prima di eseguire e la annulla con "Graph session is no longer shared with this project".

Prossimo passo

Condividi un Graph piccolo, chiedi a Claude di eseguirlo, poi fai clic su Stop sharing mentre è ancora in coda e guarda Claude segnalare l'annullamento. Come osFoundry suddivide il lavoro tra gli agenti è spiegato nella pagina sull'orchestrazione di Maestro, e l'elenco delle connessioni si trova nella pagina Connected.