> ## 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. # Vytvoření integrace nástroje (API) > Umožněte svému agentovi během hovoru volat vaše API — prohledávat databázi, vytvářet požadavky nebo vyhledávat objednávky. **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í](/cs/guides/concepts). 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: 1. **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á. 2. **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řipojte jednorázový nástroj k poli `tools` agenta. Je to jednoduché, ale nástroj nelze znovu použít. Uložte nástroj jako opakovaně použitelnou [integraci](/api-reference/integrations) 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 ```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" } ] }' ``` 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í: ```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, ...}" } ``` 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`: ```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-..."] }' ``` 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: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Váš server odpoví daty JSON, která se předají zpět LLM: ```json theme={null} {"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ů](/cs/guides/verify-webhook-signatures). ## 6. Otestujte celý cyklus Spusťte [relaci mikrofonu](/api-reference/mic-sessions) 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: ```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." } ] } ``` Tyto údaje můžete získat pomocí [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); nezpracovaný stream událostí (včetně časování jednotlivých záznamů a posunů zvuku) najdete na [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Běžné chyby 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`.“). 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. 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. Každý `PATCH` integrace vytvoří novou revizi. Zkontrolujte [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) 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 CRUD, přenos, historie verzí. Úplná gramatika schématu JSON a kontrakt podepsaného endpointu. Použijte vzor podpisu webhooku pro endpointy nástrojů. Prohlédněte si celý cyklus volání nástroje.