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

# Narzędzia jako kod

## Omówienie

[Tool](/docs/pl/eleven-agents/customization/tools) jest przechowywany jako konfiguracja z zagnieżdżonymi schematami JSON parametrów. Ręczne pisanie tej konfiguracji wymaga synchronizacji parametrów ścieżki z URL-em, list `required` z ich właściwościami oraz przypisania każdemu parametrowi dokładnie jednego źródła wartości. Kreator narzędzi w SDK dla Pythona i JavaScriptu pozwala opisać to samo narzędzie za pomocą łańcuchowych wywołań metod. Następnie tworzy żądanie, które akceptują już `tools.create()` i `tools.update()`.

Użyj go, aby:

* Definiować narzędzia webhook, klienckie i systemowe w kodzie oraz przeglądać je jak każdą inną zmianę w kodzie.
* Wczytać narzędzie, zmienić jeden parametr i odesłać je bez naruszania reszty konfiguracji.
* Zapisywać narzędzia jako JSON w kontroli wersji i walidować je w CI.

> **Note**
>
> Kreator działa całkowicie w SDK. Nie wywołuje nowych endpointów API, a wszystko, co utworzy, można
> otworzyć i edytować w panelu.

## Wymagania

* Python: pakiet `elevenlabs`. Kreator importuje się z `elevenlabs.agent_tools`.
* JavaScript: pakiet `@elevenlabs/elevenlabs-js`. Kreator jest eksportowany z głównego modułu pakietu.

## Tworzenie narzędzia webhook

`Tool.webhook(name, description)` tworzy [narzędzie webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools). Nazwa i opis to informacje, które widzi LLM, gdy decyduje, czy wywołać narzędzie. Ten przykład wyszukuje zamówienie po numerze podanym przez rozmówcę, wysyła klucz API z sekretów workspace'u i zapisuje status zamówienia w zmiennej dynamicznej:

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

Metody żądań ustawiają metodę HTTP i URL. Symbole zastępcze `{name}` w URL-u są uzupełniane parametrami ścieżki:

