Strumenti di codice

Gli strumenti di codice consentono al tuo agente di eseguire JavaScript personalizzato in un ambiente server-side isolato, senza dover creare e fornire il tuo endpoint webhook. Scrivi la logica una sola volta nell’editor di codice integrato e ElevenLabs la esegue ogni volta che l’agente chiama lo strumento.

Panoramica

Uno strumento di codice è una funzione JavaScript che viene eseguita quando l’agente la chiama. Scrivi l’intero corpo della funzione, quindi lo strumento può fare quanto richiesto dall’attività:

• Calcoli personalizzati: applica regole di prezzo, conversioni di unità, logica di punteggio o calcoli sulle date usando solo i parametri della chiamata allo strumento. Non è richiesto alcun accesso alla rete.
• Chiamate ad API esterne: usa fetch da domini consentiti, con segreti del workspace e connessioni di autenticazione inseriti nel contesto della funzione.
• Combinazione di più fonti: chiama due o tre API e unisci, confronta o riconcilia i risultati prima di restituire una singola risposta.
• Diramazioni condizionali: esegui una logica diversa in base ai parametri della chiamata allo strumento, senza dover creare uno strumento separato per ogni diramazione.
• Ristrutturazione dei dati: restituisci esattamente la struttura che vuoi mostrare all’agente, anziché una risposta upstream non elaborata.

Come funziona

Il tuo codice è un modulo JavaScript che esporta una singola funzione asincrona predefinita. La funzione riceve un oggetto ctx e restituisce il risultato dello strumento:

export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;
  return { message: `Hello from ${city}!` };
};

Il valore restituito diventa il risultato dello strumento. Viene inviato all’agente, mostrato nella trascrizione della conversazione e può essere usato per l’assegnazione dinamica di variabili.

L’oggetto ctx

ctx è il punto di accesso a tutto ciò a cui lo strumento può accedere al momento della chiamata. I parametri forniti dall’agente arrivano sempre in ctx.args; segreti, valori di configurazione e connessioni di autenticazione sono facoltativi e compaiono solo se li mappi nella sezione Context object dello strumento.

Configurare i parametri

I parametri sono i valori che l’agente fornisce quando chiama lo strumento e arrivano in ctx.args. Definiscili nella sezione Parameters del modulo di configurazione dello strumento oppure nell’editor di codice, nella scheda Params, nella sottoscheda Define Params. Ogni parametro richiede un tipo di dati, un identificatore e una descrizione che l’agente usa per determinare il valore corretto dalla conversazione. Il tuo codice legge quel valore tramite l’identificatore, come ctx.args.appointment_datetime qui sotto.

Configurare l’oggetto di contesto

Aggiungi segreti, valori di configurazione e connessioni di autenticazione nella sezione Context object dello strumento. Ogni voce richiede un tipo e un nome. Il pannello mostra l’accessor esatto per ogni voce, come ctx.secrets.DEMO_KEY qui sotto.

Accesso alla rete

Il codice eseguito nel sandbox può raggiungere solo i domini che il tuo workspace ha esplicitamente consentito. Aggiungi i domini che il tuo codice deve chiamare nelle Impostazioni di ElevenAgents, in Code Tool Network Access. Le richieste a qualsiasi altro dominio non riusciranno.

Limiti di esecuzione

• Timeout: ogni esecuzione deve completarsi entro il timeout di risposta configurato per lo strumento, da 1 a 30 secondi.
• Nessun pacchetto esterno: gli strumenti di codice attualmente vengono eseguiti senza dipendenze npm.

Testare il codice

Prima di salvare, usa Run nell’editor di codice per eseguire il codice con valori di esempio per i parametri:

• Params — imposta valori di test per ogni parametro definito dallo strumento.
• Output — visualizza il risultato restituito oppure l’errore, se l’esecuzione non è riuscita.
• Logs — visualizza tutto ciò che è stato scritto con console.log, console.warn o console.error, oltre ai tempi di build ed esecuzione.

Guida

In questa guida creeremo uno strumento di codice che converte una temperatura e restituisce una stringa formattata e intuitiva:

export default async (ctx) => {
  const { value, from_unit } = ctx.args;
  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }
  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};

When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.

Esempi di autenticazione

Chiamare un’API con un segreto

export default async (ctx) => {
  const { order_id } = ctx.args;
  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Mappa EXAMPLE_API_KEY a un segreto del workspace nella sezione Context object dello strumento, quindi aggiungi api.example.com a Code Tool Network Access affinché la richiesta possa uscire. Il valore a cui fai riferimento è un segnaposto: il segreto reale viene sostituito nell’header in uscita e non è mai visibile al tuo codice.

Chiamare un’API con una connessione di autenticazione OAuth

export default async (ctx) => {
  const { customer_id } = ctx.args;
  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Mappa EXAMPLE_CRM a una connessione di autenticazione configurata nella sezione Context object dello strumento. Il valore a cui fai riferimento è un segnaposto: la credenziale reale viene sostituita nell’header in uscita e non è mai visibile al tuo codice.

Best practice

Assegna agli strumenti nomi intuitivi e descrizioni dettagliate

Se noti che l’assistente non effettua chiamate agli strumenti corretti, potrebbe essere necessario aggiornare i nomi e le descrizioni degli strumenti affinché capisca più chiaramente quando selezionare ciascuno strumento. Evita di usare abbreviazioni o acronimi per accorciare i nomi degli strumenti e degli argomenti.

Puoi anche includere descrizioni dettagliate che indicano quando chiamare uno strumento. Per gli strumenti complessi, includi descrizioni per ciascun argomento, così da aiutare l’assistente a capire cosa deve chiedere all’utente per raccogliere quell’argomento.

Assegna ai parametri degli strumenti nomi intuitivi e descrizioni dettagliate

Usa nomi chiari e descrittivi per i parametri degli strumenti. Se pertinente, specifica nella descrizione il formato previsto per un parametro, ad esempio YYYY-mm-dd o dd/mm/yy per una data.

Valuta di fornire ulteriori informazioni su come e quando chiamare gli strumenti nel prompt di sistema dell’assistente

Fornire istruzioni chiare nel prompt di sistema può migliorare notevolmente la precisione delle chiamate agli strumenti dell’assistente. Ad esempio, guida l’assistente con istruzioni come le seguenti:

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

Fornisci contesto per scenari complessi. Ad esempio:

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

Selezione dell’LLM

È importante notare che la scelta dell’LLM influisce sul successo delle chiamate di funzione. Alcuni LLM possono avere difficoltà a estrarre dalla conversazione i parametri pertinenti.