Gestione di immagini e documenti in ElevenAgents

Un responsabile di cantiere nota una carenza di materiali. La fotografa, invia l'immagine all'agente addetto agli acquisti su WhatsApp e conferma vocalmente l'indirizzo di consegna. L'agente elabora la foto, identifica ciò che manca ed effettua un ordine urgente, tutto in un'unica conversazione. I workflow aziendali includono spesso un contesto che le sole parole non possono trasmettere. Le informazioni necessarie per risolvere una richiesta possono essere fornite come foto di un articolo danneggiato o PDF di una polizza. Passarle direttamente all'agente riduce la conversazione e accelera la risoluzione. Quando un cliente può mostrare anziché descrivere, l'agente risolve i problemi più rapidamente senza chiedergli di cambiare canale. Rohlik, una delle maggiori piattaforme europee di spesa online, utilizza il suo agente su telefono, web, app e WhatsApp in sei lingue e risolve automaticamente il 90% delle richieste dei clienti. L'input multimodale estende lo stesso tasso di risoluzione anche ai momenti in cui un cliente deve mostrare, non raccontare. ElevenAgents tratta i file come input di prima classe nello stesso agente che già gestisce voce, WhatsApp, web e mobile. I file raggiungono il modello sottostante come messaggi nativi, quindi un unico agente gestisce ogni tipo di input all'interno dello stesso thread di conversazione. 

Questo articolo spiega cosa significa la multimodalità sulla piattaforma, come i file passano dal dispositivo del cliente al contesto del modello, cosa supporta ciascun canale e come mantenere il contesto tra sessioni quando un cliente torna.

Canali e input 

ElevenAgents è progettato attorno ai canali che le aziende usano già per raggiungere i clienti: applicazioni web e mobile, la piattaforma di assistenza, telefono, SMS, email, WhatsApp e altri. La configurazione dell'agente (prompt, modello, strumenti, knowledge base e voce) viene definita una sola volta e condivisa tra tutti i canali. Due elementi variano in base al canale: il livello di trasporto e i tipi di input supportati. Le applicazioni web e mobile si connettono tramite il widget incorporabile, uno degli SDK o l'Agents WebSocket. Le conversazioni telefoniche si connettono tramite Twilio nativo, SIP trunking o integrazioni native basate su WebSocket. Gli SMS si connettono tramite l'integrazione Twilio nativa. WhatsApp si connette importando un account WhatsApp Business e abilitando l'integrazione sull'agente. Un singolo agente può essere distribuito contemporaneamente su tutti questi trasporti.

Gli input di file (immagini e PDF) sono attualmente supportati su web, mobile e WhatsApp. La gestione degli input è basata sul tipo, non sul canale: una foto e un messaggio vocale ricevuti nella stessa sessione WhatsApp vengono elaborati tramite pipeline completamente diverse prima di raggiungere il modello. Indipendentemente dal canale o dal tipo di input, tutti gli input convergono sullo stesso livello di pre-elaborazione prima di essere passati al modello come contesto nativo, dove seguono uno di due percorsi.

Rappresentazione degli input: basata su file o inline

Indipendentemente dal tipo di input o dal canale, la piattaforma normalizza ogni input in una delle due rappresentazioni interne prima di passarlo al modello. Questa classificazione determina come l'input viene codificato nella context window del modello e cosa deve gestire a monte la tua integrazione.

Input basati su file

Le immagini e i PDF vengono passati al modello come riferimenti a file nativi, non come riepiloghi testuali. La piattaforma archivia il file, gli assegna un file_id e associa tale identificatore al turno dell'utente. Un modello in grado di elaborare immagini o documenti riceve il file non elaborato nella propria context window anziché una rappresentazione derivata. Il requisito di integrazione è semplice: acquisisci il file_id restituito dall'endpoint di upload e includilo nel payload del messaggio. Se il messaggio viene inviato senza il file_id, il modello non ha alcun riferimento al file, indipendentemente dal fatto che l'upload sia riuscito. L'archiviazione dei file è limitata alla conversazione. Ciò significa che tutto ciò che deve persistere oltre la sessione (il file stesso, i campi estratti o un output strutturato) deve essere gestito esplicitamente dalla tua integrazione. Il meccanismo varia in base al canale e al caso d'uso.

