Vai alla navigazione
ConfigurazioneStrumenti

Strumenti di sistema

Aggiorna lo stato interno delle conversazioni senza richieste esterne.

Gli strumenti di sistema consentono al tuo assistente di aggiornare lo stato interno di una conversazione. A differenza degli strumenti webhook o degli strumenti client, gli strumenti di sistema non effettuano chiamate API esterne né attivano funzioni lato client: modificano lo stato interno della conversazione senza effettuare chiamate esterne.

Panoramica

Alcune applicazioni richiedono che gli agenti controllino il flusso o lo stato di una conversazione. Gli strumenti di sistema offrono questa possibilità consentendo all’assistente di eseguire azioni relative allo stato della chiamata che non richiedono la comunicazione con server esterni o con il client.

Strumenti di sistema disponibili

Termina chiamata

Consenti al tuo agente di terminare automaticamente una conversazione quando vengono soddisfatte le condizioni appropriate.

Rilevamento della lingua

Consenti al tuo agente di passare automaticamente alla lingua dell’utente durante le conversazioni.

Trasferimento dell'agente

Trasferisci facilmente le conversazioni tra agenti IA in base a condizioni definite.

Trasferisci al numero

Trasferisci le chiamate a numeri di telefono esterni o URI SIP.

Salta turno

Consenti all’agente di saltare i propri turni se l’LLM rileva che non deve ancora parlare.

Riproduci tono della tastiera

Consenti agli agenti di riprodurre toni DTMF per interagire con sistemi telefonici automatizzati e navigare nei menu.

Rilevamento della segreteria telefonica

Consenti agli agenti di rilevare automaticamente i sistemi di segreteria telefonica e, facoltativamente, lasciare messaggi.

Aggiorna stato

Consenti al tuo agente di aggiornare le variabili dinamiche durante la conversazione usando espressioni.

Implementazione

Quando crei un agente tramite API, puoi aggiungere strumenti di sistema alla configurazione dell’agente. Ecco come implementare gli strumenti di fine chiamata e rilevamento della lingua:

Integrazione LLM personalizzata

Quando usi un LLM personalizzato con gli agenti ElevenLabs, gli strumenti di sistema sono esposti come definizioni di funzioni che il tuo LLM può chiamare. Ogni strumento di sistema ha parametri e condizioni di attivazione specifici:

Strumenti di sistema disponibili

Scopo: termina automaticamente le conversazioni quando vengono soddisfatte le condizioni appropriate.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • L’attività principale è stata completata e l’utente è soddisfatto
  • La conversazione è giunta a una conclusione naturale con accordo reciproco
  • L’utente indica esplicitamente di voler terminare la conversazione

Parametri:

  • reason (stringa, obbligatorio): il motivo della conclusione della chiamata
  • message (stringa, facoltativo): un messaggio di saluto da inviare all’utente prima di terminare la chiamata

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "end_call",
    "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
  }
}

Implementazione: configuralo come strumento di sistema nelle impostazioni dell’agente. L’LLM riceverà istruzioni dettagliate su quando chiamare questa funzione.

Scopri di più: Strumento Termina chiamata

Scopo: passa automaticamente alla lingua rilevata dell’utente durante le conversazioni.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • L’utente parla una lingua diversa da quella della conversazione corrente
  • L’utente richiede esplicitamente di cambiare lingua
  • Per la conversazione è necessario il supporto multilingue

Parametri:

  • reason (stringa, obbligatorio): il motivo del cambio di lingua
  • language (stringa, obbligatorio): il codice della lingua da usare (deve essere nell’elenco delle lingue supportate)

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "language_detection",
    "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
  }
}

Implementazione: configura le lingue supportate nelle impostazioni dell’agente e aggiungi lo strumento di sistema per il rilevamento della lingua. L’agente adatterà automaticamente la voce e le risposte alle lingue rilevate.

Scopri di più: Strumento di rilevamento della lingua

Scopo: trasferire le conversazioni tra agenti IA specializzati in base alle esigenze dell’utente.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • La richiesta dell’utente richiede conoscenze specialistiche o capacità di un agente diverso
  • L’agente attuale non è in grado di gestire adeguatamente la query
  • Il flusso della conversazione indica la necessità di un tipo di agente diverso

Parametri:

  • reason (stringa, facoltativo): il motivo del trasferimento dell’agente
  • agent_number (intero, obbligatorio): numero con indice a partire da zero dell’agente a cui trasferire la conversazione (in base alle regole di trasferimento configurate)

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "transfer_to_agent",
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
  }
}

Implementazione: definisci regole di trasferimento che associano le condizioni a ID di agenti specifici. Configura gli agenti a cui l’agente attuale può trasferire la conversazione. Nella configurazione del trasferimento, gli agenti sono indicati da numeri con indice a partire da zero.

