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, il tutto in un'unica conversazione. I workflow aziendali spesso includono 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. Inviarle direttamente all'agente rende la conversazione più breve e accelera la risoluzione. Quando un cliente può mostrare anziché descrivere, l'agente risolve il problema più velocemente senza chiedergli di cambiare canale. Rohlik, una delle più grandi piattaforme europee di spesa online, utilizza il proprio 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 ai momenti in cui un cliente deve mostrare, anziché raccontare. ElevenAgents considera i file come input di prima classe per lo stesso agente che gestisce già 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 multimodalità sulla piattaforma, come i file passano dal dispositivo di un cliente al contesto del modello, cosa supporta ciascun canale e come mantenere il contesto tra le sessioni quando un cliente torna.

Canali e input 

ElevenAgents è progettato intorno ai canali che le aziende usano già per raggiungere i clienti: applicazioni web e mobile, piattaforme di assistenza, telefono, SMS, email, WhatsApp e altri. La configurazione dell'agente (prompt, modello, strumenti, knowledge base e voce) viene definita una volta e condivisa su 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 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 simultaneamente su tutti questi trasporti.

Gli input di file (immagini e PDF) sono attualmente supportati su web, mobile e WhatsApp. La gestione degli input è guidata dal tipo, non dal 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 dell'input: basato 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 finestra di contesto 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 nativi ai file, non come riepiloghi testuali. La piattaforma archivia il file, gli assegna un file_id e associa quell'identificatore al turno dell'utente. Un modello con capacità di elaborazione visiva o di documenti riceve il file non elaborato nella propria finestra di contesto anziché una rappresentazione derivata. Il requisito per l'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, anche se l'upload è 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 per farlo 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 dei contatti 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 divisione determina dove concentrare il lavoro di integrazione. Il percorso inline non richiede alcuna azione 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 finestra di contesto del modello. Il modello lavora 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 le sessioni.

Configurare l'input multimodale 

L'abilitazione dell'input multimodale inizia dalla stessa configurazione dell'agente su web, mobile e WhatsApp. Da lì, il modo in cui un file viene caricato e recuperato in seguito 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 al momento della creazione dell'agente oppure in Impostazioni > Impostazioni avanzate > Input 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 serve a nulla se il modello sottostante non può elaborare blocchi di immagini o documenti; entrambi devono essere impostati prima del test.

SDK e WebSocket

L'input di file su web o mobile richiede un client di chat personalizzato basato sull'SDK o una connessione WebSocket Agents 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 l'upload 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 riuniscono 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 a eseguire l'upload, a quel punto hai già il file. Se ti serve solo per la conversazione corrente, è sufficiente caricarlo e fare riferimento al suo identificatore. Se devi conservarlo oltre la sessione, l'approccio più semplice è archiviarlo dalla tua applicazione al momento dell'upload. Puoi anche recuperarlo in seguito tramite il webhook post-chiamata, trattato nella sezione sul contesto tra le sessioni.

WhatsApp

Su WhatsApp, la tua applicazione non interviene nell'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, quindi ElevenLabs usa le credenziali del tuo account WhatsApp Business connesso per scaricare il file da server a server, ne archivia una copia e lo associa alla conversazione come per 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-chiamata, che punta alla copia archiviata da ElevenLabs. L'URL del media di Meta viene utilizzato solo per l'importazione e non viene mai esposto esternamente. Le modalità di recupero, inclusi i vincoli temporali per il download, sono trattate nella sezione sul contesto tra le sessioni.

Su WhatsApp, il cliente invia il file in 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 di web e 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 le sessioni

ElevenAgents elabora ogni conversazione in modo indipendente. Nulla di ciò che un cliente invia, né 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-chiamata, ma la memoria che copre più conversazioni risiede al di fuori del perimetro di ElevenLabs. La continuità spetta a te.

Vale la pena progettare tenendo deliberatamente conto di questo confine architetturale. Le conversazioni in cui l'input multimodale è più importante (un cliente che fotografa un articolo danneggiato, carica un documento relativo a una polizza o condivide una posizione) spesso non vengono risolte in una sola sessione. Un cliente che invia la foto di un pezzo rotto e fissa una richiamata si aspetta che l'agente ricordi la foto quando richiama. Senza una gestione esplicita del contesto, l'agente riparte da zero ogni volta e il cliente deve ripetersi. Il modello che risolve questo problema si compone di due parti. Al termine di una conversazione, il webhook post-chiamata invia la trascrizione, i risultati dell'analisi, gli eventuali campi di raccolta dati strutturati che hai definito e gli URL dei file passati nella sessione. Il tuo backend archivia ciò che è rilevante associandolo a un identificatore cliente permanente, come un numero di telefono, un ID utente o una chiave 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 le informazioni che già conosce. In particolare, per gli input basati su file, l'URL del file nel payload del webhook punta alla copia archiviata da ElevenLabs ed è l'unico modo per recuperarlo 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, trattata nella documentazione di riferimento. Il webhook trasferisce lo stato all'esterno. Le variabili dinamiche lo riportano all'interno. Tutto ciò che sta nel mezzo è responsabilità del tuo sistema, ed è qui che si concentra il vero lavoro di integrazione per qualsiasi caso d'uso in cui i clienti tornano, effettuano un'escalation 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 di base è coerente. Per la telefonia, ElevenLabs chiama il tuo server prima che la chiamata sia connessa, dandoti la possibilità di cercare il chiamante tramite numero e restituire variabili dinamiche come nome, ID dell'ordine o fascia dell'account prima che l'agente parli. Su WhatsApp, un webhook pre-messaggio viene attivato per ogni messaggio in entrata e ti consente di arricchirlo con identità e contesto aziendale provenienti dai tuoi sistemi prima che l'agente lo elabori. Negli altri casi, 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 le gestisce tutte. Crealo una volta e coprirà ogni canale su cui viene eseguito l'agente. L'inserimento del contesto gestisce dati in formato testo: nomi, ID degli ordini, riepiloghi e campi strutturati. I file sono un caso a parte e richiedono un approccio diverso.

Mantenere i file nelle conversazioni successive

I file sono limitati a una singola conversazione e non persistono automaticamente. Cosa mantenere dipende dal fatto che la conversazione successiva necessiti delle informazioni contenute in un file o del file stesso. Nella maggior parte dei casi, servono solo le informazioni. L'agente interpreta un file caricato nel turno in cui arriva, ma non salva automaticamente quell'interpretazione in alcun luogo permanente. L'output strutturato proviene dai dati post-chiamata: la trascrizione, il riepilogo della trascrizione e gli eventuali campi dei risultati della 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 queste informazioni dai dati post-chiamata, archiviali in relazione all'identificatore del cliente e inseriscile come variabile dinamica quando torna. In genere sono sufficienti un breve riepilogo o alcuni campi strutturati.

Quando ti serve il file originale, per i tuoi archivi, per la conformità normativa o per sistemi a valle, il webhook post-chiamata è il percorso di recupero. Ogni file caricato appare nella trascrizione come evento file_input con un URL di file firmato. L'URL è valido per quindici minuti, quindi scarica e archivia il file all'arrivo del webhook anziché rimandare. Se perdi questa finestra mentre la conversazione esiste ancora, l'API GET conversation genera nuovamente URL aggiornati come alternativa. Pianifica la possibilità che file_input sia assente in alcuni casi, ad esempio in modalità di 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 vi opera in modo nativo, 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 un'implementazione separata 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 le sessioni segue lo stesso modello su ogni canale: il webhook post-chiamata trasferisce lo stato all'esterno, le variabili dinamiche lo riportano all'interno.

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