Motore Strands

Libre WebUI integra un motore di agenti basato sull'open source Strands Agents harness (@strands-agents/harness 0.1.1 su @strands-agents/sdk 1.19.0). Il motore gira all'interno del processo backend di Libre WebUI, quindi non c'è alcun demone separato da installare. L'SDK viene caricato la prima volta che il motore viene usato; un server con Strands disattivato non lo carica mai.

Il motore pilota i modelli che Libre WebUI già serve:

• i modelli Ollama, quando Ollama è abilitato
• i modelli dei plugin provider di chat o di completamento attivi

Ogni chiamata al modello passa per gli stessi servizi Ollama e plugin usati da Chat. Non esiste una configurazione separata dei provider né una chiave API separata. Le credenziali dei provider e l'interruttore di Ollama si applicano senza modifiche.

Puoi usare il motore in tre punti:

• la pagina Strands, per sessioni di agente persistenti
• Chat, tramite le voci Strands nel selettore dei modelli
• Work, come opzione Strands del controllo Motore del compositore

Accesso

Un amministratore sceglie chi può usare il motore in Impostazioni → Gestione utenti → Accesso e criteri → Motore Strands:

Modalità	Etichetta nell'impostazione	Chi può usare Strands
disabled	Disattivo	Nessuno, amministratori compresi (predefinito)
admins	Amministratori	Gli amministratori attivi
all-users	Tutti gli utenti	Ogni account attivo

Una modifica ha effetto dalla richiesta successiva, senza riavvio.

Per fissare la modalità a livello di deployment, imposta LIBRE_STRANDS_ACCESS:

LIBRE_STRANDS_ACCESS=admins   # or disabled, all-users

Una modalità fissata blocca il controllo in Gestione utenti. Qualsiasi valore diverso da disabled, admins o all-users blocca il motore su disattivato, invece di ripiegare sull'impostazione salvata.

Il server applica la modalità a ogni richiesta REST, alla chat via WebSocket e a ogni chiamata al modello di un'esecuzione Work. Se la modalità non può essere letta, l'accesso viene negato. Gli account senza accesso non vedono la pagina Strands, le voci Strands della chat né il motore Strands di Work, e l'API risponde 403.

Pagina Strands

Apri Strands dalla barra laterale (/strands).

• Le sessioni persistono tra un riavvio e l'altro, fino a 200 per account. Il primo messaggio dà il nome a una nuova sessione.
• Scegli un modello per ogni sessione. Modello predefinito usa il tuo modello di chat predefinito.
• Le risposte arrivano in streaming man mano che vengono generate, con il ragionamento del modello e una scheda per ogni chiamata a uno strumento.
• Interrompi annulla il turno in corso. Una sessione esegue un turno alla volta.
• Eliminare una sessione ne rimuove la cronologia e lo spazio di lavoro.

Chat

Scegli Strands nel selettore dei modelli. Compare nel gruppo Agenti, accanto ai modelli Agent CLI:

• Strands (strands) usa il valore predefinito del motore, cioè il tuo modello di chat predefinito.
• Strands · modello (provider) (strands:<route>) fissa un modello e il suo provider per la conversazione.

Strands in Chat dipende solo dall'accesso a Strands. Non richiede l'interruttore dei modelli Agent CLI e compare anche quando quell'interruttore è disattivato. In Chat l'agente ha gli stessi strumenti per i file della pagina Strands, in un unico spazio di lavoro privato per account, e le sue risposte arrivano come testo e ragionamento. Consulta Agenti di programmazione installati per il gruppo Agenti e per usare una voce Strands come modello delle attività per titoli e riepiloghi del ragionamento.

Work

Nel compositore di Work, scegli Libre WebUI o Strands nel controllo Motore e seleziona il modello a parte. Con Strands, un agente Strands pianifica ogni passaggio e Work esegue gli strumenti che richiede nella sandbox di Work, secondo la normale politica di approvazione di Work. Work resta l'autorità per la trascrizione, le approvazioni, l'esecuzione degli strumenti e la cronologia delle esecuzioni; in Work l'agente Strands non esegue alcuno strumento proprio.

Il modello del provider sottostante deve supportare le chiamate agli strumenti. Work lo verifica prima dell'avvio di un'esecuzione e rifiuta un modello che non dichiara il supporto agli strumenti.

