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

# Tools als code

## Overzicht

Een [tool](/docs/nl/eleven-agents/customization/tools) wordt opgeslagen als een configuratie met geneste JSON-schema's voor de parameters. Als je die configuratie handmatig schrijft, moet je padparameters laten overeenkomen met de URL, `required`-lijsten met de bijbehorende eigenschappen en elke parameter precies één waardebron geven. Met de toolbuilder in de Python- en JavaScript-SDK's kun je dezelfde tool beschrijven met gekoppelde method calls. Vervolgens produceert deze de request die `tools.create()` en `tools.update()` al accepteren.

Gebruik deze om:

* Webhook-, client- en systeemtools in code te definiëren en ze te beoordelen zoals elke andere codewijziging.
* Een tool te laden, één parameter te wijzigen en deze terug te sturen zonder de rest van de configuratie te verstoren.
* Tools als JSON in versiebeheer op te slaan en ze in CI te valideren.

> **Note**
>
> De builder draait volledig in de SDK. Hij roept geen nieuwe API-endpoints aan en alles wat hij bouwt, kan
> in het dashboard worden geopend en bewerkt.

## Vereisten

* Python: het pakket `elevenlabs`. De builder wordt geïmporteerd vanuit `elevenlabs.agent_tools`.
* JavaScript: het pakket `@elevenlabs/elevenlabs-js`. De builder wordt geëxporteerd vanuit de pakketroot.

## Een webhooktool bouwen

`Tool.webhook(name, description)` start een [webhooktool](/docs/nl/eleven-agents/customization/tools/webhook-tools). De naam en beschrijving ziet de LLM wanneer die beslist of de tool wordt aangeroepen. Dit voorbeeld zoekt een bestelling op aan de hand van het nummer dat de beller opgeeft, stuurt een API-sleutel vanuit de secrets van de workspace en slaat de status van de bestelling op in een dynamische variabele:

```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());
```

De requestmethoden stellen de HTTP-methode en URL in. Tijdelijke aanduidingen `{name}` in de URL worden ingevuld vanuit padparameters:

| Python                                                           | JavaScript                 | Stelt in                                                                                                                      |
| ---------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | same                       | De methode en URL. `POST`, `PUT` en `PATCH` hebben een body nodig; `GET` kan er geen hebben.                                  |
| `path_param(name, schema)`                                       | `pathParam(name, schema)`  | Een padparameter voor de tijdelijke aanduiding `{name}` in de URL.                                                            |
| `query_param(name, schema)`                                      | `queryParam(name, schema)` | Een queryparameter.                                                                                                           |
| `body(schema)`                                                   | `body(schema)`             | De requestbody. Moet een objectschema zijn.                                                                                   |
| `response(schema)`                                               | `response(schema)`         | Het schema van de responsebody. Moet een objectschema zijn.                                                                   |
| `header(name, value)`                                            | `header(name, value)`      | Een requestheader. Zie [Headers en authenticatie](#headers-and-authentication).                                               |
| `auth(connection)`                                               | `auth(connection)`         | De te gebruiken [auth-verbinding](/docs/nl/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods). |
| `assign(variable, path)`                                         | `assign(variable, path)`   | Slaat de waarde bij `path` in de response (puntnotatie) op in een dynamische variabele.                                       |

Als je een parameter of header instelt waarvan de naam al bestaat, wordt die vervangen en behoudt deze zijn positie. Met `remove_path_param()`, `remove_query_param()`, `remove_header()` en `remove_assignment()` (in JavaScript `removePathParam()` enzovoort) verwijder je er één. Parameternamen moeten uniek zijn voor pad, query en body.

Een body is een objectschema dat eigenschap voor eigenschap wordt opgebouwd:

```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())
  );
```

## Parameterschema's

`Schema` bouwt de parameterschema's die webhook- en clienttools gebruiken. Elke methode retourneert een nieuw schema en laat het schema waarop deze is aangeroepen ongewijzigd, zodat je een schema één keer kunt definiëren en in meerdere tools kunt gebruiken.

| Constructor                                                               | Bouwt                                                              |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `Schema.string()`, `Schema.integer()`, `Schema.number()`, `Schema.bool()` | Een letterlijke waarde                                             |
| `Schema.object()`                                                         | Een object. Voeg eigenschappen toe met `property()`.               |
| `Schema.array(items)`                                                     | Een array waarvan de elementen overeenkomen met het schema `items` |

### Waar een waarde vandaan komt

Elke letterlijke waarde heeft precies één waardebron nodig, ongeacht waar deze voorkomt: in een parameter, in een body, in een responseschema of binnen een object of array. Een object of array kan er ook één hebben, die dan de volledige waarde levert.

| Python                | JavaScript           | De waarde                                                                                                                                    |
| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `describe(text)`      | `describe(text)`     | Wordt geleverd door de LLM, aangestuurd door `text`.                                                                                         |
| `from_variable(name)` | `fromVariable(name)` | Wordt uit een [dynamische variabele](/docs/nl/eleven-agents/customization/personalization/dynamic-variables) gelezen wanneer de tool draait. |
| `constant(value)`     | `constant(value)`    | Is altijd `value`.                                                                                                                           |
| `system_provided()`   | `systemProvided()`   | Wordt door het systeem ingevuld wanneer de tool draait. Alleen letterlijke waarden.                                                          |
| `omit()`              | `omit()`             | Wordt weggelaten uit de request. Alleen voor een optionele eigenschap.                                                                       |

Voor een object of array documenteert `describe()` de container voor de LLM en heeft elke eigenschap of elk element nog steeds een eigen bron.

### Andere schemamethoden

| Python                                            | JavaScript                                    | Doet                                                                                                                          |
| ------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `optional()`                                      | `optional()`                                  | Maakt een eigenschap optioneel. Eigenschappen zijn verplicht, tenzij ze als optioneel zijn gemarkeerd.                        |
| `choices(values)`                                 | `choices(values)`                             | Beperkt een string tot een vaste set waarden waaruit de LLM kiest.                                                            |
| `allowed_from(variable)`                          | `allowedFrom(variable)`                       | Wijst een LLM-waarde af die niet in de lijst staat die door een dynamische variabele wordt bijgehouden. Vereist `describe()`. |
| `property(name, schema)` / `without(name)`        | `property(name, schema)` / `without(name)`    | Voegt een objecteigenschap toe, vervangt deze of verwijdert deze. Een vervangen eigenschap behoudt zijn positie.              |
| `require_any_of(names)` / `require_all_of(names)` | `requireAnyOf(names)` / `requireAllOf(names)` | Vereist minstens één of alle eigenschappen uit een groep optionele eigenschappen.                                             |

## Headers en authenticatie

Een headerwaarde komt uit een van vier bronnen. Gebruik voor gevoelige gegevens een secret of omgevingsvariabele, zodat de waarde nooit in de toolconfiguratie verschijnt:

| Constructor                                      | De headerwaarde is                                                                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Header.value(text)`                             | Vaste tekst.                                                                                                                          |
| `Header.secret(id)`                              | Een secret uit de secretstore van de workspace.                                                                                       |
| `Header.variable(name)`                          | Een dynamische variabele, gelezen wanneer de tool draait.                                                                             |
| `Header.env_var(label)` / `Header.envVar(label)` | Een [omgevingsvariabele](/docs/nl/eleven-agents/integrate/environment-variables) van de workspace, opgelost voor de huidige omgeving. |

`AuthConnection.id(id)` gebruikt een auth-verbinding uit de workspace op basis van ID. `AuthConnection.env_var(label)` / `AuthConnection.envVar(label)` kiest deze uit een omgevingsvariabele, zodat dezelfde toolconfiguratie in elke omgeving een andere verbinding kan gebruiken.

```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"));
```

## Een clienttool bouwen

`Tool.client(name, description)` start een [clienttool](/docs/nl/eleven-agents/customization/tools/client-tools), die in je applicatie draait in plaats van op een server. Voeg parameters toe met `param(name, schema)`. Stel `expects_response` / `expectsResponse` in wanneer de agent moet wachten op het resultaat van je applicatie:

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

## Een systeemtool bouwen

[Systeemtools](/docs/nl/eleven-agents/customization/tools/system-tools) zijn ingebouwd in het platform. Elke tool heeft een eigen constructor op `SystemTool`, die de instellingen van die tool accepteert:

| 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()`                        |

De twee transfertools halen hun bestemmingen uit `transfer(condition, destination, options)`. De voorwaarde vertelt de LLM wanneer deze daarnaartoe moet transfereren en de bestemming gebruikt dezelfde `Destination` als [workflows als code](/docs/nl/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Voor een transfer naar een SIP-URI is een SIP REFER-transfer nodig:

```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" }
);
```

## Toolopties

Instellingen die alle soorten tools delen, plaats je in `options()`: als keyword arguments in Python en als object in JavaScript. De namen komen overeen met de velden van de toolconfiguratie in de API:

| Van toepassing op | Python                                                                                                                                       | JavaScript                                                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Alle tools        | `name`, `description`, `response_timeout_secs`, `interruption_mode`, `pre_tool_speech`, `tool_call_sound`, `tool_error_handling_mode`, ...   | `name`, `description`, `responseTimeoutSecs`, `interruptionMode`, `preToolSpeech`, `toolCallSound`, `toolErrorHandlingMode`, ...    |
| Webhooktools      | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Clienttools       | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `expectsResponse`, `dynamicVariablePlaceholders`                                                                   |

De responsetime-out van een webhooktool is 5 tot 300 seconden. Die van een clienttool is 1 tot 120 seconden, of -1 om zo lang als nodig te wachten; daarvoor is `expects_response` / `expectsResponse` vereist. Voor `follow_redirects` / `followRedirects` is een lijst met toegestane domeinen vereist.

## Tools aan een agent koppelen

Webhook- en clienttools worden afzonderlijk gemaakt met `tools.create()` en via ID aan agents gekoppeld, zodat één tool door meerdere agents kan worden gedeeld. Systeemtools maken deel uit van de configuratie van de agent: `build_config()` / `buildConfig()` retourneert de invoer voor de ingebouwde tools van de agent.

```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**
>
> Het veld `prompt.tools` van de agent, waarin toolconfiguraties inline worden opgeslagen, is verouderd. Het kan niet worden
> gecombineerd met `tool_ids`, en wanneer een request het bevat, worden de ingebouwde tools van de agent vervangen
> door de systeemtools die het bevat. Maak tools met `tools.create()` en koppel ze in plaats daarvan via ID.

## Een bestaande tool bewerken

`Tool.from_response()` / `Tool.fromResponse()` laadt een tool die wordt geretourneerd door `tools.get()`. Velden die de builder niet modelleert en de standaardwaarden die de API invult, blijven behouden, dus terugsturen wijzigt alleen wat je hebt gewijzigd. `as_webhook()`, `as_client()` en `as_system()` (in JavaScript `asWebhook()` enzovoort) geven je de getypeerde tool om te bewerken, of `None` / `undefined` als het een ander soort tool is.

Om een body-eigenschap te wijzigen, lees je het bodyschema, stel je de eigenschap opnieuw in en stel je de body in:

```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());
```

## Tools opslaan in versiebeheer

`to_json_string()` / `toJSONString()` schrijft de tool in het wireformat van de API: snake_case-sleutels, gesorteerd op elk niveau, met inspringing van 2 spaties. Het heeft dezelfde structuur als de [CLI](/docs/nl/eleven-agents/operate/cli) bewaart in de directory `tool_configs/`, en beide SDK's schrijven voor dezelfde tool byte voor byte identieke bestanden, zodat diffs klein blijven. `Tool.from_json()` / `Tool.fromJSON()` leest het weer in.

```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());
```

Een gebruikelijke opzet is dezelfde als voor [workflows](/docs/nl/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control): vul de bestanden eerst met `elevenlabs tools pull`, bewerk ze rechtstreeks of met de builder, voer `Tool.from_json(file).build()` / `Tool.fromJSON(file).build()` uit in CI voor elke pull request en push ze bij een merge met `tools.update()` of `elevenlabs tools push`.

## Validatie

Gekoppelde calls mislukken nooit op zichzelf. `build()`, `build_config()` / `buildConfig()`, `to_json()` / `toJSON()` en `to_json_string()` / `toJSONString()` controleren de volledige tool en geven of werpen één `ToolValidationError` waarvan de lijst `issues` elk probleem bevat, met telkens een `code`, een `message` en het `path` van het betreffende onderdeel, zoals `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;
  }
}
```

Fouten omvatten:

* Een tijdelijke aanduiding in een URL zonder padparameter, of een padparameter zonder tijdelijke aanduiding. Templates voor omgevingsvariabelen zoals `{{system__env_api_host}}` zijn geen tijdelijke aanduidingen.
* Een letterlijke waarde zonder waardebron, of met meer dan één bron.
* Een body bij een `GET`, of geen body bij een `POST`, `PUT` of `PATCH`.
* Dezelfde parameternaam in meer dan één van pad, query en body.
* `omit()` bij een verplichte eigenschap, `choices()` bij een schema dat geen string is, of een constante die niet overeenkomt met het type van het schema.
* Een transfertool zonder bestemmingen, een bestemming van het verkeerde type of een SIP-URI-bestemming zonder SIP REFER-transfer.
* Een optie die niet van toepassing is op het soort tool, of een time-out buiten het toegestane bereik.

## Tooltypen die nieuwer zijn dan je SDK

Een tool die uit de API of uit een bestand is geladen, kan een type hebben dat de builder niet kan bewerken, zoals een MCP-tool. Deze wordt geladen met het type `"other"` en gaat ongewijzigd heen en terug via `from_json()` / `fromJSON()` en `to_json_string()` / `toJSONString()`. `build()` rapporteert deze als waarschuwing via `on_warning` / `onWarning`.