Inline

La seconda rappresentazione è inline e include tutto il resto. La voce e i messaggi vocali vengono trascritti. Il testo digitato, il parlato trascritto, i pin di posizione di WhatsApp e le schede contatto vengono tutti normalizzati in testo semplice nella trascrizione prima dell'esecuzione del modello. Un pin di posizione diventa coordinate e un indirizzo facoltativo; un contatto diventa un nome e un numero di telefono. Nessuno di questi elementi viene archiviato come file o genera un riferimento a un file. Questi input risiedono direttamente nella trascrizione.

Perché la distinzione è importante

La suddivisione determina dove concentrare gli sforzi di integrazione. Il percorso inline non richiede nulla da parte tua durante la conversazione: la piattaforma normalizza questi input in testo e li inserisce direttamente nella trascrizione. Il percorso basato su file ha una superficie di integrazione distinta. Anziché convertire il contenuto del file in testo prima dell'esecuzione del modello, l'orchestratore passa il file non elaborato direttamente nella context window del modello. Il modello opera sulla struttura del file anziché su una rappresentazione o descrizione testuale derivata, preservando relazioni spaziali, layout visivo e formattazione del documento che altrimenti andrebbero persi. Tenendo presente questa distinzione, il resto dell'articolo tratta l'implementazione: come configurare l'agente, come i file passano attraverso ciascun canale e come mantenere il contesto tra sessioni.

Configurare l'input multimodale 

L'abilitazione dell'input multimodale parte dalla stessa configurazione dell'agente per web, mobile e WhatsApp. Da quel punto in poi, il modo in cui un file viene caricato e recuperato dipende dal canale.

Abilitare l'input di file

Prima che l'input di file funzioni, nella configurazione dell'agente devono essere presenti due impostazioni. Innanzitutto, imposta conversation_config.conversation.file_input.enabled su True, tramite l'API durante la creazione dell'agente oppure in Impostazioni > Impostazioni avanzate > Input di file nella dashboard. In secondo luogo, l'agente deve essere configurato con un modello in grado di elaborare immagini e documenti. Il flag da solo non fa nulla se il modello sottostante non può elaborare blocchi di immagini o documenti; prima dei test devono essere impostati entrambi.

SDK e WebSocket

L'input di file sul web o su mobile richiede un client di chat personalizzato basato sull'SDK o una connessione Agents WebSocket raw. Il flusso è identico in tutti e tre i casi e la sequenza è un requisito imprescindibile: il file deve essere caricato prima dell'invio del messaggio, perché il payload del messaggio fa riferimento all'identificatore restituito dall'upload.

Carica prima il file:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.conversational_ai.conversations.files.create(
    conversation_id="your_conversation_id",
    file=open("example_file.jpg", "rb"),
)

file_id = response.file_id  

Consulta il caricamento di file per la richiesta e la risposta complete:

Invia quindi un messaggio tramite la connessione che fa riferimento al file_id restituito:

{ 
	"type": "multimodal_message",
	"text": { 
		"type": "user_message", 
		"text": "What does this show?" 
	 },
	"file": { 
		"type": "file_input", 
		"file_id": "<file_id>" 
 	}
}

Gli SDK raggruppano i passaggi di upload e riferimento in un'unica chiamata, gestendo internamente l'identificatore del file. Consulta la specifica multimodal_message per il formato completo del messaggio. Poiché la tua applicazione esegue l'upload, a questo punto dispone già del file. Se ti serve soltanto per la conversazione corrente, è sufficiente caricarlo e fare riferimento al suo identificatore. Se devi conservarlo oltre la sessione, l'approccio più pulito è archiviarlo dalla tua applicazione al momento dell'upload. Può anche essere recuperato in seguito tramite il webhook post-call, descritto nella sezione sul contesto tra sessioni.

