> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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.

> **Note**
>
> Questa funzionalità è disponibile solo per Enterprise.

## 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.

> **Info**
>
> Per una singola chiamata ad API esterna senza logica personalizzata, gli [strumenti webhook](/docs/it/eleven-agents/customization/tools/webhook-tools) sono in genere più semplici da configurare. Per
> attivare azioni nel browser o nell'app di un utente, usa invece gli [strumenti client](/docs/it/eleven-agents/customization/tools/client-tools).

## 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:

```javascript
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](/docs/it/eleven-agents/customization/tools/webhook-tools#tool-configuration).

### 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.

| Proprietà              | Descrizione                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.args`             | I parametri della chiamata allo strumento forniti dall'agente.                                                                                                                                                                                                                                                                                                                                           |
| `ctx.config`           | Variabili stringa semplici che hai mappato nel contesto di questo strumento.                                                                                                                                                                                                                                                                                                                             |
| `ctx.secrets`          | Segreti del workspace che hai mappato nel contesto di questo strumento per usarli negli header delle richieste. Il segreto non elaborato non viene mai esposto al tuo codice; l'inserimento avviene in uscita ed esclusivamente negli header.                                                                                                                                                            |
| `ctx.auth_connections` | Riferimenti alle [connessioni di autenticazione](/docs/it/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) configurate che hai mappato nel contesto di questo strumento, da usare nell'header della richiesta `X-With-Auth-Connection`. La credenziale sottostante non viene mai esposta al tuo codice; l'inserimento avviene in uscita ed esclusivamente negli header. |

> **Note**
>
> Solo `ctx.args` è visibile all'agente quando chiama lo strumento. Segreti, valori di configurazione e connessioni di autenticazione non vengono mai rivelati all'agente.

#### 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.

![Definizione di un parametro dello strumento di codice](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp)

#### 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.

![Mappatura di un segreto del workspace nell'oggetto di contesto di uno strumento di codice](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp)

### 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.

> **Warning**
>
> La modifica di **Code Tool Network Access** richiede le autorizzazioni di amministratore del workspace.

### 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:

#### Crea un nuovo strumento di codice

Nella sezione **Agent** della pagina delle impostazioni dell'agente, scegli **Add Tool**. Seleziona **Code** come tipo di strumento, quindi imposta un nome e una descrizione:

| Campo       | Valore                                            |
| ----------- | ------------------------------------------------- |
| Nome        | convert\_temperature                              |
| Descrizione | Converte una temperatura tra Celsius e Fahrenheit |

#### Definisci i parametri

Aggiungi due parametri affinché l'LLM sappia cosa fornire:

| Tipo di dati | Identificatore | Obbligatorio | Descrizione                               |
| ------------ | -------------- | ------------ | ----------------------------------------- |
| number       | value          | true         | Il valore della temperatura da convertire |
| string       | from\_unit     | true         | L'unità da cui convertire: `"C"` o `"F"`  |

#### Scrivi il codice

Apri l'editor di codice e sostituisci il codice sorgente predefinito con:

```javascript
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` };
};
```

Usa **Run** con alcuni valori di esempio (ad es. `value: 100, from_unit: "C"`) per confermare l'output prima di salvare.

#### Orchestrazione

Aggiorna il prompt di sistema dell'agente affinché sappia quando usare lo strumento:

**`Prompt di sistema`**

```plaintext Prompt di sistema
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.
```

#### Test

Avvia una conversazione e prova:

> *Quanto sono 100 gradi Celsius in Fahrenheit?*

L'agente dovrebbe chiamare lo strumento e comunicare il valore convertito.

### Esempi di autenticazione

**Chiamare un'API con un segreto**

```javascript
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**

```javascript
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](/docs/it/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) 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&#xA;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:

```plaintext
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:

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

#### Selezione dell'LLM

> **Warning**
>
> Quando usi gli strumenti, ti consigliamo di scegliere modelli ad alta capacità di ragionamento come GPT 6 o Claude Sonnet 5.5.

È 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.