> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Narzędzia (Tools)

> Podłączaj narzędzia (np. wywołania API) do agenta - użyje ich w trakcie rozmowy na podstawie Twoich promptów.

Brosbots pozwala podpiąć wiele narzędzi (np. wywołań API) bezpośrednio do
agenta, w zakładce **Narzędzia**. Dzięki temu agent głosowy może w trakcie żywej rozmowy
wywołać dowolny wewnętrzny lub zewnętrzny system - decyzję podejmuje LLM na
podstawie Twoich promptów.

Działa to jak tool calling na każdej platformie agentowej i jest w pełni
konfigurowalne.

## Gdzie tworzysz narzędzia

Narzędzia zakładasz w **Integracjach**. Katalog otwiera się jedną ciągłą
siatką, a kafelki narzędzi agenta - **przekierowanie rozmowy**, **zakończenie
rozmowy** i **własne HTTP API** - stoją na jej początku.

Narzędzie HTTP najłatwiej zbudować w kreatorze: **Integracje** → zakładka
**Własne**. Prowadzi krok po kroku (adres, klucz, pola, test na prawdziwym
API, wybór pól odpowiedzi, frazy klienta, agenci), ma szablony i przyjmuje
wklejone polecenie cURL. Opis: [Własne integracje](/pl/integrations/custom).

Narzędzia podpinasz do agenta w kreatorze (krok **Agenci**) albo w zakładce
**Narzędzia** edytora agenta.

### Co dodaje kreator

Narzędzie z kreatora ma kilka ustawień, których nie ma w zwykłym formularzu.
Pełny edytor (**Zaawansowane**) je zachowuje:

| Ustawienie | Działanie |
| - | - |
| Frazy klienta | dopisywane do opisu narzędzia, który widzi model |
| Komunikat oczekiwania | agent mówi go, zanim API odpowie (zamiast ogólnej frazy agenta) |
| Pola odpowiedzi | agent dostaje tylko wybrane pola odpowiedzi (`order.status`, `items.0.name`) |
| Komunikat błędu | zdanie, które agent powie, gdy API zwróci błąd albo nie odpowie |
| Typy Data i Telefon | wartości idą jako tekst `RRRR-MM-DD` i `+48600100200` |

## Czym są narzędzia?

Narzędzie to akcja, którą LLM może wywołać w trakcie rozmowy. Brosbots
obsługuje cztery kategorie:

1. **HTTP API (Webhook niestandardowy)** - wywołanie dowolnego endpointu REST (Twój backend, CRM, zewnętrzne API)
2. **Transfer** - przekazanie rozmowy do człowieka lub na inny numer
3. **End Call** - kulturalne zakończenie rozmowy
4. **Połączona usługa** - gotowa integracja bez pisania endpointu

**Typowe zastosowania:**

* wywołania własnego backendu,
* uruchamianie automatyzacji n8n,
* synchronizacja danych z CRM,
* pobieranie danych z zewnętrznych API (pogoda, ceny, dostępność),
* przekazanie pilnych spraw do konsultanta,
* zakończenie rozmowy po potwierdzeniu rezerwacji.

**LLM decyduje:** które narzędzie wywołać, kiedy i z jakimi parametrami -
na podstawie Twoich promptów, nazwy narzędzia, jego opisu i definicji
parametrów.

## Kategorie narzędzi

### Narzędzie HTTP API

Najbardziej elastyczne. Definiujesz endpoint REST, metodę, nagłówki,
uwierzytelnienie i parametry - LLM sam buduje payload i wywołuje endpoint.

### Narzędzie Transfer

Przekazuje trwającą rozmowę na inny numer. Przydatne do:

* eskalacji trudnych spraw do człowieka,
* kierowania połączeń do właściwego działu,
* przekazywania rozmów po godzinach na numer dyżurny.

Pola konfiguracji:

* **Numer docelowy** - dokąd przekazać rozmowę,
* **Komunikat przy przekazaniu** - opcjonalna wypowiedź przed transferem
  (np. „Łączę z konsultantem, proszę czekać.”),
* **Parametry** - opcjonalne dane przekazywane razem z transferem.

Przekazać można tylko na **polski numer stacjonarny albo komórkowy**.
Numerów zagranicznych, krótkich i o podwyższonej opłacie (70x) nie da się
zapisać, a rozmowa się na nie nie przełączy. Wyjątek to rozmowy z Twojej
centrali (np. Daktela): wracają do niej, więc mogą trafić także na numer
wewnętrzny albo kolejkę.

Agent dzwoni wyłącznie na numery ustawione przy agencie (numer docelowy
narzędzia, numer w ustawieniach narzędzi agenta albo nadpisanie w węźle).
Jeśli model poda w parametrze inny numer, na przykład podyktowany przez
dzwoniącego, zostaje on pominięty i rozmowa idzie na numer ustawiony.
Przekazana rozmowa trwa najwyżej 2 godziny.

Jak przebiega przekazanie: telefon osoby docelowej dzwoni przez **30 sekund**,
a dzwoniący w tym czasie zostaje z agentem i słyszy sygnał dzwonienia. Gdy
osoba odbierze, rozmowa przechodzi do niej, a agent się wyłącza. Gdy nikt nie
odbierze, numer jest zajęty albo niedostępny, rozmowa **wraca do agenta**:
agent mówi, że nikt z zespołu nie może teraz odebrać, zapisuje wiadomość
(imię, numer do oddzwonienia, sprawa) i obiecuje, że ktoś oddzwoni.
Wiadomość trafia do zapisu i podsumowania rozmowy jak każda inna wypowiedź.

