Creare ElevenAgents con Claude Code

Un tempo servivano settimane e diversi fornitori per realizzare agenti vocali. Ora puoi crearne uno da zero in un pomeriggio con Claude Code. In questa guida ti accompagniamo passo dopo passo: dalla persona, alla knowledge base, al workflow, agli strumenti, ai guardrail, ai test, fino a un numero di telefono che puoi chiamare.

Cosa puoi creare in un pomeriggio:

• Agente vocale che ti sveglia con un briefing sugli errori CI della notte
• Linea di supporto multilingue per il tuo side project già oggi pomeriggio
• Agente interattivo per il tuo sito portfolio che parla come te

I limiti che rendevano gli agenti vocali meccanici—latenza, prosodia, turn-taking—sono migliorati moltissimo. Il nostro modello più veloce ha una latenza di circa 75ms e gestisce pause e interruzioni in tempo reale. Eleven v3 è il nostro modello TTS più espressivo: può cambiare registro, ridere e sospirare come una persona.

Configurazione rapida

Per prima cosa, installa la skill ElevenLabs con questo prompt in Claude Code:

Install the ElevenLabs skill globally - npx skills add elevenlabs/skills

Poi esegui la skill setup-api-key per collegare la tua API key di ElevenLabs:

Set up the elevenlabs key using the setup-api-key skill.

Consiglio: limita la chiave a "agents-write" e imposta un tetto di spesa giornaliero. Un loop fuori controllo può consumare rapidamente i crediti.

Crea l’agente

ElevenAgents è pensato per permetterti di creare un agente vocale pronto per la produzione in Claude Code in pochi minuti, usando prompt in linguaggio naturale. Il resto di questa guida è una serie di prompt che ti portano da un workspace vuoto a un numero di telefono che puoi chiamare.

Partiamo dall’agente vero e proprio. Questo primo prompt ne crea uno con una persona, una voce e un LLM per la parte di ragionamento. Niente strumenti, niente knowledge base, niente workflow per ora: solo il percorso più rapido dal nulla al minimo agente funzionante.

Create an ElevenAgent: a warm, knowledgeable product expert. Use a v3 conversational voice and Qwen-3.6 as the LLM. Return the dashboard URL.

Aggiungi una knowledge base

Una knowledge base è l’insieme di documenti, URL e FAQ a cui il tuo agente può fare riferimento quando riceve una domanda. ElevenAgents gestisce per te la pipeline di retrieval (RAG, retrieval-augmented generation). Quando un utente chiede qualcosa, la piattaforma cerca nei contenuti indicizzati, estrae le parti più rilevanti e le passa all’LLM come contesto prima di generare la risposta. Le fonti vengono reindicizzate automaticamente quando cambiano, così l’agente resta sempre aggiornato con la tua documentazione senza che tu debba caricare di nuovo nulla.

Add a knowledge base to my agent. Index 
https://elevenlabs.io/docs/eleven-agents/overview
 and ./README.md if it exists. 

Auto-reindex on.

Aggiungi un workflow

Un singolo agente con un solo prompt gestisce bene compiti specifici. I workflow estendono questa capacità a conversazioni multi-intento. Invece di inserire tutti i comportamenti possibili in un unico prompt di sistema, suddividi l’agente in nodi che gestiscono ciascuno un intento specifico, e instradi tra loro in base alle esigenze di chi chiama. Ogni nodo ha un comportamento mirato, e i collegamenti tra i nodi vengono gestiti in base a condizioni valutate da un LLM.

Add a workflow to my agent: greeting, classify intent, then branch to either answer from KB or escalate to human, then wrap up.

Aggiungi strumenti

ElevenAgents supporta tre categorie di strumenti, ognuna con una funzione diversa. Gli strumenti client eseguono azioni sull’interfaccia utente, così l’agente può navigare, evidenziare o aggiornare ciò che l’utente vede. Gli strumenti webhook chiamano le tue API server, permettendo all’agente di leggere o scrivere dati nei tuoi sistemi. Gli strumenti integrati coprono le azioni comuni della piattaforma che non vuoi sviluppare tu, come terminare la chiamata, rilevare la lingua di chi chiama o trasferire a un operatore umano.

Add three tools to my agent: 
1. A client tool called show_help_article that takes an article_id. 
2. A webhook tool called get_weather hitting 
https://wttr.in/
{location}?format=j1. 
3. Enable the built-in end_call and language_detection tools.

Aggiungi guardrail

I guardrail funzionano in modo indipendente dall’LLM, quindi intercettano i casi limite che il tuo prompt di sistema potrebbe non coprire. In generale, conviene configurarli nelle platform_settings invece di affidarsi solo al prompt di sistema, ma per le regole più critiche è meglio fare entrambe le cose. Includili sia nel prompt di sistema sia come guardrail personalizzato indipendente. Così hai una doppia protezione: se l’LLM si discosta dalle istruzioni, il validatore della risposta lo intercetta prima che arrivi all’utente.

Add guardrails to my agent. Enable focus and prompt injection protection. Add custom rules to block specific pricing claims, speculation about unreleased features, and any write access to billing systems.

Aggiungi test

Prima di mettere il tuo agente davanti agli utenti reali, ti conviene verificare che si comporti come previsto. ElevenAgents supporta tre tipi di test, e di solito ti serviranno tutti. I test di risposta verificano che l’agente dica la cosa giusta con il tono giusto. I test sugli strumenti controllano che richiami lo strumento corretto con i parametri giusti. I test di simulazione verificano che il flusso multi-turno regga anche quando la conversazione esce dallo script.

Add three tests to my agent: one that checks the greeting tone, one that checks it calls show_help_article when asked about password resets, and a simulation that checks if it defers to sales when asked about pricing.

Collegalo a un telefono

Fino a questo punto l’agente funziona solo nella dashboard. Collegarlo a un numero di telefono permette di instradare il traffico vocale tramite un provider di telefonia, abilitando chiamate in entrata e in uscita. Chi chiama può comporre il numero, il tuo agente può chiamare, e l’audio passa tramite il provider. ElevenAgents offre integrazioni native con Twilio, SIP trunk, Vonage, Telnyx, Plivo e Genesys: non serve un media server esterno e non devi gestire manualmente il routing TwiML. Tutto, dal modello vocale all’LLM fino al provider telefonico, è integrato in un’unica piattaforma.

L’integrazione nativa con Twilio è la configurazione più rapida. Importi un numero Twilio nella dashboard di ElevenAgents con il tuo Account SID e Auth Token, e la piattaforma configura automaticamente i webhook vocali e il formato audio. Una cosa utile da sapere: i numeri acquistati tramite Twilio supportano sia chiamate in entrata che in uscita. I numeri verificati come caller ID in Twilio supportano solo le chiamate in uscita.

Connect my Twilio account to ElevenAgents. Reserve a +1 number from Twilio's available pool, assign it my ElevenAgent via the native Twilio integration, and return the number to dial.

Consiglio: se non hai ancora Twilio, il pulsante Talk to Agent nella dashboard funziona direttamente dal browser. Il numero di telefono serve per la produzione.

Ora hai un agente vocale che non sembra un agente vocale.