Zbuduj integrację narzędzia (API)

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. 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:

Schemat — definicja funkcji w stylu OpenAI ({type: "function", function: {name, description, parameters}}), która informuje LLM, co robi narzędzie i jakie argumenty przyjmuje.
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

Bezpośrednio w agencie

Dołącz jednorazowe narzędzie do tablicy tools agenta. Proste, ale nie nadaje się do ponownego użycia.

Zapisana integracja

Zapisz narzędzie jako integrację wielokrotnego użytku integration 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ę

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ść:

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" }
  }'

Response

{
  "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:

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: <HMAC-SHA256 hex>
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:

{"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.

6. Przetestuj przepływ

Uruchom sesję mikrofonu dla agenta i zadaj pytanie obsługiwane przez narzędzie („Jaka jest pogoda w 94110?”). Transkrypcja połączenia pokazuje pełny przepływ:

{
  "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; surowy strumień zdarzeń (z czasem dla każdego wpisu i przesunięciami audio) znajduje się pod GET /v1/calls/{call_id}/history.

Typowe pułapki

Agent nigdy nie wywołuje narzędzia

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.”).

Narzędzie zwraca zbyt dużo danych

Odpowiedzi większe niż 6 kB są obcinane w podglądzie transkrypcji. Zwracaj tylko pola potrzebne LLM — nie cały wiersz.

Limity czasu

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.

Wersjonowanie

Każde PATCH integracji tworzy nową wersję. Sprawdź GET /v1/integrations/{id}/versions, 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

Dokumentacja integracji

CRUD, transfer, historia wersji.

Specyfikacja narzędzi funkcji

Pełna gramatyka schematu JSON i kontrakt podpisanego punktu końcowego.

Weryfikacja podpisów

Zastosuj wzorzec podpisu webhooka do punktów końcowych narzędzi.

API transkrypcji i historii

Sprawdź pełny cykl wywołania narzędzia.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Zbuduj integrację narzędzia (API)

Budowa narzędzia

1. Wybierz strategię przechowywania

Bezpośrednio w agencie

Zapisana integracja

2. Utwórz integrację

3. Przetestuj punkt końcowy w piaskownicy

4. Połącz integrację z agentem

5. Zaimplementuj punkt końcowy

6. Przetestuj przepływ

Typowe pułapki

Kolejne kroki

Dokumentacja integracji

Specyfikacja narzędzi funkcji

Weryfikacja podpisów

API transkrypcji i historii

​Budowa narzędzia

​1. Wybierz strategię przechowywania

Bezpośrednio w agencie

Zapisana integracja

​2. Utwórz integrację

​3. Przetestuj punkt końcowy w piaskownicy

​4. Połącz integrację z agentem

​5. Zaimplementuj punkt końcowy

​6. Przetestuj przepływ

​Typowe pułapki

​Kolejne kroki

Dokumentacja integracji

Specyfikacja narzędzi funkcji

Weryfikacja podpisów

API transkrypcji i historii

Budowa narzędzia

1. Wybierz strategię przechowywania

2. Utwórz integrację

3. Przetestuj punkt końcowy w piaskownicy

4. Połącz integrację z agentem

5. Zaimplementuj punkt końcowy

6. Przetestuj przepływ

Typowe pułapki

Kolejne kroki