> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Zbuduj integrację narzędzia (API) > Pozwól swojemu agentowi wywoływać Twoje interfejsy API w trakcie rozmowy — przeszukiwać bazę danych, tworzyć zgłoszenia, sprawdzać zamówienia. **Integracja narzędzia** to wielokrotnego użytku punkt końcowy HTTP, który agent może wywołać podczas rozmowy. Przekazujesz ThunderPhone opis narzędzia w schemacie JSON oraz adres URL punktu końcowego; agent decyduje, kiedy je wywołać, na podstawie rozmowy, a ThunderPhone wysyła wychodzące żądanie HTTP ze swoich serwerów i zwraca odpowiedź agentowi. Panel obsługuje większość potrzeb związanych z narzędziami bez użycia tego API: **Połączenia → Aplikacje** łączy Slack, HubSpot, Salesforce, Kalendarz Google, Arkusze Google i Cal.com za pomocą kilku kliknięć OAuth; **Połączenia → API** przekształca dowolne API HTTP w akcję agenta (wklej polecenie cURL, a kreator AI przygotuje narzędzie z wbudowaną funkcją Testuj żądanie); oraz **Połączenia → MCP** dodaje serwery MCP. Zobacz [Połączenia](/pl/guides/concepts). Ten przewodnik dotyczy bazowego API stojącego za sekcją API. Ten przewodnik przedstawia kompleksowe tworzenie narzędzia do sprawdzania pogody. ## Budowa narzędzia Dwa elementy: 1. **Schemat** — definicja funkcji w stylu OpenAI (`{type: "function", function: {name, description, parameters}}`), która informuje LLM, co robi narzędzie i jakie argumenty przyjmuje. 2. **Punkt końcowy** — adres URL wywoływany przez serwery ThunderPhone, gdy LLM zdecyduje się użyć narzędzia. Żądanie to JSON POST z argumentami wybranymi przez LLM jako treścią. ## 1. Wybierz strategię przechowywania Dołącz jednorazowe narzędzie do tablicy `tools` agenta. Proste, ale nie nadaje się do ponownego użycia. Zapisz narzędzie jako integrację wielokrotnego użytku [integration](/api-reference/integrations) i połącz je z wieloma agentami. Zalecane dla wszystkiego, co jest używane więcej niż raz. Ten przewodnik korzysta z metody zapisanej integracji. ## 2. Utwórz integrację ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/integrations \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Weather API", "spec": { "type": "function", "function": { "name": "get_weather", "description": "Return the current weather for a zip code.", "parameters": { "type": "object", "properties": { "zip": { "type": "string", "description": "5-digit US ZIP code" } }, "required": ["zip"] } } }, "endpoint_url": "https://api.example.com/weather", "endpoint_method": "GET", "headers": [ { "key": "X-Api-Key", "value": "your-provider-key" } ] }' ``` Zapisz zwrócone `id` (UUID). Poświęć czas na przygotowanie `description` narzędzia oraz każdego parametru. LLM używa tych ciągów w czasie działania, aby zdecydować, czy i jak wywołać narzędzie. Nieprecyzyjne opisy → nieprecyzyjne wywołania narzędzi. ## 3. Przetestuj punkt końcowy w piaskownicy Przed połączeniem integracji z agentem wyślij podpisane żądanie z serwerów ThunderPhone, aby potwierdzić łączność: ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/integrations/test-request \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/weather?zip=94110", "method": "GET", "headers": { "X-Api-Key": "your-provider-key" } }' ``` ```json Response theme={null} { "ok": true, "status": 200, "elapsed_ms": 187, "response_headers": { "content-type": "application/json" }, "response_preview": "{\"temperature_f\": 64, ...}" } ``` Ten test wzmacnia również zabezpieczenia ThunderPhone przed SSRF — żądania do localhost lub prywatnych zakresów adresów IP zwracają `400 code=url_not_allowed`. ## 4. Połącz integrację z agentem Dołącz za pomocą `integration_ids` podczas tworzenia lub aktualizowania agenta: ```bash theme={null} curl -X PATCH https://api.thunderphone.com/v1/agents/12 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "integration_ids": ["f9b5a1a4-..."] }' ``` Możesz połączyć wiele integracji z jednym agentem. Prompt agenta może odwoływać się do nich po nazwie — „użyj `get_weather`, gdy rozmówca pyta o warunki pogodowe” — albo może wykrywać je pośrednio na podstawie opisów schematu. ## 5. Zaimplementuj punkt końcowy Gdy agent wywołuje narzędzie, ThunderPhone wysyła podpisane żądanie POST na Twój `endpoint_url`: ``` POST /weather HTTP/1.1 Host: api.example.com X-Api-Key: your-provider-key X-ThunderPhone-Signature: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Twój serwer odpowiada kodem JSON, który jest przekazywany z powrotem do LLM: ```json theme={null} {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM przetwarza tę odpowiedź i przekazuje rozmówcy zrozumiałe podsumowanie. Podpis jest obliczany na podstawie surowej treści żądania przy użyciu tego samego `secret` co punkt końcowy webhooka. **Zweryfikuj go** — punkty końcowe narzędzi są dostępne z internetu i podlegają tym samym zagrożeniom związanym z podszywaniem się co webhooki. Zobacz [Weryfikowanie podpisów webhooków](/pl/guides/verify-webhook-signatures). ## 6. Przetestuj przepływ Uruchom [sesję mikrofonu](/api-reference/mic-sessions) dla agenta i zadaj pytanie obsługiwane przez narzędzie („Jaka jest pogoda w 94110?”). Transkrypcja połączenia pokazuje pełny przepływ: ```json theme={null} { "call_id": 987654321, "transcripts": [ { "role": "user", "content": "What's the weather in 94110?" }, { "role": "tool_call", "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" }, { "role": "tool_response", "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" }, { "role": "agent", "content": "It's 64 degrees and partly cloudy." } ] } ``` Możesz pobrać ją za pomocą [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); surowy strumień zdarzeń (z czasem dla każdego wpisu i przesunięciami audio) znajduje się pod [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Typowe pułapki LLM podejmuje decyzję na podstawie opisu narzędzia. Jeśli pytanie rozmówcy nie pasuje do opisu, model nie wywoła narzędzia. Doprecyzuj opis (dodaj często używane synonimy i sformułowania) albo wyraźnie wspomnij o nim w prompcie agenta („Gdy rozmówca pyta o pogodę, użyj `get_weather`.”). Odpowiedzi większe niż 6 kB są obcinane w podglądzie transkrypcji. Zwracaj tylko pola potrzebne LLM — nie cały wiersz. Punkty końcowe narzędzi mają domyślny limit czasu 10 sekund. Jeśli potrzebujesz więcej, obsłuż to asynchronicznie: zwróć `{"status": "pending", "request_id": "..."}` i udostępnij wynik przez oddzielne wywołanie narzędzia. Każde `PATCH` integracji tworzy nową wersję. Sprawdź [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history), aby zobaczyć, kto co zmienił. Jeśli uszkodzisz schemat narzędzia, możesz ręcznie cofnąć zmiany, ponownie stosując PATCH do starszego migawki. *** ## Kolejne kroki CRUD, transfer, historia wersji. Pełna gramatyka schematu JSON i kontrakt podpisanego punktu końcowego. Zastosuj wzorzec podpisu webhooka do punktów końcowych narzędzi. Sprawdź pełny cykl wywołania narzędzia.