Przekazania nie da się włączyć bez numeru: w zakładce **Integracje** agenta
najpierw wpisujesz numer, potem włączasz przełącznik, a zapis agenta z
włączonym przekazaniem i bez numeru jest odrzucany. Gdy przełączenie się nie
uda (np. numer odrzucony), agent nie milknie - przeprasza, zapisuje wiadomość
i obiecuje, że ktoś oddzwoni.

<Note>Na numerach Telnyx przekazanie też dzwoni 30 sekund, ale jest „ślepe”:
gdy nikt nie odbierze, rozmowa nie wraca do agenta. Powrót do agenta działa
na numerach BrosBots (plfon) i na rozmowach z Twojej centrali (np. Daktela).</Note>

<Note>Narzędzie Transfer nie ma opcji „View Code”, bo jest obsługiwane wewnętrznie przez platformę.</Note>

### Narzędzie End Call

Kulturalnie kończy rozmowę - zwykle podpinane do węzła End Call.

### Połączona usługa

Gotowa integracja - nie definiujesz URL-a ani nagłówków, wybierasz dostawcę:

* **Pogoda** - aktualna pogoda dla podanego miasta (bez klucza API),
* **Wyszukiwanie kontaktu w CRM** - szuka kontaktu w HubSpot po numerze
  telefonu lub adresie e-mail; podajesz typ CRM i klucz API. Token HubSpota
  musi mieć uprawnienie `crm.objects.contacts.read` - zobacz
  [Podłączenie HubSpota](/pl/integrations/overview#pod%C5%82%C4%85czenie-hubspota).

Wypełniasz nazwę, opis (na jego podstawie LLM decyduje, kiedy użyć
narzędzia) oraz parametry, o które model ma poprosić - np. `city` dla
pogody albo `phone` / `email` dla CRM. Narzędzie utworzone z tej kategorii
nie ma opcji „View Code”, bo wywołanie realizuje platforma.

## Definiowanie narzędzi

### 1. Nazwa narzędzia

* Jasna i akcyjna, np. `capture_lead_interest`, `fetch_weather`, `create_crm_contact`.

### 2. Opis narzędzia

* **Najważniejszy element** - na jego podstawie LLM decyduje, **kiedy** użyć narzędzia.
* Pisz prosto i jednoznacznie (po polsku lub angielsku).

**Źle:**
„API do zapisywania danych”

**Dobrze:**
„Narzędzie do oznaczenia zainteresowania. Użyj go, gdy rozmówca wyraźnie
wyraża zainteresowanie produktem albo prosi o kontakt.”

### 3. Konfiguracja endpointu

* Pełny URL (**musi zawierać `http://` lub `https://`**)
* Obsługiwane metody **REST**

<Note>Częsty błąd: brak https\:// w adresie URL.</Note>

### 4. Uwierzytelnianie i nagłówki

* Własne uwierzytelnianie i nagłówki
* Działa z usługami wewnętrznymi i zewnętrznymi API

### 5. Parametry

Każdy parametr ma: nazwę, typ, opis i flagę wymagany/opcjonalny.

**Opisy parametrów są ważniejsze niż typy.**

Wskazówki:

* na początek używaj parametrów typu string,
* opisuj jednoznacznie, co reprezentuje wartość,
* jako wymagane oznaczaj tylko naprawdę niezbędne pola.

Przykład:

* interest (string):
  „Ustaw true, jeśli rozmówca wyraźnie chce kupić albo prosi o kontakt. W przeciwnym razie false.”

## Podpinanie narzędzi do węzłów

* Do jednego węzła możesz podpiąć **wiele narzędzi**.
* Wszystkie utworzone narzędzia są dostępne do wyboru w węźle.
* Narzędzie da się wywołać tylko w węźle, do którego jest podpięte.
* LLM wybiera, którego użyć.

Wewnątrz węzła kieruj LLM-em **prostymi instrukcjami**, np.:

„Jeśli rozmówca chce rozmawiać z działem sprzedaży albo prosi o oddzwonienie,
natychmiast wywołaj narzędzie capture\_lead\_interest z interest = true.”

Taka instrukcja to często **czynnik decydujący** o poprawnym użyciu narzędzia.

## Jak LLM decyduje o wywołaniu

LLM bierze pod uwagę:

* intencję wypowiedzianą przez rozmówcę,
* instrukcje w promptcie węzła,
* nazwę i opis narzędzia,
* opisy parametrów.

Gdy wszystko jest spójne, narzędzie jest wywoływane automatycznie.
Słabe nazwy i mgliste opisy prowadzą do pominiętych wywołań, złych
parametrów i zmyślonych wartości.

## Najlepsze praktyki

* Nazywaj narzędzia jednoznacznie.
* Pisz szczegółowe, akcyjne opisy.
* Zaczynaj od prostych parametrów.
* Zawsze podawaj http/https w URL-ach.
* Instrukcje w węzłach pisz prostym językiem.
* Podpinaj do węzła tylko potrzebne narzędzia.

**Dobrze zdefiniowane narzędzia + jasne prompty = niezawodny, produkcyjny agent.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.