> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Strumenti come codice

## Panoramica

Uno [strumento](/docs/it/eleven-agents/customization/tools) viene memorizzato come configurazione con schemi JSON annidati per i relativi parametri. Scrivere questa configurazione manualmente significa dover mantenere i parametri del path allineati con l'URL, gli elenchi `required` allineati con le relative proprietà e assegnare a ogni parametro esattamente una fonte del valore. Il builder di strumenti negli SDK Python e JavaScript ti consente di descrivere lo stesso strumento con chiamate di metodi concatenate. Genera quindi la richiesta già accettata da `tools.create()` e `tools.update()`.

Usalo per:

* Definire strumenti webhook, client e di sistema nel codice e revisionarli come qualsiasi altra modifica al codice.
* Caricare uno strumento, modificare un parametro e inviarlo di nuovo senza alterare il resto della configurazione.
* Archiviare gli strumenti come JSON nel controllo versione e convalidarli in CI.

> **Note**
>
> Il builder viene eseguito interamente nell'SDK. Non chiama nuovi endpoint API e tutto ciò che crea può essere
> aperto e modificato nella dashboard.

## Requisiti

* Python: il pacchetto `elevenlabs`. Il builder viene importato da `elevenlabs.agent_tools`.
* JavaScript: il pacchetto `@elevenlabs/elevenlabs-js`. Il builder viene esportato dalla root del pacchetto.

## Crea uno strumento webhook

`Tool.webhook(name, description)` avvia uno [strumento webhook](/docs/it/eleven-agents/customization/tools/webhook-tools). Il nome e la descrizione sono ciò che l'LLM vede quando decide se chiamare lo strumento. Questo esempio cerca un ordine in base al numero fornito dal chiamante, invia una chiave API dai segreti del workspace e memorizza lo stato dell'ordine in una variabile dinamica:

```python
from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool

elevenlabs = ElevenLabs()

get_order = (
    Tool.webhook("get_order", "Look up an order by the number the caller gives")
    .get("https://api.example.com/orders/{order_id}")
    .path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
    .query_param("include", Schema.string().constant("items"))
    .header("Authorization", Header.secret("sec_orders_api"))
    .assign("order_status", "order.status")
    .options(response_timeout_secs=10)
)

tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
```

```typescript
import { ElevenLabsClient, Header, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const getOrder = Tool.webhook("get_order", "Look up an order by the number the caller gives")
  .get("https://api.example.com/orders/{order_id}")
  .pathParam("order_id", Schema.string().describe("The order number, e.g. A-1042"))
  .queryParam("include", Schema.string().constant("items"))
  .header("Authorization", Header.secret("sec_orders_api"))
  .assign("order_status", "order.status")
  .options({ responseTimeoutSecs: 10 });

const tool = await elevenlabs.conversationalAi.tools.create(getOrder.build());
```

I metodi della richiesta impostano il metodo HTTP e l'URL. I placeholder `{name}` nell'URL vengono compilati dai parametri del path:

| Python                                                           | JavaScript                 | Imposta                                                                                                                                 |
| ---------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | stesso                     | Il metodo e l'URL. `POST`, `PUT` e `PATCH` richiedono un body; `GET` non può averne uno.                                                |
| `path_param(name, schema)`                                       | `pathParam(name, schema)`  | Un parametro del path, per il placeholder `{name}` nell'URL.                                                                            |
| `query_param(name, schema)`                                      | `queryParam(name, schema)` | Un parametro query.                                                                                                                     |
| `body(schema)`                                                   | `body(schema)`             | Il body della richiesta. Deve essere uno schema oggetto.                                                                                |
| `response(schema)`                                               | `response(schema)`         | Lo schema del body della risposta. Deve essere uno schema oggetto.                                                                      |
| `header(name, value)`                                            | `header(name, value)`      | Un header della richiesta. Vedi [Header e autenticazione](#headers-and-authentication).                                                 |
| `auth(connection)`                                               | `auth(connection)`         | La [connessione di autenticazione](/docs/it/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) da usare. |
| `assign(variable, path)`                                         | `assign(variable, path)`   | Memorizza in una variabile dinamica il valore in corrispondenza di `path` nella risposta (notazione con punti).                         |

L'impostazione di un parametro o di un header con un nome già esistente lo sostituisce e ne mantiene la posizione. `remove_path_param()`, `remove_query_param()`, `remove_header()` e `remove_assignment()` (`removePathParam()` e così via in JavaScript) ne rimuovono uno. I nomi dei parametri devono essere univoci tra path, query e body.

Un body è uno schema oggetto creato proprietà per proprietà:

```python
refund = (
    Tool.webhook("issue_refund", "Refund an order the caller asked to return")
    .post("https://api.example.com/refunds")
    .body(
        Schema.object()
        .property("order_id", Schema.string().from_variable("order_id"))
        .property(
            "reason",
            Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
        )
        .property("note", Schema.string().describe("Anything else the caller said").optional())
    )
)
```

```typescript
const refund = Tool.webhook("issue_refund", "Refund an order the caller asked to return")
  .post("https://api.example.com/refunds")
  .body(
    Schema.object()
      .property("order_id", Schema.string().fromVariable("order_id"))
      .property(
        "reason",
        Schema.string()
          .describe("Why the caller wants a refund")
          .choices(["damaged", "late", "other"])
      )
      .property("note", Schema.string().describe("Anything else the caller said").optional())
  );
```

## Schemi dei parametri

`Schema` crea gli schemi dei parametri usati dagli strumenti webhook e client. Ogni metodo restituisce un nuovo schema e lascia invariato quello su cui è stato chiamato, quindi puoi definire uno schema una volta e usarlo in più strumenti.

| Costruttore                                                               | Crea                                                      |
| ------------------------------------------------------------------------- | --------------------------------------------------------- |
| `Schema.string()`, `Schema.integer()`, `Schema.number()`, `Schema.bool()` | Un valore letterale                                       |
| `Schema.object()`                                                         | Un oggetto. Aggiungi proprietà con `property()`.          |
| `Schema.array(items)`                                                     | Un array i cui elementi corrispondono allo schema `items` |

### Origine di un valore

Ogni valore letterale richiede esattamente una fonte del valore, ovunque compaia: in un parametro, in un body, in uno schema di risposta o all'interno di un oggetto o di un array. Anche un oggetto o un array può averne una, che fornisce quindi l'intero valore.

| Python                | JavaScript           | Il valore                                                                                                                                           |
| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `describe(text)`      | `describe(text)`     | Viene fornito dall'LLM, guidato da `text`.                                                                                                          |
| `from_variable(name)` | `fromVariable(name)` | Viene letto da una [variabile dinamica](/docs/it/eleven-agents/customization/personalization/dynamic-variables) quando lo strumento viene eseguito. |
| `constant(value)`     | `constant(value)`    | È sempre `value`.                                                                                                                                   |
| `system_provided()`   | `systemProvided()`   | Viene compilato dal sistema quando lo strumento viene eseguito. Solo valori letterali.                                                              |
| `omit()`              | `omit()`             | Viene escluso dalla richiesta. Solo per una proprietà facoltativa.                                                                                  |

Su un oggetto o un array, `describe()` documenta il contenitore per l'LLM e ogni proprietà o elemento mantiene la propria fonte.

### Altri metodi dello schema

| Python                                            | JavaScript                                    | Funzione                                                                                                     |
| ------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `optional()`                                      | `optional()`                                  | Rende facoltativa una proprietà. Le proprietà sono obbligatorie se non sono contrassegnate come facoltative. |
| `choices(values)`                                 | `choices(values)`                             | Limita una stringa a un set fisso di valori, tra cui l'LLM sceglie.                                          |
| `allowed_from(variable)`                          | `allowedFrom(variable)`                       | Rifiuta un valore dell'LLM che non è nell'elenco contenuto in una variabile dinamica. Richiede `describe()`. |
| `property(name, schema)` / `without(name)`        | `property(name, schema)` / `without(name)`    | Aggiunge, sostituisce o rimuove una proprietà dell'oggetto. Una proprietà sostituita mantiene la posizione.  |
| `require_any_of(names)` / `require_all_of(names)` | `requireAnyOf(names)` / `requireAllOf(names)` | Richiede almeno una o tutte le proprietà facoltative di un gruppo.                                           |

## Header e autenticazione

Il valore di un header proviene da uno di quattro punti. Usa un segreto o una variabile d'ambiente per qualsiasi dato sensibile, in modo che il valore non compaia mai nella configurazione dello strumento:

| Costruttore                                      | Il valore dell'header è                                                                                                            |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Header.value(text)`                             | Testo fisso.                                                                                                                       |
| `Header.secret(id)`                              | Un segreto dall'archivio dei segreti del workspace.                                                                                |
| `Header.variable(name)`                          | Una variabile dinamica, letta quando lo strumento viene eseguito.                                                                  |
| `Header.env_var(label)` / `Header.envVar(label)` | Una [variabile d'ambiente](/docs/it/eleven-agents/integrate/environment-variables) del workspace, risolta per l'ambiente corrente. |

`AuthConnection.id(id)` usa una connessione di autenticazione del workspace tramite ID. `AuthConnection.env_var(label)` / `AuthConnection.envVar(label)` la seleziona da una variabile d'ambiente, così la stessa configurazione dello strumento può usare una connessione diversa in ogni ambiente.

```python
from elevenlabs.agent_tools import AuthConnection, Header

update_profile = (
    Tool.webhook("update_profile", "Update the caller's email address")
    .put("https://api.example.com/profiles/{profile_id}")
    .path_param("profile_id", Schema.string().from_variable("profile_id"))
    .body(Schema.object().property("email", Schema.string().describe("The new email address")))
    .header("X-Api-Key", Header.env_var("profiles_api_key"))
    .auth(AuthConnection.env_var("profiles_oauth"))
)
```

```typescript
import { AuthConnection, Header } from "@elevenlabs/elevenlabs-js";

const updateProfile = Tool.webhook("update_profile", "Update the caller's email address")
  .put("https://api.example.com/profiles/{profile_id}")
  .pathParam("profile_id", Schema.string().fromVariable("profile_id"))
  .body(Schema.object().property("email", Schema.string().describe("The new email address")))
  .header("X-Api-Key", Header.envVar("profiles_api_key"))
  .auth(AuthConnection.envVar("profiles_oauth"));
```

## Crea uno strumento client

`Tool.client(name, description)` avvia uno [strumento client](/docs/it/eleven-agents/customization/tools/client-tools), che viene eseguito nella tua applicazione anziché su un server. Aggiungi i relativi parametri con `param(name, schema)`. Imposta `expects_response` / `expectsResponse` quando l'agente deve attendere il risultato della tua applicazione:

```python
show_map = (
    Tool.client("show_store_map", "Show the caller a map of the nearest store")
    .param("store_id", Schema.string().describe("The store to show"))
    .options(expects_response=False)
)
```

```typescript
const showMap = Tool.client("show_store_map", "Show the caller a map of the nearest store")
  .param("store_id", Schema.string().describe("The store to show"))
  .options({ expectsResponse: false });
```

## Crea uno strumento di sistema

Gli [strumenti di sistema](/docs/it/eleven-agents/customization/tools/system-tools) sono integrati nella piattaforma. Ognuno ha il proprio costruttore in `SystemTool`, che accetta le impostazioni dello strumento:

| Python                                                  | JavaScript                                            |
| ------------------------------------------------------- | ----------------------------------------------------- |
| `SystemTool.end_call()`                                 | `SystemTool.endCall()`                                |
| `SystemTool.skip_turn(wait_timeout_secs=...)`           | `SystemTool.skipTurn({ waitTimeoutSecs })`            |
| `SystemTool.language_detection(...)`                    | `SystemTool.languageDetection(options?)`              |
| `SystemTool.play_keypad_touch_tone(...)`                | `SystemTool.playKeypadTouchTone(options?)`            |
| `SystemTool.voicemail_detection(voicemail_message=...)` | `SystemTool.voicemailDetection({ voicemailMessage })` |
| `SystemTool.knowledge_base(enabled_strategies=...)`     | `SystemTool.knowledgeBase({ enabledStrategies })`     |
| `SystemTool.transfer_to_number(...)`                    | `SystemTool.transferToNumber(options?)`               |
| `SystemTool.transfer_to_agent()`                        | `SystemTool.transferToAgent()`                        |

I due strumenti di trasferimento ricevono le destinazioni da `transfer(condition, destination, options)`. La condizione indica all'LLM quando effettuare il trasferimento e la destinazione usa lo stesso `Destination` dei [workflow come codice](/docs/it/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Un trasferimento a un URI SIP richiede un trasferimento SIP REFER:

```python
from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination

transfer = (
    SystemTool.transfer_to_number()
    .transfer("Caller asks for billing", Destination.phone("+15551234567"))
    .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)

to_sales = SystemTool.transfer_to_agent().transfer(
    "Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)
```

```typescript
import { Destination, SystemTool } from "@elevenlabs/elevenlabs-js";

const transfer = SystemTool.transferToNumber()
  .transfer("Caller asks for billing", Destination.phone("+15551234567"))
  .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), {
    transferType: "sip_refer",
  });

const toSales = SystemTool.transferToAgent().transfer(
  "Caller wants to buy something",
  Destination.agent("agent_sales"),
  { transferMessage: "Connecting you to sales" }
);
```

## Opzioni dello strumento

Le impostazioni condivise da ogni tipo di strumento vanno in `options()`, come argomenti con nome in Python e come oggetto in JavaScript. I loro nomi corrispondono ai campi della configurazione dello strumento nell'API:

| Si applica a        | Python                                                                                                                                       | JavaScript                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Tutti gli strumenti | `name`, `description`, `response_timeout_secs`, `interruption_mode`, `pre_tool_speech`, `tool_call_sound`, `tool_error_handling_mode`, ...   | `name`, `description`, `responseTimeoutSecs`, `interruptionMode`, `preToolSpeech`, `toolCallSound`, `toolErrorHandlingMode`, ...    |
| Strumenti webhook   | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Strumenti client    | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `expectsResponse`, `dynamicVariablePlaceholders`                                                                   |

Il timeout della risposta di uno strumento webhook va da 5 a 300 secondi. Quello di uno strumento client va da 1 a 120 secondi, oppure è -1 per attendere il tempo necessario, opzione che richiede `expects_response` / `expectsResponse`. `follow_redirects` / `followRedirects` richiede un elenco di domini consentiti.

## Collega strumenti a un agente

Gli strumenti webhook e client vengono creati separatamente con `tools.create()` e collegati agli agenti tramite ID, così uno strumento può essere condiviso da più agenti. Gli strumenti di sistema fanno parte della configurazione dell'agente: `build_config()` / `buildConfig()` restituisce la voce per gli strumenti integrati dell'agente.

```python
from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput

order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

agent = elevenlabs.conversational_ai.agents.create(
    name="Support line",
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt=PromptAgentApiModelOutput(
                prompt="You are a support agent for Acme.",
                tool_ids=[order_tool.id],
                built_in_tools=BuiltInToolsOutput(
                    end_call=SystemTool.end_call().build_config(),
                    transfer_to_number=transfer.build_config(),
                ),
            )
        )
    ),
)
```

```typescript
const orderTool = await elevenlabs.conversationalAi.tools.create(getOrder.build());

const agent = await elevenlabs.conversationalAi.agents.create({
  name: "Support line",
  conversationConfig: {
    agent: {
      prompt: {
        prompt: "You are a support agent for Acme.",
        toolIds: [orderTool.id],
        builtInTools: {
          endCall: SystemTool.endCall().buildConfig(),
          transferToNumber: transfer.buildConfig(),
        },
      },
    },
  },
});
```

> **Warning**
>
> Il campo `prompt.tools` dell'agente, che contiene le configurazioni degli strumenti inline, è deprecato. Non può essere
> combinato con `tool_ids` e, quando una richiesta lo include, gli strumenti integrati dell'agente vengono sostituiti
> dagli strumenti di sistema che contiene. Crea invece gli strumenti con `tools.create()` e collegali tramite ID.

## Modifica uno strumento esistente

`Tool.from_response()` / `Tool.fromResponse()` carica uno strumento restituito da `tools.get()`. I campi che il builder non modella e i valori predefiniti compilati dall'API vengono mantenuti, quindi reinviarlo modifica solo ciò che hai cambiato. `as_webhook()`, `as_client()` e `as_system()` (`asWebhook()` e così via in JavaScript) restituiscono lo strumento tipizzato da modificare, oppure `None` / `undefined` se è di un altro tipo.

Per modificare una proprietà del body, leggi lo schema del body, imposta nuovamente la proprietà e imposta il body:

```python
from elevenlabs.agent_tools import ObjectSchema

loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
    raise ValueError("Not a webhook tool")

body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())

elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())
```

```typescript
import { type ObjectSchema, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const loaded = Tool.fromResponse(
  await elevenlabs.conversationalAi.tools.get("tool_id")
).asWebhook();
if (!loaded) throw new Error("Not a webhook tool");

const body = loaded.bodySchema as ObjectSchema;
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")));
loaded.queryParam("locale", Schema.string().describe("The caller's language").optional());

await elevenlabs.conversationalAi.tools.update("tool_id", loaded.build());
```

## Archivia gli strumenti nel controllo versione

`to_json_string()` / `toJSONString()` scrive lo strumento nel wire format dell'API: chiavi in snake_case, ordinate a ogni livello, con rientro di 2 spazi. È lo stesso formato che la [CLI](/docs/it/eleven-agents/operate/cli) conserva nella directory `tool_configs/` e, per lo stesso strumento, entrambi gli SDK scrivono file identici byte per byte, così le differenze rimangono limitate. `Tool.from_json()` / `Tool.fromJSON()` lo legge nuovamente.

```python
from pathlib import Path

from elevenlabs.agent_tools import Tool

Path("tool_configs/get_order.json").write_text(get_order.to_json_string())

stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())
```

```typescript
import { Tool } from "@elevenlabs/elevenlabs-js";
import { readFile, writeFile } from "node:fs/promises";

await writeFile("tool_configs/get_order.json", getOrder.toJSONString());

const stored = Tool.fromJSON(await readFile("tool_configs/get_order.json", "utf8"));
await elevenlabs.conversationalAi.tools.update("tool_id", stored.build());
```

Una configurazione tipica è uguale a quella dei [workflow](/docs/it/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control): inizializza i file con `elevenlabs tools pull`, modificali direttamente o con il builder, esegui `Tool.from_json(file).build()` / `Tool.fromJSON(file).build()` in CI a ogni pull request e inviali con `tools.update()` o `elevenlabs tools push` al merge.

## Convalida

Le chiamate concatenate non generano mai errori da sole. `build()`, `build_config()` / `buildConfig()`, `to_json()` / `toJSON()` e `to_json_string()` / `toJSONString()` controllano l'intero strumento e sollevano o lanciano un singolo `ToolValidationError`, il cui elenco `issues` raccoglie ogni problema, ciascuno con un `code`, un `message` e il `path` della parte interessata, ad esempio `body.reason`.

```python
from elevenlabs.agent_tools import ToolValidationError

try:
    request = refund.build()
except ToolValidationError as err:
    for issue in err.issues:
        print(issue.code, issue.path, issue.message)
```

```typescript
import { ToolValidationError } from "@elevenlabs/elevenlabs-js";

try {
  const request = refund.build();
} catch (err) {
  if (err instanceof ToolValidationError) {
    for (const issue of err.issues) console.error(issue.code, issue.path, issue.message);
  } else {
    throw err;
  }
}
```

Gli errori includono:

* Un placeholder URL senza parametro del path o un parametro del path senza placeholder. I template delle variabili d'ambiente come `{{system__env_api_host}}` non sono placeholder.
* Un valore letterale senza una fonte del valore o con più di una.
* Un body in una `GET` oppure nessun body in una `POST`, `PUT` o `PATCH`.
* Lo stesso nome di parametro in più di uno tra path, query e body.
* `omit()` su una proprietà obbligatoria, `choices()` su uno schema che non è una stringa o una costante che non corrisponde al tipo dello schema.
* Uno strumento di trasferimento senza destinazioni, una destinazione del tipo errato o una destinazione URI SIP senza trasferimento SIP REFER.
* Un'opzione che non si applica al tipo di strumento o un timeout fuori dall'intervallo consentito.

## Tipi di strumenti più recenti del tuo SDK

Uno strumento caricato dall'API o da un file può essere di un tipo che il builder non può modificare, ad esempio uno strumento MCP. Viene caricato con il tipo `"other"` e passa invariato attraverso `from_json()` / `fromJSON()` e `to_json_string()` / `toJSONString()`, mentre `build()` lo segnala come avviso tramite `on_warning` / `onWarning`.