Vytvoření integrace nástroje (API)

Integrace nástroje je opakovaně použitelný koncový bod HTTP, který může agent během hovoru vyvolat. ThunderPhone poskytnete popis nástroje ve formátu schématu JSON spolu s adresou URL koncového bodu; agent na základě konverzace rozhodne, kdy jej zavolat, a ThunderPhone ze svých serverů odešle odchozí požadavek HTTP a vrátí odpověď agentovi.

Ovládací panel pokrývá většinu potřeb týkajících se nástrojů i bez tohoto rozhraní API: Připojení → Aplikace připojí Slack, HubSpot, Salesforce, Kalendář Google, Tabulky Google a Cal.com několika kliknutími OAuth; Připojení → API promění libovolné rozhraní HTTP API v akci agenta (vložte příkaz cURL a průvodce AI připraví návrh nástroje včetně integrované funkce Testovat požadavek); a Připojení → MCP přidá servery MCP. Viz Připojení. Tento průvodce popisuje základní API pod rozhraním API.

Tento průvodce vás krok za krokem provede vytvořením nástroje pro zjišťování počasí.

Anatomie nástroje

Dvě části:

Schéma — definice funkce ve stylu OpenAI ({type: "function", function: {name, description, parameters}}), která LLM sděluje, co nástroj dělá a jaké argumenty přijímá.
Koncový bod — adresa URL, kterou servery ThunderPhone volají, když se LLM rozhodne nástroj použít. Požadavek je JSON POST s argumenty zvolenými LLM v těle požadavku.

1. Zvolte strategii ukládání

Přímo u agenta

Připojte jednorázový nástroj k poli tools agenta. Je to jednoduché, ale nástroj nelze znovu použít.

Uložená integrace

Uložte nástroj jako opakovaně použitelnou integraci a propojte jej s více agenty. Doporučeno pro vše, co používáte více než jednou.

Tento průvodce používá postup s uloženou integrací.

2. Vytvořte integraci

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

Uložte vrácené id (UUID).

Věnujte skutečné úsilí hodnotě description nástroje i každého parametru. LLM tyto řetězce za běhu používá k rozhodnutí, zda a jak nástroj zavolat. Neurčité popisy → neurčitá volání nástroje.

3. Otestujte koncový bod v sandboxu

Než integraci propojíte s agentem, odešlete podepsaný požadavek ze serverů ThunderPhone a ověřte připojení:

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, ...}"
}

Tento test také posiluje ochranu ThunderPhone proti SSRF — požadavky na localhost nebo rozsahy soukromých IP adres vrátí 400 code=url_not_allowed.

4. Propojte integraci s agentem

Při vytváření nebo aktualizaci agenta ji připojte pomocí integration_ids:

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

K jednomu agentovi můžete propojit více integrací. Prompt agenta na ně může odkazovat podle názvu — „použijte get_weather, když volající požádá o informace o podmínkách“ — nebo je může implicitně rozpoznat z popisů schématu.

5. Implementujte koncový bod

Když agent vyvolá nástroj, ThunderPhone odešle podepsaný požadavek POST na vaši adresu 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"}

Váš server odpoví daty JSON, která se předají zpět LLM:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM tuto odpověď zpracuje a volajícímu sdělí srozumitelné shrnutí.

Podpis se vypočítává ze surového těla požadavku pomocí stejného secret jako váš koncový bod webhooku. Ověřte jej — koncové body nástrojů jsou dostupné z internetu a vztahují se na ně stejné obavy z podvržení jako na webhooky. Viz Ověření podpisů webhooků.

6. Otestujte celý cyklus

Spusťte relaci mikrofonu s agentem a položte otázku, kterou váš nástroj zpracovává („Jaké je počasí v 94110?“). Přepis hovoru zobrazí celý průběh požadavku a odpovědi:

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

Tyto údaje můžete získat pomocí GET /v1/calls/{call_id}/transcript; nezpracovaný stream událostí (včetně časování jednotlivých záznamů a posunů zvuku) najdete na GET /v1/calls/{call_id}/history.

Běžné chyby

Agent nikdy nevolá nástroj

LLM rozhoduje podle popisu nástroje. Pokud otázka volajícího neodpovídá popisu, model nástroj nevyvolá. Upřesněte popis (přidejte běžná synonyma a formulace) nebo jej výslovně uveďte v promptu agenta („Když se volající zeptá na počasí, použijte get_weather.“).

Nástroj vrací příliš mnoho dat

Odpovědi větší než 6 kB jsou v náhledu přepisu zkráceny. Vraťte pouze pole, která LLM potřebuje — ne celý záznam.

Časové limity

Koncové body nástrojů mají výchozí časový limit 10 sekund. Pokud potřebujete delší, zpracujte požadavek asynchronně: vraťte {"status": "pending", "request_id": "..."} a výsledek zpřístupněte prostřednictvím samostatného volání nástroje.

Verzování

Každý PATCH integrace vytvoří novou revizi. Zkontrolujte GET /v1/integrations/{id}/versions a zjistěte, kdo co změnil. Pokud nekompatibilně změníte schéma nástroje, můžete se ručně vrátit zpět tak, že pomocí PATCH znovu nahrajete starší snímek.

Další kroky

Referenční dokumentace integrací

CRUD, přenos, historie verzí.

Specifikace nástrojů funkcí

Úplná gramatika schématu JSON a kontrakt podepsaného endpointu.

Ověření podpisů

Použijte vzor podpisu webhooku pro endpointy nástrojů.

API přepisu + historie

Prohlédněte si celý cyklus volání nástroje.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Vytvoření integrace nástroje (API)

Anatomie nástroje

1. Zvolte strategii ukládání

Přímo u agenta

Uložená integrace

2. Vytvořte integraci

3. Otestujte koncový bod v sandboxu

4. Propojte integraci s agentem

5. Implementujte koncový bod

6. Otestujte celý cyklus

Běžné chyby

Další kroky

Referenční dokumentace integrací

Specifikace nástrojů funkcí

Ověření podpisů

API přepisu + historie

​Anatomie nástroje

​1. Zvolte strategii ukládání

Přímo u agenta

Uložená integrace

​2. Vytvořte integraci

​3. Otestujte koncový bod v sandboxu

​4. Propojte integraci s agentem

​5. Implementujte koncový bod

​6. Otestujte celý cyklus

​Běžné chyby

​Další kroky

Referenční dokumentace integrací

Specifikace nástrojů funkcí

Ověření podpisů

API přepisu + historie

Anatomie nástroje

1. Zvolte strategii ukládání

2. Vytvořte integraci

3. Otestujte koncový bod v sandboxu

4. Propojte integraci s agentem

5. Implementujte koncový bod

6. Otestujte celý cyklus

Běžné chyby

Další kroky