Scopri di più: Strumento di trasferimento dell’agente

Scopo: trasferisci senza interruzioni le conversazioni a operatori umani quando l’assistenza dell’IA non è sufficiente.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • Ci sono problemi complessi che richiedono il giudizio umano
  • L’utente richiede esplicitamente assistenza umana
  • L’IA raggiunge i limiti delle proprie capacità per la richiesta specifica
  • Vengono attivati i protocolli di escalation

Parametri:

  • reason (stringa, facoltativo): il motivo del trasferimento
  • transfer_number (stringa, obbligatorio): il numero di telefono a cui trasferire la chiamata (deve corrispondere ai numeri configurati)
  • client_message (stringa, obbligatorio): messaggio letto al cliente durante l’attesa del trasferimento
  • agent_message (stringa, obbligatorio): messaggio per l’operatore umano che riceve la chiamata

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

Implementazione: configura i numeri di telefono e le condizioni per il trasferimento. Definisci i messaggi sia per il cliente sia per l’operatore umano che riceve la chiamata. Funziona sia con Twilio sia con il trunking SIP.

Scopri di più: Strumento Trasferisci al numero

Scopo: consente all’agente di fare una pausa e attendere l’input dell’utente senza parlare.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • L’utente indica di aver bisogno di un momento (“Dammi un secondo”, “Fammi pensare”)
  • L’utente richiede una pausa nel flusso della conversazione
  • L’agente rileva che l’utente ha bisogno di tempo per elaborare le informazioni

Parametri:

  • reason (stringa, facoltativo): motivo in formato libero che spiega perché è necessaria la pausa

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "skip_turn",
    "arguments": "{\"reason\": \"User requested time to think\"}"
  }
}

Implementazione: non è necessaria alcuna configurazione aggiuntiva. Lo strumento segnala semplicemente all’agente di rimanere in silenzio finché l’utente non parla di nuovo.

Scopri di più: Strumento Salta turno

Parametri:

  • reason (stringa, facoltativo): il motivo della riproduzione dei toni DTMF (ad esempio, “passaggio all’interno”, “inserimento del PIN”)
  • dtmf_tones (stringa, obbligatorio): la sequenza DTMF da riprodurre. Caratteri validi: 0-9, *, #, w (pausa di 0,5 s), W (pausa di 1 s)

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "play_keypad_touch_tone",
    "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
  }
}

Scopri di più: Strumento Riproduci tono della tastiera

Parametri:

  • reason (stringa, obbligatorio): il motivo del rilevamento della segreteria telefonica (ad esempio, “rilevato messaggio di benvenuto automatico”, “nessuna risposta umana”)

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "voicemail_detection",
    "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
  }
}

Scopri di più: Strumento di rilevamento della segreteria telefonica

Scopo: consentire all’agente di aggiornare una o più variabili dinamiche in base alla conversazione, senza chiamare un’API esterna.

Condizioni di attivazione: l’LLM deve chiamare questo strumento quando:

  • La conversazione fornisce informazioni da registrare (ad esempio, un flag di escalation, un’opzione scelta, un valore fornito dall’utente)
  • Un aggiornamento dello stato configurato dipende da un valore che l’LLM deve valutare o estrarre dalla conversazione

Parametri:

I parametri della funzione dipendono dalla configurazione dello strumento. Ogni aggiornamento dello stato configurato che utilizza un valore estratto dall’LLM aggiunge una proprietà allo schema, denominata come la variabile dinamica di quell’aggiornamento e di tipo string, number o boolean. Gli aggiornamenti dello stato creati solo da costanti o altre variabili dinamiche non aggiungono parametri.

Formato della chiamata di funzione:

{
  "type": "function",
  "function": {
    "name": "update_state",
    "arguments": "{\"should_escalate\": true}"
  }
}

Implementazione: l’agente valuta ogni espressione configurata utilizzando i parametri estratti e le variabili dinamiche correnti della conversazione, quindi assegna i risultati alle corrispondenti variabili dinamiche. Non viene effettuata alcuna richiesta esterna.

Scopri di più: Strumento Aggiorna stato

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Each system tool is keyed by name under built_in_tools.
# Leave "description" blank to use the default, tool-specific prompt.
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt={
                "built_in_tools": {
                    "end_call": {
                        "type": "system",
                        "name": "end_call",
                        "description": "",
                        "params": {"system_tool_type": "end_call"},
                    },
                    "language_detection": {
                        "type": "system",
                        "name": "language_detection",
                        "description": "",
                        "params": {"system_tool_type": "language_detection"},
                    },
                }
            },
        ),
    ),
)

Domande frequenti

Sì, gli strumenti di sistema possono essere usati insieme a strumenti webhook e strumenti client nello stesso assistente. Questo consente funzionalità complete che combinano la gestione dello stato interno con interazioni esterne.