| Python                                                           | JavaScript                 | Ustawia                                                                                                                                         |
| ---------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | same                       | Metodę i URL. `POST`, `PUT` oraz `PATCH` wymagają treści żądania; `GET` nie może jej mieć.                                                      |
| `path_param(name, schema)`                                       | `pathParam(name, schema)`  | Parametr ścieżki dla symbolu zastępczego `{name}` w URL-u.                                                                                      |
| `query_param(name, schema)`                                      | `queryParam(name, schema)` | Parametr zapytania.                                                                                                                             |
| `body(schema)`                                                   | `body(schema)`             | Treść żądania. Musi być schematem obiektu.                                                                                                      |
| `response(schema)`                                               | `response(schema)`         | Schemat treści odpowiedzi. Musi być schematem obiektu.                                                                                          |
| `header(name, value)`                                            | `header(name, value)`      | Nagłówek żądania. Zobacz [Nagłówki i uwierzytelnianie](#headers-and-authentication).                                                            |
| `auth(connection)`                                               | `auth(connection)`         | [Połączenie uwierzytelniające](/docs/pl/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods), którego należy użyć. |
| `assign(variable, path)`                                         | `assign(variable, path)`   | Zapisuje wartość z `path` w odpowiedzi (notacja kropkowa) w zmiennej dynamicznej.                                                               |

Ustawienie parametru lub nagłówka o istniejącej nazwie zastępuje go i zachowuje jego pozycję. `remove_path_param()`, `remove_query_param()`, `remove_header()` i `remove_assignment()` (w JavaScripcie `removePathParam()` itd.) usuwają element. Nazwy parametrów muszą być unikalne dla ścieżki, zapytania i treści.

Treść żądania to schemat obiektu budowany właściwość po właściwości:

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

## Schematy parametrów

`Schema` tworzy schematy parametrów używane przez narzędzia webhook i klienckie. Każda metoda zwraca nowy schemat i nie zmienia tego, na którym została wywołana, więc możesz raz zdefiniować schemat i użyć go w kilku narzędziach.

| Konstruktor                                                               | Tworzy                                              |
| ------------------------------------------------------------------------- | --------------------------------------------------- |
| `Schema.string()`, `Schema.integer()`, `Schema.number()`, `Schema.bool()` | Wartość literalną                                   |
| `Schema.object()`                                                         | Obiekt. Dodaj właściwości przez `property()`.       |
| `Schema.array(items)`                                                     | Tablicę, której elementy pasują do schematu `items` |

### Źródło wartości

Każda wartość literalna potrzebuje dokładnie jednego źródła, niezależnie od tego, gdzie się znajduje: w parametrze, treści żądania, schemacie odpowiedzi albo wewnątrz obiektu czy tablicy. Obiekt lub tablica też mogą je mieć, co zapewnia wtedy całą wartość.

| Python                | JavaScript           | Wartość                                                                                                                                         |
| --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `describe(text)`      | `describe(text)`     | Jest podawana przez LLM zgodnie z wskazówką `text`.                                                                                             |
| `from_variable(name)` | `fromVariable(name)` | Jest odczytywana ze [zmiennej dynamicznej](/docs/pl/eleven-agents/customization/personalization/dynamic-variables) podczas działania narzędzia. |
| `constant(value)`     | `constant(value)`    | Zawsze wynosi `value`.                                                                                                                          |
| `system_provided()`   | `systemProvided()`   | Jest uzupełniana przez system podczas działania narzędzia. Tylko wartości literalne.                                                            |
| `omit()`              | `omit()`             | Jest pomijana w żądaniu. Tylko dla opcjonalnej właściwości.                                                                                     |

W przypadku obiektu lub tablicy `describe()` dokumentuje kontener dla LLM, a każda właściwość lub element nadal ma własne źródło.

### Inne metody schematu

| Python                                            | JavaScript                                    | Działanie                                                                                                  |
| ------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `optional()`                                      | `optional()`                                  | Czyni właściwość opcjonalną. Właściwości są wymagane, chyba że oznaczysz je jako opcjonalne.               |
| `choices(values)`                                 | `choices(values)`                             | Ogranicza tekst do ustalonego zestawu wartości, z których wybiera LLM.                                     |
| `allowed_from(variable)`                          | `allowedFrom(variable)`                       | Odrzuca wartość LLM, której nie ma na liście przechowywanej przez zmienną dynamiczną. Wymaga `describe()`. |
| `property(name, schema)` / `without(name)`        | `property(name, schema)` / `without(name)`    | Dodaje, zastępuje lub usuwa właściwość obiektu. Zastąpiona właściwość zachowuje pozycję.                   |
| `require_any_of(names)` / `require_all_of(names)` | `requireAnyOf(names)` / `requireAllOf(names)` | Wymaga co najmniej jednej lub wszystkich opcjonalnych właściwości z grupy.                                 |

## Nagłówki i uwierzytelnianie

Wartość nagłówka może pochodzić z jednego z czterech miejsc. Do danych wrażliwych używaj sekretu lub zmiennej środowiskowej, aby wartość nigdy nie pojawiła się w konfiguracji narzędzia:

| Konstruktor                                      | Wartość nagłówka                                                                                                                   |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Header.value(text)`                             | Stały tekst.                                                                                                                       |
| `Header.secret(id)`                              | Sekret z magazynu sekretów workspace'u.                                                                                            |
| `Header.variable(name)`                          | Zmienna dynamiczna, odczytywana podczas działania narzędzia.                                                                       |
| `Header.env_var(label)` / `Header.envVar(label)` | [Zmienna środowiskowa](/docs/pl/eleven-agents/integrate/environment-variables) workspace'u, rozwiązywana dla bieżącego środowiska. |

`AuthConnection.id(id)` używa połączenia uwierzytelniającego z workspace'u według ID. `AuthConnection.env_var(label)` / `AuthConnection.envVar(label)` wybiera je ze zmiennej środowiskowej, dzięki czemu ta sama konfiguracja narzędzia może używać innego połączenia w każdym środowisku.

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

## Tworzenie narzędzia klienckiego

`Tool.client(name, description)` tworzy [narzędzie klienckie](/docs/pl/eleven-agents/customization/tools/client-tools), które działa w twojej aplikacji, a nie na serwerze. Dodaj jego parametry przez `param(name, schema)`. Ustaw `expects_response` / `expectsResponse`, gdy agent ma czekać na wynik twojej aplikacji:

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

## Tworzenie narzędzia systemowego

[Narzędzia systemowe](/docs/pl/eleven-agents/customization/tools/system-tools) są wbudowane w platformę. Każde ma własny konstruktor w `SystemTool`, który przyjmuje ustawienia tego narzędzia:

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

Dwa narzędzia transferu pobierają miejsca docelowe z `transfer(condition, destination, options)`. Warunek mówi LLM, kiedy wykonać transfer, a miejsce docelowe używa tego samego `Destination` co [workflow jako kod](/docs/pl/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Transfer do URI SIP wymaga transferu 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" }
);
```

## Opcje narzędzi

Ustawienia wspólne dla każdego typu narzędzia umieszcza się w `options()`: jako argumenty nazwane w Pythonie i obiekt w JavaScripcie. Ich nazwy odpowiadają polom konfiguracji narzędzia w API:

| Dotyczy             | Python                                                                                                                                       | JavaScript                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Wszystkie narzędzia | `name`, `description`, `response_timeout_secs`, `interruption_mode`, `pre_tool_speech`, `tool_call_sound`, `tool_error_handling_mode`, ...   | `name`, `description`, `responseTimeoutSecs`, `interruptionMode`, `preToolSpeech`, `toolCallSound`, `toolErrorHandlingMode`, ...    |
| Narzędzia webhook   | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Narzędzia klienckie | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `expectsResponse`, `dynamicVariablePlaceholders`                                                                   |

Limit czasu odpowiedzi narzędzia webhook wynosi od 5 do 300 sekund. Dla narzędzia klienckiego wynosi od 1 do 120 sekund albo -1, aby czekać tak długo, jak potrzeba, co wymaga `expects_response` / `expectsResponse`. `follow_redirects` / `followRedirects` wymaga listy dozwolonych domen.

## Dodawanie narzędzi do agenta

Narzędzia webhook i klienckie są tworzone osobno przez `tools.create()` i dodawane do agentów za pomocą ID, więc jedno narzędzie może być współdzielone przez kilku agentów. Narzędzia systemowe są częścią konfiguracji agenta: `build_config()` / `buildConfig()` zwraca wpis dla wbudowanych narzędzi agenta.

```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**
>
> Pole `prompt.tools` agenta, które przechowuje konfiguracje narzędzi bezpośrednio, jest wycofywane. Nie można go
> łączyć z `tool_ids`, a gdy żądanie je zawiera, wbudowane narzędzia agenta są zastępowane
> narzędziami systemowymi, które ono zawiera. Zamiast tego twórz narzędzia przez `tools.create()` i dodawaj je według ID.

## Edycja istniejącego narzędzia

`Tool.from_response()` / `Tool.fromResponse()` wczytuje narzędzie zwrócone przez `tools.get()`. Pola, których kreator nie modeluje, oraz domyślne wartości uzupełniane przez API zostają zachowane, więc odesłanie narzędzia zmienia tylko to, co zmienisz. `as_webhook()`, `as_client()` i `as_system()` (w JavaScripcie `asWebhook()` itd.) zwracają typowane narzędzie do edycji albo `None` / `undefined`, jeśli jest innego rodzaju.

Aby zmienić właściwość treści żądania, odczytaj schemat treści, ponownie ustaw właściwość i ustaw treść:

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

## Przechowywanie narzędzi w kontroli wersji

`to_json_string()` / `toJSONString()` zapisuje narzędzie w formacie przesyłanym przez API: klucze w snake_case, sortowane na każdym poziomie, z wcięciem 2 spacji. Ma ten sam format, który [CLI](/docs/pl/eleven-agents/operate/cli) przechowuje w katalogu `tool_configs/`, a oba SDK zapisują bajt w bajt identyczne pliki dla tego samego narzędzia, więc różnice pozostają małe. `Tool.from_json()` / `Tool.fromJSON()` odczytuje je ponownie.

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

Typowa konfiguracja jest taka sama jak dla [workflow](/docs/pl/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control): zainicjuj pliki za pomocą `elevenlabs tools pull`, edytuj je bezpośrednio lub przez kreator, uruchamiaj `Tool.from_json(file).build()` / `Tool.fromJSON(file).build()` w CI przy każdym pull requeście i wysyłaj je przez `tools.update()` lub `elevenlabs tools push` po scaleniu.

## Walidacja

Wywołania łańcuchowe same w sobie nigdy nie kończą się błędem. `build()`, `build_config()` / `buildConfig()`, `to_json()` / `toJSON()` i `to_json_string()` / `toJSONString()` sprawdzają całe narzędzie oraz zgłaszają pojedynczy `ToolValidationError`, którego lista `issues` zawiera każdy problem wraz z `code`, `message` i `path` części, której dotyczy, na przykład `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;
  }
}
```

Błędy obejmują:

* Symbol zastępczy URL bez parametru ścieżki albo parametr ścieżki bez symbolu zastępczego. Szablony zmiennych środowiskowych, takie jak `{{system__env_api_host}}`, nie są symbolami zastępczymi.
* Wartość literalną bez źródła wartości albo z więcej niż jednym źródłem.
* Treść żądania przy `GET` albo brak treści przy `POST`, `PUT` lub `PATCH`.
* Tę samą nazwę parametru w więcej niż jednym z miejsc: ścieżce, zapytaniu i treści.
* `omit()` dla wymaganej właściwości, `choices()` dla schematu, który nie jest tekstem, albo stałą niezgodną z typem schematu.
* Narzędzie transferu bez miejsc docelowych, miejsce docelowe niewłaściwego rodzaju albo miejsce docelowe URI SIP bez transferu SIP REFER.
* Opcję, która nie dotyczy danego rodzaju narzędzia, albo limit czasu poza dozwolonym zakresem.

## Typy narzędzi nowsze niż twoje SDK

Narzędzie wczytane z API lub pliku może mieć typ, którego kreator nie może edytować, na przykład narzędzie MCP. Jest wczytywane z rodzajem `"other"` i bez zmian przechodzi przez `from_json()` / `fromJSON()` oraz `to_json_string()` / `toJSONString()`, a `build()` zgłasza je jako ostrzeżenie przez `on_warning` / `onWarning`.