WhatsApp

Su WhatsApp, la tua applicazione non partecipa all'upload. Quando un cliente invia un'immagine, un documento o uno sticker, il file viene prima inviato all'infrastruttura di Meta. Meta notifica ElevenLabs tramite il webhook dell'API WhatsApp Business e ElevenLabs usa le credenziali del tuo account WhatsApp Business connesso per scaricare il file da server a server, archivia la propria copia e la allega alla conversazione come nel caso di un upload da web o SDK. L'agente lo riceve come input multimodale e la trascrizione registra un evento file_input.

Poiché la tua applicazione non gestisce mai l'upload, non dispone mai direttamente del file. Non esiste un modo per acquisirlo al momento dell'upload, come avviene su web e mobile. Il file raggiunge il tuo sistema tramite il file_url nel webhook post-call, che punta alla copia archiviata da ElevenLabs. L'URL dei contenuti multimediali di Meta viene usato soltanto per l'acquisizione e non viene mai esposto esternamente. I meccanismi di recupero, inclusi i vincoli temporali per il download, sono descritti nella sezione sul contesto tra sessioni.

Su WhatsApp, il cliente invia il file nella chat. ElevenLabs lo recupera da Meta, lo archivia e associa il file_id lato piattaforma. Ciò significa che non è previsto alcun passaggio di upload lato client. A differenza del web e del mobile, la tua applicazione non chiama POST /v1/convai/conversations/{id}/files né invia multimodal_message tramite WebSocket. ElevenLabs gestisce la consegna, l'archiviazione e il turno dell'agente.

Mantenere il contesto tra sessioni

ElevenAgents elabora ogni conversazione in modo indipendente. Nulla di ciò che un cliente invia e nulla di ciò che l'agente risolve durante una conversazione passa automaticamente a quella successiva. L'agente trasferisce al tuo sistema tutti i dati di una conversazione completata tramite il webhook post-call, ma la memoria che si estende tra conversazioni risiede al di fuori del perimetro di ElevenLabs. La continuità è sotto la tua responsabilità.

Vale la pena progettare intenzionalmente attorno a questo confine architetturale. Le conversazioni in cui l'input multimodale è più importante (un cliente che fotografa un articolo danneggiato, carica un documento di polizza o condivide una posizione) spesso non si risolvono in una singola sessione. Un cliente che invia la foto di un componente rotto e programma una richiamata si aspetta che l'agente ricordi la foto quando richiamerà. Senza una gestione esplicita del contesto, l'agente riparte da zero ogni volta e il cliente deve ripetersi. Il modello che risolve questo problema ha due parti. Quando una conversazione termina, il webhook post-call fornisce la trascrizione, i risultati dell'analisi, eventuali campi di raccolta dati strutturati che hai definito e gli URL dei file passati attraverso la sessione. Il tuo backend archivia ciò che è rilevante associandolo a un identificatore cliente persistente, come un numero di telefono, un ID utente o una chiave dell'account. Quando il cliente torna, la tua applicazione inserisce il contesto archiviato all'avvio della sessione tramite variabili dinamiche, così l'agente inizia la conversazione con ciò che già sa. Per gli input basati su file, in particolare, l'URL del file nel payload del webhook punta alla copia archiviata da ElevenLabs ed è l'unica modalità di recupero dopo la chiusura della conversazione. La copia della piattaforma è limitata alla sessione, quindi se ti serve il file in una conversazione futura o nei tuoi sistemi, devi scaricarlo dal payload del webhook prima della chiusura di quella finestra. La rapidità con cui devi agire dipende dalla policy di conservazione, descritta nella documentazione di riferimento. Il webhook trasferisce lo stato all'esterno. Le variabili dinamiche lo trasferiscono di nuovo all'interno. Tutto ciò che sta nel mezzo è responsabilità del tuo sistema, ed è lì che si concentra il vero lavoro di integrazione per qualsiasi caso d'uso in cui i clienti tornano, inoltrano una richiesta o riprendono una risoluzione in corso.

