Vai alla navigazione

Override

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

Sebbene gli override siano ancora supportati per sostituire completamente i prompt di sistema 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 con l’utente. Puoi passare dati e impostazioni personalizzati all’inizio di ogni conversazione, consentendo all’assistente di personalizzare le proprie risposte e 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:

  • Prompt di sistema
  • Primo messaggio
  • Lingua
  • ID della voce
  • LLM (Large Language Model)
  • Livello di ragionamento dell’LLM
  • Strumenti
  • Knowledge base
  • Modalità solo testo
  • Stabilità
  • Velocità
  • Miglioramento della somiglianza
  • Parole chiave ASR
  • Procedure
  • Nodo iniziale del workflow

L’override Procedure non utilizza 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.

Anche l’override Nodo iniziale del workflow funziona al di fuori di conversation_config_override: il client passa starting_workflow_node_id al livello superiore. Consulta la struttura dei dati client.

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

Le parole chiave ASR usano un rifiuto soft: se l’interruttore Security è disattivato e il client invia comunque asr.keywords, la conversazione continua e le parole chiave vengono ignorate (nessun errore). Abilita l’override Parole chiave ASR nelle impostazioni Security se vuoi applicare il potenziamento delle parole chiave per conversazione. Sono supportate fino a 50 parole chiave per conversazione.

Il livello di ragionamento deve essere supportato dall’LLM dell’agente. In caso contrario, la conversazione non viene avviata e la connessione si chiude con un errore che indica il livello non supportato. Se l’interruttore Security è disattivato, prompt.reasoning_effort viene ignorato e viene utilizzato il livello di ragionamento salvato dell’agente. Il valore è fisso per l’intera conversazione e non può essere modificato dopo l’avvio.

Ecco alcuni esempi in cui gli override possono essere utili:

  • Saluta gli utenti chiamandoli per nome
  • Includi dettagli specifici dell’account nelle risposte
  • Modifica la lingua dell’agente o il tono 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 CRM) tramite parole chiave ASR

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

Guida

Prerequisiti

Questa guida mostra come sovrascrivere i valori predefiniti di Prompt di sistema, Primo messaggio, LLM, Livello di ragionamento, Strumenti, Knowledge base, Impostazioni TTS e Parole chiave ASR dell’agente.

1

Abilita gli override

Per motivi di sicurezza, gli override sono disabilitati per impostazione predefinita. Abilita i campi per cui vuoi consentire la sovrascrittura, ad esempio first_message, prompt.prompt, prompt.reasoning_effort, prompt.tool_ids, prompt.knowledge_base, language o asr.keywords.

Vai alle impostazioni del tuo agente e seleziona la scheda Security. Abilita First message, System prompt, Tools, Knowledge base, ASR keywords e qualsiasi altro override necessario, come LLM o Reasoning effort.

Abilita gli override

2

Sovrascrivi la conversazione

Nel tuo codice, nel punto in cui viene avviata la conversazione, passa gli override come parametro. Gli override degli strumenti e della 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": {
"reasoning_effort": "high",
"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.
"reasoning_effort": "high", # Optional: override the reasoning effort. Requires Security → Reasoning effort.
"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 utilizzi gli override, ometti i campi che non vuoi sovrascrivere anziché impostarli come stringhe vuote o valori null. Includi solo i campi che vuoi personalizzare in modo 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.