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 a voce 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 spesso includono 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 riduce la conversazione e accelera la risoluzione. Quando un cliente può mostrare invece di descrivere, l'agente risolve il problema più velocemente senza chiedergli di cambiare canale. Rohlik, una delle più grandi piattaforme di spesa online in Europa, 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, non raccontare. ElevenAgents tratta i file come input di primo livello per lo 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 di un unico thread di conversazione. 

Questo articolo spiega cosa significa 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 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 sistemi di trasporto.

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: basati 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 nativi a file, non come riepiloghi di testo. La piattaforma archivia il file, gli assegna un file_id e associa quell'identificatore al turno dell'utente. Un modello in grado di elaborare immagini o documenti riceve il file originale nella propria context window anziché una rappresentazione derivata. Il requisito per l'integrazione è semplice: acquisisci il file_id restituito dall'endpoint di caricamento 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 il caricamento sia riuscito. L'archiviazione dei file è limitata alla conversazione. Ciò significa che tutto ciò che deve persistere oltre la sessione, come 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 segnaposto di posizione di WhatsApp e le schede dei contatti vengono tutti normalizzati in testo semplice nella trascrizione prima dell'esecuzione del modello. Un segnaposto 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 né produce un riferimento a file. Questi input risiedono direttamente nella trascrizione.

Perché la distinzione è importante

La suddivisione determina dove concentrare l'impegno per l'integrazione. Il percorso inline non richiede alcun intervento 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. Invece di convertire il contenuto del file in testo prima dell'esecuzione del modello, l'orchestratore passa il file originale 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 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 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; entrambi devono essere impostati prima dei test.

SDK e WebSocket

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

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 file per la richiesta e la risposta complete:

Quindi invia tramite la connessione un messaggio 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 caricamento 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 il caricamento, a quel punto dispone già del file. Se ti serve solo per la conversazione corrente, è sufficiente caricarlo e fare riferimento al suo identificatore. Se deve persistere oltre la sessione, l'approccio più semplice è archiviarlo dalla tua applicazione al momento del caricamento. Può anche essere recuperato in seguito tramite il webhook post-chiamata, descritto nella sezione sul contesto tra sessioni.

WhatsApp

Su WhatsApp, la tua applicazione non ha alcun ruolo nel caricamento. Quando un cliente invia un'immagine, un documento o uno sticker, il file viene prima inviato all'infrastruttura di Meta. Meta avvisa 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 allega alla conversazione nello stesso modo di un caricamento 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 il caricamento, non dispone mai direttamente del file. Non esiste un metodo per acquisirlo al momento del caricamento, come avviene su web e mobile. Il file raggiunge il tuo sistema tramite il file_url nel webhook post-chiamata, che rimanda alla copia archiviata da ElevenLabs. L'URL del file multimediale di Meta viene usato solo per l'importazione e non viene mai esposto esternamente. I meccanismi di recupero, incluse le limitazioni sui tempi di 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 allega il file_id lato piattaforma. Ciò significa che non esiste un passaggio di caricamento 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 sessioni

ElevenAgents elabora ogni conversazione in modo indipendente. Nulla di ciò che un cliente invia, né di ciò che l'agente risolve durante una conversazione, passa automaticamente a quella successiva. L'agente trasmette al tuo sistema tutto ciò che riguarda una conversazione completata tramite il webhook post-chiamata, ma la memoria che attraversa le conversazioni risiede al di fuori del perimetro di ElevenLabs. La continuità spetta a te.

Vale la pena progettare deliberatamente intorno a questo confine architetturale. Le conversazioni in cui l'input multimodale conta di più, ad esempio quando un cliente fotografa un articolo danneggiato, carica un documento di una polizza o condivide una posizione, spesso non si risolvono in una sola sessione. Un cliente che invia la foto di un componente 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 ha 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 che sono passati attraverso la sessione. Il tuo backend archivia ciò che è rilevante associandolo a un identificatore cliente duraturo, 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 ciò che già sa. Nello specifico degli input basati su file, l'URL del file nel payload del webhook rimanda alla copia archiviata da ElevenLabs ed è l'unico percorso 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 che tale finestra si chiuda. La rapidità con cui devi agire dipende dalla policy di conservazione, descritta nella documentazione di riferimento. Il webhook porta lo stato all'esterno. Le variabili dinamiche lo riportano all'interno. Tutto ciò che sta in 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, inoltrano il caso 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 fondo è coerente. Per la telefonia, ElevenLabs chiama il tuo server prima della connessione della chiamata, dandoti l'opportunità di cercare il chiamante tramite il numero e restituire variabili dinamiche come nome, ID ordine o livello dell'account prima che l'agente parli. Su WhatsApp, un webhook pre-messaggio viene attivato per ogni messaggio in entrata e ti permette di arricchirlo con il contesto relativo all'identità e all'attività dai tuoi sistemi prima che l'agente lo elabori. Altrimenti, gli stessi campi vengono passati in conversation_initiation_client_data all'apertura della sessione. ElevenAgents non unisce le sessioni tra canali 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 di variabili dinamiche funzionano allo stesso modo su tutti i canali, un unico livello di persistenza li gestisce tutti. Crealo una volta e coprirà ogni canale su cui viene eseguito l'agente. L'inserimento del contesto gestisce dati in formato testo: nomi, ID ordine, riepiloghi e campi strutturati. I file sono un caso a parte e richiedono un approccio diverso.

Mantenere i file nelle sessioni successive

I file sono limitati a una conversazione e non persistono automaticamente. Ciò che devi portare avanti dipende dal fatto che alla conversazione successiva servano le informazioni contenute in un file o il file stesso. Nella maggior parte dei casi, servono solo le informazioni. L'agente interpreta un file caricato nel turno in cui arriva, ma non registra automaticamente quell'interpretazione in un archivio persistente. L'output strutturato proviene dai dati post-chiamata: trascrizione, riepilogo della trascrizione e gli eventuali campi di 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 questa informazione dai dati post-chiamata, archiviala associandola all'identificatore del cliente e inseriscila come variabile dinamica quando torna. Di solito bastano 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 firmato del file. 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 emette nuovi URL come soluzione di riserva. Considera che file_input potrebbe non essere presente in alcuni casi, come nella 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 lo elabora 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 di testo, così il layout spaziale, la struttura visiva e la formattazione del documento raggiungono il modello intatti. Il contesto tra sessioni segue lo stesso schema su ogni canale: il webhook post-chiamata porta lo stato all'esterno e le variabili dinamiche lo riportano all'interno.

Se stai sviluppando 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.