L'inserimento del contesto dipende dal canale

Il meccanismo di inserimento varia in base al canale, ma il modello sottostante è coerente. Per la telefonia, ElevenLabs chiama il tuo server prima della connessione della chiamata, dandoti la possibilità di cercare il chiamante in base al numero e restituire variabili dinamiche come nome, ID dell'ordine o fascia dell'account prima che l'agente parli. Su WhatsApp, un webhook pre-message viene attivato per ogni messaggio in arrivo e ti consente di arricchirlo con informazioni su identità e contesto aziendale provenienti dai tuoi sistemi prima che l'agente lo elabori. In alternativa, gli stessi campi vengono passati in conversation_initiation_client_data all'apertura della sessione. ElevenAgents non unisce le sessioni di canali diversi in un unico thread. Una conversazione WhatsApp e una conversazione web sono sessioni separate, anche se coinvolgono lo stesso cliente. Tuttavia, poiché l'output del webhook e l'inserimento delle variabili dinamiche funzionano in modo identico su tutti i canali, un unico livello di persistenza li gestisce tutti. Crealo una volta e coprirà ogni canale su cui opera l'agente. L'inserimento del contesto gestisce dati in forma testuale: nomi, ID degli ordini, riepiloghi, campi strutturati. I file sono un caso separato e richiedono un approccio diverso.

Trasferire i file alla conversazione successiva

I file sono limitati a una singola conversazione e non persistono automaticamente. Ciò che devi trasferire dipende dal fatto che la conversazione successiva richieda le informazioni contenute in un file o il file stesso. Nella maggior parte dei casi, servono soltanto le informazioni. L'agente interpreta un file caricato nel turno in cui arriva, ma non registra automaticamente tale interpretazione in una posizione persistente. L'output strutturato proviene dai dati post-call: la trascrizione, il riepilogo della trascrizione e gli eventuali campi di raccolta dati che definisci. Se un cliente invia la foto di una guarnizione della porta crepata e torna una settimana dopo per seguire la pratica, l'agente non ha bisogno di nuovo della foto. Deve sapere che la pratica riguarda una guarnizione della porta crepata. Estrai questa informazione dai dati post-call, archiviala associandola all'identificatore del cliente e inseriscila come variabile dinamica al suo ritorno. In genere bastano un breve riepilogo o pochi campi strutturati.

Quando ti serve il file originale, per i tuoi archivi, per la conformità normativa o per sistemi downstream, il webhook post-call è il percorso di recupero. Ogni file caricato appare nella trascrizione come un evento file_input con un URL del file firmato. L'URL è valido per quindici minuti, quindi scarica e archivia il file quando arriva il webhook anziché rimandare. Se perdi quella finestra mentre la conversazione esiste ancora, l'API GET conversation emette nuovamente URL aggiornati come fallback. Considera che file_input potrebbe non essere presente in alcuni casi, come nella modalità a conservazione zero, anziché presumere che ogni turno basato su file includa un URL.

Questo copre l'intero ciclo di vita: un file entra nella sessione, il modello lo elabora nativamente, l'output strutturato esce tramite il webhook e il tuo livello di persistenza decide cosa saprà l'agente la volta successiva.

Conclusione

La stessa configurazione dell'agente accetta immagini e PDF su web, mobile e WhatsApp senza richiedere uno sviluppo separato per ogni canale. I file vengono normalizzati, associati al turno e passati al modello come blocchi nativi anziché come riepiloghi testuali, così layout spaziale, struttura visiva e formattazione del documento raggiungono il modello intatti. Il contesto tra sessioni segue lo stesso modello su ogni canale: il webhook post-call trasferisce lo stato all'esterno, le variabili dinamiche lo trasferiscono di nuovo all'interno.

Se stai sviluppando con ElevenLabs Agents e vuoi che il tuo agente utilizzi immagini e documenti insieme a voce e testo, abilita l'input multimodale e facci sapere cosa ne pensi.