Variabili dinamiche

Le variabili dinamiche ti consentono di inserire valori runtime nei messaggi, nei prompt di sistema e negli strumenti del tuo agente. In questo modo puoi personalizzare ogni conversazione con dati specifici dell’utente senza creare più agenti.

Panoramica

Puoi integrare le variabili dinamiche in diversi aspetti del tuo agente:

• Nei prompt di sistema per personalizzare comportamento e contesto
• Nei primi messaggi per personalizzare i saluti
• Nei parametri e header degli strumenti per passare dati specifici dell’utente

Ecco alcuni esempi in cui le variabili dinamiche sono utili:

• Personalizzare i saluti con i nomi degli utenti
• Includere i dettagli dell’account nelle risposte
• Passare dati alle chiamate degli strumenti
• Personalizzare il comportamento in base al livello di abbonamento
• Accedere alle informazioni di sistema come l’ID della conversazione o la durata della chiamata

Le variabili dinamiche supportano tre tipi di valori:

Variabili dinamiche di sistema

Il tuo agente ha accesso a variabili integrate system__* in ogni conversazione, senza configurazione runtime. Queste variabili hanno il prefisso dello spazio dei nomi riservato system__ e si aggiornano automaticamente durante la conversazione. Le variabili dinamiche personalizzate non possono usare il prefisso system__ né sovrascrivere le variabili di sistema.

Le variabili contrassegnate con † cambiano tra un turno e l’altro. Inserirle nel testo del prompt può impedire la cache del prompt; consulta le best practice per le alternative.

Identità dell’agente e della conversazione

Ora e fuso orario

Telefonia e messaggistica

Queste variabili vengono popolate, quando applicabile, per i canali di telefonia e messaggistica:

Stato della conversazione per turno

Formato della cronologia della conversazione

La variabile system__conversation_history contiene un oggetto JSON con la seguente struttura:

{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}

Ogni voce include un role ("user", "agent" o "tool") e uno dei seguenti elementi:

• message: Il contenuto testuale del turno
• tool_requests: Un array di chiamate degli strumenti effettuate dall’agente, con valori dei parametri risolti
• tool_results: Un array di risposte degli strumenti

Se il risultato di uno strumento o un parametro contiene una cronologia della conversazione annidata, viene oscurata con un segnaposto (ad esempio [conversation_history (5 turns)]) per evitare un’espansione ricorsiva illimitata.

Questa variabile è utile per passare il contesto della conversazione agli strumenti (come webhook o LLM personalizzati) o per includere la cronologia della conversazione nei prompt dei sottoagenti durante i passaggi di consegne.

Variabili dinamiche segrete

Le variabili dinamiche segrete vengono popolate nello stesso modo delle normali variabili dinamiche, ma indicano a ElevenAgents che devono essere usate solo negli header delle variabili dinamiche e non devono mai essere inviate a un provider LLM come parte del prompt di sistema o del primo messaggio di un agente.

Usa variabili dinamiche segrete per token di autenticazione o ID privati che non devono essere inviati a un LLM. Per creare una variabile dinamica segreta, anteponi secret__ alla variabile dinamica.

Aggiornare le variabili dinamiche dagli strumenti

Le chiamate degli strumenti possono creare o aggiornare variabili dinamiche se restituiscono un oggetto JSON valido. Per specificare cosa estrarre, imposta i path dell’oggetto usando la notazione con punti. Se il campo o il path non esiste, non viene aggiornato nulla.

Esempio di oggetto di risposta e notazione con punti:

• Lo stato corrisponde al path: response.status
• L’email del primo utente nell’array users corrisponde al path: response.users.0.email

{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}

Per aggiornare una variabile dinamica con l’email del primo utente, imposta l’assegnazione come segue.

Le assegnazioni vengono configurate in ogni strumento webhook; consulta le assegnazioni degli strumenti nel Riferimento API.

Guida

Prerequisiti:

• Un account ElevenLabs
• Un agente ElevenAgents configurato (segui la guida rapida per crearne uno)

import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
dynamic_vars = {
    "user_name": "Angelo",
}
config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)
conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)
conversation.start_session()
signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

Integrazione della pagina pubblica talk-to

La pagina pubblica talk-to supporta le variabili dinamiche tramite parametri URL, consentendoti di personalizzare le conversazioni quando condividi i link degli agenti. È particolarmente utile per incorporare agenti personalizzati in siti web, email o campagne di marketing.

Metodi dei parametri URL

Esistono due metodi per passare le variabili dinamiche alla pagina pubblica talk-to:

Metodo 1: JSON codificato in Base64

Passa le variabili come oggetto JSON codificato in Base64 usando il parametro vars:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

Il parametro vars contiene JSON codificato in Base64:

{ "user_name": "John", "account_type": "premium" }

Metodo 2: Parametri query singoli

Passa le variabili usando parametri query con prefisso var_:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium

Precedenza dei parametri

Quando entrambi i metodi vengono usati contemporaneamente, i singoli parametri var_ hanno la precedenza sulle variabili codificate in Base64 per evitare conflitti:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John

In questo esempio, user_name sarà "John" (da var_user_name) anziché "Jane" (da vars codificato in Base64).

Esempi di implementazione

// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}
// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });
  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });
  return `${baseURL}?${params.toString()}`;
}
// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};
const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);

Best practice

Risoluzione dei problemi