Plány Standard & Pro
Přehled
Vlastní nástroje umožňují vašemu AI agentovi volat během konverzace vaše vlastní API koncové body a získávat živá data specifická pro daný požadavek — stav objednávky, sledování zásilky, dostupnost konkrétního SKU, údaje o účtu a další.
Asyntai vám nabízí tři způsoby, jak AI předávat živá nebo zákaznicky specifická data. Vlastní nástroje jsou správnou volbou, když se hodnota, kterou AI potřebuje, objeví až během konverzace:
- Datový kanál v reálném čase — načte jednu pevnou sadu dat (např. celý váš katalog produktů) do každé konverzace. Nejlepší pro sdílená data, která jsou stejná pro všechny návštěvníky.
- Kontext uživatele — váš web na začátku chatu předá data, která o aktuálním návštěvníkovi již zná (např. jméno přihlášeného zákazníka, jeho tarif nebo poslední objednávky). Nejlepší, když je návštěvník identifikován předem.
- Vlastní nástroje — AI volá váš koncový bod na vyžádání s hodnotami, které získá z chatu. Nejlepší, když hodnota není známá, dokud ji zákazník nenapíše — například číslo objednávky od anonymního návštěvníka.
Když se například zákazník zeptá „Kde je moje objednávka #10294?“, AI získá číslo objednávky, zavolá s ním váš koncový bod a odpoví na základě ověřené odpovědi. Kontext uživatele tento případ sám o sobě nepokryje, protože číslo objednávky není známé až do poloviny konverzace — a přesně sem se hodí Vlastní nástroje. (Mnoho obchodů používá Kontext uživatele pro přihlášené návštěvníky a zároveň Vlastní nástroj pro příležitostná vyhledávání.)
AI rozhoduje, kdy nástroj zavolat, na základě popisu, který napíšete. Vy rozhodujete, co nástroj dělá, tím, že jej nasměrujete na svůj koncový bod. Asyntai provede volání na straně serveru — nepíšete žádný kód a neprovozujete žádnou mezivrstvu.
Jak to funguje
- Definujete nástroj — název, popis, URL vašeho koncového bodu a parametry, které má AI odeslat.
- AI jej volá, když je to relevantní — když konverzace odpovídá vašemu popisu, AI nástroj zavolá s hodnotami, které získá ze zprávy zákazníka.
- Asyntai volá váš koncový bod — náš server provede HTTP požadavek na vaši URL a předá odpověď zpět AI.
- AI odpoví — pomocí ověřených dat, která váš koncový bod vrátil.
Žádný kód není potřeba: Stačí vám koncový bod, který už vaše data vrací. Vše ostatní nastavíte ve formuláři v nástěnce — není potřeba vytvářet žádný callback, webhook ani skript do prohlížeče.
Případy použití
Stav objednávky
Vyhledá objednávku podle čísla a vrátí její aktuální stav
Sledování zásilky
Vrátí nejnovější stav sledování pro dané sledovací číslo
Kontrola skladu
Vrátí aktuální dostupnost konkrétního produktu nebo SKU
Vyhledání účtu
Vrátí údaje o účtu nebo předplatném pro daný identifikátor
Nastavení
1
Otevřete Vlastní nástroje
Přejděte na /custom-tools/ a klikněte na Přidat nástroj
2
Popište nástroj
Zadejte mu název, jasný popis a URL vašeho koncového bodu
3
Definujte parametry
Přidejte vstupy, které má AI získat a odeslat (např. order_number)
4
Uložte & otestujte
Uložte a poté položte svému botovi odpovídající otázku, abyste viděli nástroj v akci
Pole
- Název — identifikátor funkce (písmena, číslice, podtržítka), např.
get_order_status. Tento název AI vidí.
- Popis — nejdůležitější pole. Říká AI, kdy nástroj zavolat. Buďte konkrétní: „Zavolej to vždy, když zákazník zmíní číslo objednávky. Nežádej o ověření.“
- URL koncového bodu — veřejná HTTPS URL, kterou Asyntai zavolá.
- HTTP metoda —
GET (jen pro čtení, doporučeno) nebo POST (může měnit data — viz Zabezpečení níže).
- Parametry — vstupy, které AI získá z konverzace a odešle. Každý má název, typ, popis a příznak povinnosti. U
GET se odesílají jako parametry dotazovacího řetězce; u POST jako tělo JSON.
- Autentizační hlavička (volitelné) — název hlavičky + hodnota odesílané při každém volání, např.
X-API-Key. Použijte ji, pokud váš koncový bod vyžaduje klíč.
Parametry jsou nutné k tomu, aby AI mohla předat jakoukoli hodnotu. Pokud váš koncový bod potřebuje vstup (například číslo objednávky), musíte pro něj přidat parametr — bez něj AI nemá kam hodnotu vložit a zavolá koncový bod prázdný. Záleží na dvou věcech:
- Název parametru musí přesně odpovídat tomu, co váš koncový bod očekává. Parametr s názvem
order_number se odešle jako ?order_number=... (GET) nebo {"order_number": "..."} (POST). Pokud váš koncový bod čte id, pojmenujte parametr id.
- Hodnotu nikdy nezadáváte sami — pouze deklarujete parametr. AI ji doplní v okamžiku volání z toho, co zákazník napsal.
Praktický příklad: vyhledání stavu objednávky
Předpokládejme, že váš obchod poskytuje tento koncový bod:
GET https://yourstore.com/api/order-status?order_number=10294
…který vrací JSON jako:
{
"found": true,
"status": "Accepted, preparing for shipment",
"carrier": "DHL",
"customer_message": "Your order has been accepted and is being prepared for shipment."
}
Nástroj byste nakonfigurovali takto:
- Název:
get_order_status
- Popis: „Vyhledej stav zákaznické objednávky. Zavolej to okamžitě vždy, když zákazník uvede číslo objednávky — nežádej o další ověření. Ve své odpovědi použij vrácené customer_message.“
- URL koncového bodu:
https://yourstore.com/api/order-status
- Metoda:
GET
- Parametr:
order_number (string, povinný) — „Číslo objednávky zákazníka, obvykle 8+ číslic.“
Když zákazník napíše „Jak je na tom moje objednávka #10294?“, AI zavolá get_order_status(order_number=10294), Asyntai pošle požadavek na vaši URL s ?order_number=10294 a AI odpoví na základě odpovědi.
Tip: AI odesílá hodnoty, o kterých sama rozhodne — nikdy je nevyplňujete předem. Udržujte názvy a popisy parametrů jasné, aby model přesně věděl, co má získat.
Co váš koncový bod přijímá a co by měl vracet
- Požadavek:
GET s vašimi parametry v dotazovacím řetězci nebo POST s tělem JSON. Případná autentizační hlavička, kterou jste nastavili, je součástí.
- Odpověď: vraťte JSON (preferováno) nebo prostý text. Asyntai předá tělo zpět AI. Dobře funguje pole, které může AI přímo citovat — jako
customer_message.
- Nenalezeno / chyby: vraťte srozumitelnou odpověď (například objekt JSON s
found: false a customer_message), aby AI mohla odpovědět pravdivě, místo aby hádala.
Testování vašeho nástroje
Každý nástroj má na konfigurační stránce vestavěný panel Otestovat tento nástroj, takže si můžete ověřit, že funguje, dříve než jej použije jakýkoli zákazník — a aniž byste museli posílat zprávu přes bota.
- Zadejte ukázkové hodnoty pro parametry nástroje (např. skutečné číslo objednávky).
- Klikněte na Spustit test. Asyntai zavolá váš koncový bod přesně tak, jak by to udělala AI — stejný dotazovací řetězec nebo tělo JSON, stejná autentizační hlavička, stejný 5sekundový časový limit a bezpečnostní kontroly.
- Výsledek uvidíte okamžitě: odznak úspěchu/selhání, HTTP stav, dobu odezvy, přesnou URL, kterou jsme volali, a nezpracovanou odpověď vašeho koncového bodu (přehledně naformátovanou, pokud jde o JSON).
Funguje to i na neuložených úpravách, takže můžete upravit URL, parametry nebo autentizační hlavičku a opakovaně testovat, dokud nevrátí to, co očekáváte.
Poznámka: Testování nástroje typu POST skutečně zavolá váš koncový bod a může změnit data — testovací panel vás před spuštěním upozorní. U nástrojů GET jen pro čtení se není čeho obávat.
Zabezpečení — přečtěte si toto
Hranicí zabezpečení je váš koncový bod, nikoli AI. Chatovací widget je veřejný a návštěvník může AI zmanipulovat tak, aby zavolala nástroj s libovolnými hodnotami. To platí pro každý systém volání nástrojů pomocí AI. Navrhněte svůj koncový bod odpovídajícím způsobem:
- Preferujte GET / jen pro čtení. Vyhledávání (stav objednávky, sklad, sledování) lze bezpečně zpřístupnit. Z tohoto důvodu je GET výchozí volbou.
- POST vyžaduje potvrzení. Protože POST může měnit data, lze nástroj typu POST uložit až poté, co zaškrtnete políčko potvrzující, že nesete výhradní odpovědnost za zabezpečení a autorizaci požadavků na svém vlastním koncovém bodě. Nikdy nepřipojujte vracení peněz, storna, změny hesel ani pohyby peněz, pokud váš koncový bod požadavek nezávisle neověřuje.
- Chraňte se proti enumeraci. Pokud je vyhledávací klíč uhodnutelný (jako sekvenční čísla objednávek), vyžadujte druhý faktor — např. číslo objednávky a zároveň e-mail uvedený u objednávky a ověřte, že se shodují — aby návštěvník nemohl číst data jiných zákazníků zkoušením čísel.
- Nikdy nedůvěřujte argumentům AI. Ověřte a autorizujte každý požadavek na straně serveru, jako by pocházel od anonymního útočníka — protože tomu tak v podstatě může být.
Ověřování živých volání
Jakmile je váš nástroj v provozu, každé skutečné volání z konverzace se zaznamená. U každého volání zaznamenáváme název nástroje, argumenty, které AI odeslala, přesnou URL, na kterou jsme poslali požadavek, HTTP stav, odpověď a dobu trvání. Díky tomu si můžete potvrdit, že se nástroj v reálném chatu spustil, a vidět, co váš koncový bod vrátil, aniž byste se museli prohrabávat vlastními serverovými logy. (Panel Otestovat tento nástroj výše slouží k tomu, abyste si nastavení zkontrolovali sami; tento log zachycuje, co se děje během skutečných konverzací se zákazníky.)
Limity & ochranná opatření
- Až 10 nástrojů na jeden web.
- 5sekundový časový limit na volání; odpovědi jsou omezeny na 10 KB.
- Koncové body musí být veřejné
http(s) URL. Soukromé, smyčkové (loopback) a vnitrosíťové adresy jsou blokovány.
- Dostupné v plánech Standard a Pro.
- Účtování: každé volání nástroje se počítá jako jedna zpráva navíc ve vašem tarifu. Běžná odpověď využije 1 zprávu; odpověď, při které AI zavolá nástroj, využije 2 (odpověď plus volání nástroje), protože volání nástroje vyžaduje další požadavek na AI.
- Pokud volání nástroje selže (časový limit, chyba, blokování), AI je o tom informována a odpoví s rozvahou — konverzaci to nezhroutí.