--- title: "Vytvoření integrace nástroje (API)" description: "Umožněte svému agentovi volat vaše API během konverzace — vyhledávat v databázi, vytvářet tikety nebo dohledávat objednávky." --- **Integrace nástroje** je opakovaně použitelný koncový bod HTTP, který může agent vyvolat během hovoru. Poskytnete ThunderPhone popis nástroje ve formátu schématu JSON spolu s adresou URL koncového bodu; agent na základě konverzace rozhodne, kdy jej vyvolat, a ThunderPhone odešle ze svých serverů odchozí požadavek HTTP a vrátí odpověď agentovi. Dashboard pokrývá většinu potřeb pro nástroje i bez tohoto API: **Připojení → Aplikace** propojí Slack, HubSpot, Salesforce, Kalendář Google, Tabulky Google a Cal.com několika kliknutími OAuth; **Připojení → API** promění libovolné HTTP API v akci agenta (vložte příkaz cURL a průvodce AI připraví návrh nástroje včetně integrovaného Testu požadavku); a **Připojení → MCP** přidá servery MCP. Viz [Připojení](/cs/guides/concepts). Tento průvodce popisuje přímé API, na kterém rozhraní API stojí. Tento průvodce vás provede vytvořením nástroje pro vyhledávání počasí od začátku do konce. ## Anatomie nástroje Dvě části: 1. **Schéma** — definice funkce ve stylu OpenAI (`{type: "function", function: {name, description, parameters}}`), která LLM říká, 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 vybranými LLM v těle. ## 1. Zvolte editor Otevřete **Připojení → API**, vytvořte nebo upravte připojení API, přepněte editor parametrů na **JSON** a přidejte tam definici. Vytvořte specifikaci pomocí `POST /v1/integrations` nebo ji aktualizujte pomocí `PATCH /v1/integrations/{id}`. Obě cesty vytvoří uloženou integraci. Po uložení integraci přiřaďte agentovi. API agentů nemá zapisovatelné vložené pole `tools`. Tento průvodce používá cestu API integrací. ## 2. Vytvořte integraci ```bash 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). Hodnoty hlaviček jsou pouze pro zápis: odpovědi uvádějí pouze názvy hlaviček a pozdější `PATCH` může odeslat hlavičku bez `value`, aby se zachovala uložená hodnota. Věnujte skutečnou pozornost `description` nástroje a každého parametru. LLM tyto řetězce používá za běhu k rozhodnutí, zda a jak nástroj zavolat. Vágní popisy → vágní volání nástrojů. ### U parametrů adresy uveďte `format: "email"` Parametr, který přijímá e-mailovou adresu, by to měl uvádět ve svém schématu: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` je více než jen nápověda. U vyřešeného e-mailového schématu ThunderPhone před voláním vašeho endpointu ořízne hodnotu, převede doménu na malá písmena, samostatná anglická slova `at`, `dot`, `underscore`, `dash` a `hyphen` převede na příslušné znaky a odstraní mezery přímo kolem `@`, `.`, `_` a `-`. Slova mají stejný význam bez ohledu na to, zda přepis již obsahuje doslovné `@`: `"john dot smith at gmail dot com"` se změní na `john.smith@gmail.com`. Jakékoli jiné vnitřní mezery jsou odmítnuty, nikoli potichu spojeny. Slova pro mluvené oddělovače jsou pouze v angličtině; neanglické nebo nerozpoznané varianty s mezerami jsou bezpečně odmítnuty. Platné internacionalizované domény a lokální části SMTPUTF8 jsou přijímány. Vstup v punycode zůstává punycode a vstup s doménou Unicode zůstává po normalizaci parserem v Unicode, takže vaše API obdrží běžnou reprezentaci zadanou volajícím. Pokud je výsledná hodnota neplatná, nástroj se **nezavolá**. Agent obdrží `invalid_email_argument`, které mu sdělí, aby s volajícím potvrdil pravopis a znovu odeslal doslovnou adresu. Vynechaný volitelný e-mail zůstává beze změny. `null`, prázdný řetězec nebo řetězec obsahující pouze mezery rovněž zůstávají beze změny, pokud je vlastnost volitelná nebo umožňuje hodnotu null; stejné hodnoty jsou odmítnuty u povinného e-mailu, který hodnotu null neumožňuje. Lokální odkazy na schéma, například `#/$defs/email` a `#/definitions/email`, spolu s `anyOf`, `oneOf` a `allOf`, jsou kontrolovány s limity pro cykly a hloubku. Nelokální nebo nevyřešitelný `$ref` představuje známé omezení vynucování a je předán beze změny, stejně jako volání, jehož snímek nástroje nemá použitelné schéma. Pokud potřebujete, aby se kontrola použila, zachovejte e-mailová schémata lokální. Parametry bez vynucovaného e-mailového formátu jsou předány přesně tak, jak je model vytvořil. Podporované formáty jsou `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` a `uuid`; v současnosti se normalizuje a vynucuje pouze `email`. ## 3. Otestujte endpoint v sandboxu Než integraci propojíte s agentem, odešlete podepsaný požadavek ze serverů ThunderPhone a ověřte připojení: ```bash 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 { "ok": true, "status": 200, "elapsed_ms": 187, "response_headers": { "content-type": "application/json" }, "response_preview": "{\"temperature_f\": 64, ...}" } ``` Tento test také posiluje ochrany ThunderPhone proti SSRF — požadavky na localhost nebo privátní rozsahy IP vracejí `400 code=url_not_allowed`. ## 4. Propojte integraci s agentem Při vytváření nebo aktualizaci agenta ji připojte pomocí `integration_ids`: ```bash 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 připojit více integrací. Prompt agenta na ně může odkazovat podle názvu — „použij `get_weather`, když se volající zeptá na podmínky“ — nebo je může nepřímo rozpoznat z popisů schématu. ## 5. Implementujte endpoint Když agent vyvolá nástroj, ThunderPhone odešle podepsaný požadavek POST na váš `endpoint_url`: ``` POST /weather HTTP/1.1 Host: api.example.com X-Api-Key: your-provider-key X-ThunderPhone-Signature-V2: t=,v1= X-ThunderPhone-Signature: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Váš server odpoví JSONem, který se předá zpět LLM: ```json {"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á z nezpracovaného těla požadavku pomocí stejného `secret` jako váš endpoint webhooku. **Ověřte jej** — endpointy nástrojů jsou přístupné 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ý proces Spusťte [relaci s mikrofonem](/api-reference/mic-sessions) proti agentovi a položte otázku, kterou váš nástroj zpracovává („Jaké je počasí v 94110?“). Přepis hovoru zobrazuje celý průběh: ```json { "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." } ] } ``` Můžete jej získat pomocí [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); nezpracovaný proud událostí (včetně časování jednotlivých záznamů a posunů zvuku) je na [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). V seznamech hovorů a analytických přehledech ThunderPhone nyní uvádí testovací hovory odděleně od skutečného provozu. Testy a simulace v Browser Talk mohou znovu použít skutečné telefonní číslo a mohou vypadat jako příchozí, ale nezapočítávají se do celkového počtu produkčních hovorů, hodnocení ani metrik problémů. ## Časté problémy LLM rozhoduje na základě 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žij `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ý váš záznam. Endpointy 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 pomocí 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 narušíte schéma nástroje, můžete se ručně vrátit zpět tím, že pomocí PATCH znovu nahrajete starší snímek. --- ## Další kroky CRUD, předávání, historie verzí. Úplná gramatika schématu JSON a kontrakt podepsaného koncového bodu. Použijte vzor podpisu webhooku na koncové body nástrojů. Prozkoumejte celý průběh volání nástroje.