Le esecuzioni Work salvate da release precedenti con il prefisso di modello dsh: si aprono come esecuzioni Strands. Consulta Work: motore Strands per capire come la scelta del motore interagisce con i modelli portati da Chat.

Modello di sicurezza

Nella pagina Strands e in Chat, l'agente ha un insieme di strumenti volutamente ridotto:

• read, write ed edit, per i file nel suo spazio di lavoro
• il plugin todos dell'harness, per pianificare lavori in più passaggi

Non ha shell, recupero dal web, memoria né skill, e nessun file AGENTS.md viene inserito nelle sue istruzioni.

Ogni sessione ha una directory di lavoro privata, che l'agente vede come /workspace. Ogni percorso viene risolto dopo aver seguito i link simbolici e deve restare all'interno di quella directory, così un link nello spazio di lavoro non può raggiungere il resto del disco. La sandbox rifiuta di eseguire comandi.

Elemento	Limite
Sessioni per account	200
Lunghezza del prompt	32.000 caratteri
Turni dell'agente per messaggio	24
Lettura o scrittura di file	2 MB per chiamata
Titolo della sessione	120 caratteri

Un turno che raggiunge il limite di turni si ferma e lo segnala. Ogni turno può effettuare più chiamate ai modelli dei tuoi provider, quindi concedi l'accesso con la stessa attenzione che riservi a qualsiasi altro accesso ai modelli che consuma budget dei provider.

Archiviazione

I dati di Strands si trovano in <DATA_DIR>/strands/, non nel database dell'applicazione. Ogni account ha una propria directory, <DATA_DIR>/strands/users/<account-hash>/, che contiene:

• registry.json: l'elenco delle sessioni dell'account
• sessions/: gli snapshot delle sessioni Strands che l'agente usa come contesto
• transcripts/: la trascrizione mostrata nella pagina Strands per ogni sessione
• workspaces/: lo spazio di lavoro privato di ogni sessione
• chat-workspace/: lo spazio di lavoro usato dai turni di Chat

Includi <DATA_DIR>/strands/ nei backup se le sessioni ti interessano.

Utilizzo

Utilizzo provider (/usage) attribuisce le chiamate di Strands all'agente Strands nella sua sezione Agenti. Consulta Utilizzo degli agenti.

API

Ogni route richiede un account autenticato con accesso a Strands, tranne /api/strands/access, che richiede un amministratore.

Metodo	Percorso	Scopo
GET	/api/strands/access	Legge la modalità di accesso e se LIBRE_STRANDS_ACCESS la fissa (admin)
PUT	/api/strands/access	Imposta mode su disabled, admins o all-users (admin; 409 se fissata)
GET	/api/strands/health	Disponibilità del motore e versioni dell'harness e dell'SDK
GET	/api/strands/models	Modelli che il motore può pilotare per questo account
GET	/api/strands/sessions	Elenca le sessioni
POST	/api/strands/sessions	Crea una sessione (title e model facoltativi)
GET	/api/strands/sessions/:sessionId	Legge una sessione, la sua trascrizione e se un turno è in corso
PATCH	/api/strands/sessions/:sessionId	Modifica il titolo o il modello di una sessione
DELETE	/api/strands/sessions/:sessionId	Elimina una sessione con la sua trascrizione e il suo spazio di lavoro
POST	/api/strands/sessions/:sessionId/messages	Invia { "text": "..." } e trasmette il turno in streaming come NDJSON
POST	/api/strands/sessions/:sessionId/cancel	Interrompe il turno in corso

Lo stream dei messaggi scrive un evento JSON per riga: turn-start, text, reasoning, tool-start, tool-result, done (con il motivo dell'arresto e l'uso dei token quando il provider lo riporta) ed error. Chiudere la connessione annulla il turno. Inviare un messaggio mentre un turno è in corso restituisce 409.

Configurazione

Variabile	Predefinito	Scopo
LIBRE_STRANDS_ACCESS	non impostata (impostazione dell'amministratore, admins)	Fissa disabled, admins o all-users; qualsiasi altro valore blocca il motore su disattivato

Risoluzione dei problemi

Consulta Problemi del motore Strands.