Override

Personalizza ogni conversazione con un contesto su misura per ciascun utente.

Sebbene gli override siano ancora supportati per sostituire completamente i system prompt o i primi messaggi, ti consigliamo di usare le variabili dinamiche come metodo preferito per personalizzare le risposte del tuo agente e inserire dati in tempo reale. Le variabili dinamiche offrono una migliore manutenibilità e un approccio più strutturato alla personalizzazione.

Gli override consentono al tuo assistente di adattare il proprio comportamento a ogni interazione dell’utente. Puoi passare dati e impostazioni personalizzati all’inizio di ogni conversazione, permettendo all’assistente di personalizzare le risposte e le conoscenze con un contesto in tempo reale. Gli override sostituiscono completamente i valori predefiniti dell’agente definiti nella dashboard dell’agente.

Panoramica

Gli override ti consentono di modificare in tempo reale il comportamento del tuo agente IA senza creare più agenti. In questo modo puoi personalizzare le risposte con dati specifici dell’utente.

Gli override possono essere abilitati per i seguenti campi nelle impostazioni di sicurezza dell’agente:

System prompt
Primo messaggio
Lingua
ID voce
LLM (Large Language Model)
Strumenti
Knowledge base
Modalità solo testo
Stabilità
Velocità
Aumento della somiglianza
Parole chiave ASR
Procedure

L’override Procedure non usa conversation_config_override. Il client passa invece procedure_ids e start_procedure_ids al livello superiore dei dati client di avvio della conversazione. Consulta Scegliere le procedure per conversazione.

Quando gli override sono abilitati per un campo, fornirne uno resta facoltativo. Se non viene fornito, l’agente userà i valori predefiniti definiti nella dashboard dell’agente. Per la maggior parte dei campi, verrà generato un errore se viene fornito un override quando gli override non sono abilitati per quel campo.

Le parole chiave ASR usano un blocco non rigido: se l’interruttore Sicurezza è disattivato e il client invia comunque asr.keywords, la conversazione prosegue e le parole chiave vengono ignorate (nessun errore). Abilita l’override delle parole chiave ASR nelle impostazioni di sicurezza quando vuoi applicare il potenziamento delle parole chiave per ogni conversazione. Sono supportate fino a 50 parole chiave per conversazione.

Ecco alcuni esempi in cui gli override possono essere utili:

Saluta gli utenti chiamandoli per nome
Includi dettagli specifici dell’account nelle risposte
Adatta la lingua o il tono dell’agente in base alle preferenze dell’utente
Passa dati in tempo reale come saldi del conto o stato dell’ordine
Migliora la trascrizione di nomi o termini per chiamata (ad esempio nomi di aziende nel CRM) tramite parole chiave ASR

Gli override sono particolarmente utili per le applicazioni che richiedono interazioni personalizzate o gestiscono dati utente sensibili che non dovrebbero essere archiviati nella configurazione di base dell’agente.

Guida

Prerequisiti

Un account ElevenLabs
Un agente conversazionale ElevenLabs configurato (creane uno qui)

Questa guida mostra come eseguire l’override di System prompt, Primo messaggio, LLM, Strumenti, Knowledge base, impostazioni TTS e parole chiave ASR predefiniti dell’agente.

Abilita gli override

Per motivi di sicurezza, gli override sono disabilitati per impostazione predefinita. Abilita i campi per i quali vuoi consentire l’override, come first_message, prompt.prompt, prompt.tool_ids, prompt.knowledge_base, language o asr.keywords.

Aggiorna dalla dashboard

Aggiorna tramite CLI

Aggiorna tramite API

Vai alle impostazioni dell’agente e seleziona la scheda Sicurezza. Abilita Primo messaggio, System prompt, Strumenti, Knowledge base, Parole chiave ASR e qualsiasi altro override necessario, ad esempio LLM.

Esegui l'override della conversazione

Nel codice, nel punto in cui viene avviata la conversazione, passa gli override come parametro. Gli override di strumenti e knowledge base sostituiscono gli array predefiniti per quella conversazione. Gli override delle parole chiave ASR sostituiscono l’elenco predefinito di parole chiave dell’agente per quella conversazione (massimo 50 parole chiave).

Payload di avvio della conversazione

{
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "tool_ids": ["tool_7101k5zvyjhmfg983brhmhkd98n6"],
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "5xM3yVvZQKV0EfqQpLrJ",
            "usage_mode": "auto"
          }
        ]
      }
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso", "Globex"]
    }
  }
}

Assicurati di avere installato l’SDK più recente.

from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
...
conversation_override = {
    "agent": {
        "prompt": {
            "prompt": f"The customer's bank account balance is {customer_balance}. They are based in {customer_location}.", # Optional: override the system prompt.
            "llm": "gpt-4o", # Optional: override the LLM model.
            "tool_ids": [
                "tool_7101k5zvyjhmfg983brhmhkd98n6"
            ], # Optional: replace the tools available to the agent.
            "knowledge_base": [
                {
                    "type": "file",
                    "name": "Unladen Swallow Facts",
                    "id": "5xM3yVvZQKV0EfqQpLrJ",
                    "usage_mode": "auto",
                }
            ], # Optional: replace the knowledge base available to the agent.
        },
        "first_message": f"Hi {customer_name}, how can I help you today?", # Optional: override the first_message.
        "language": "en" # Optional: override the language.
    },
    "tts": {
        "voice_id": "custom_voice_id", # Optional: override the voice.
        "stability": 0.7, # Optional: override stability (0.0 to 1.0).
        "speed": 1.1, # Optional: override speed (0.7 to 1.2).
        "similarity_boost": 0.9 # Optional: override similarity boost (0.0 to 1.0).
    },
    "conversation": {
        "text_only": True # Optional: enable text-only mode (no audio).
    },
    "asr": {
        "keywords": ["Acme Corp", "Contoso"] # Optional: boost ASR for per-call terms (max 50). Requires Security → ASR keywords.
    }
}
config = ConversationInitiationData(
    conversation_config_override=conversation_override
)
conversation = Conversation(
    ...
    config=config,
    ...
)
conversation.start_session()

Quando usi gli override, ometti i campi che non vuoi sostituire anziché impostarli su stringhe vuote o valori null. Includi soltanto i campi che vuoi personalizzare nello specifico.

Per trovare la stringa corretta del modello LLM, consulta il Riferimento API degli agenti, che elenca tutti i modelli LLM supportati e i relativi identificatori stringa esatti.