Přeskočit na obsah

Vlastní API nástroje (HTTP)

Vlastní HTTP nástroj umožní agentovi volat libovolné REST API vaší firmy — nastavíte ho sami přímo v administraci, bez samostatného vývojového projektu. Typické použití: stav objednávky, založení ticketu, ověření zákazníka, zápis do CRM.

Pokud je vaše API složitější (autentizace přes více kroků, netypický formát odpovědi), ozvěte se svému Kanbu kontaktu — rádi vám s napojením pomůžeme.

Co nastavíte

V administraci u nástrojů zadáte:

  • Název — interní identifikátor nástroje (jedno slovo, např. objednavka_stav).
  • Popis — podle něj agent pozná, kdy má nástroj použít. Píšou se sem i pravidla typu „vyžaduje číslo objednávky“.
  • URL adresa a HTTP metoda — GET, POST, PUT, PATCH nebo DELETE. Do URL můžete vložit {parametr}, který se v cestě nahradí hodnotou z konverzace.
  • Parametry (cesta a query) — u každého nastavíte typ (text, číslo, celé číslo, ano/ne), zda ho doplní model podle konverzace, nebo má pevnou hodnotu, kterou zadáte jednou v administraci a agent ji nikdy nevidí (hodí se pro interní ID nebo klíče). U parametrů doplňovaných modelem můžete zadat i uzavřený výčet povolených hodnot.
  • Tělo požadavku (u POST/PUT/PATCH) — zadáte ukázkový JSON a slovní instrukce; model podle nich při volání vygeneruje celé tělo požadavku najednou.
  • Hlavičky (headers) — statické dvojice klíč/hodnota, například Authorization: Bearer <token>. Kanbu nemá samostatný výběr typu autentizace (bearer/API klíč/basic) — přidáte ji jako běžnou hlavičku. Hodnoty se ukládají šifrované a v administraci se po uložení znovu nezobrazí, jen jejich názvy.
  • Časový limit — 1 až 30 sekund, výchozí 10 s.
  • Mapování odpovědi (volitelné) — cesta k poli v odpovědi (např. data.items), pokud chcete agentovi předat jen jeho relevantní část místo celého JSON.
  • Přiřazení agentům — konkrétní výběr, nebo přepínač Dostupné pro všechny agenty.

Tlačítkem Test si spojení hned po nastavení ověříte. Po uložení je nástroj hned k dispozici v konverzaci přiřazených agentů.

Tip na dobrý popis

Pište, kdy nástroj použít a co vrací. Např.: „Použij, když zákazník chce vědět stav objednávky. Vyžaduje číslo objednávky. Vrací stav a předpokládané doručení.“

Bezpečnost a limity

  • Požadavky jsou chráněné proti volání na interní/privátní adresy a proti přesměrování na ně (SSRF ochrana) — kontrola běží na každém přesměrování, ne jen na zadané URL.
  • Odpověď je omezená na 1 MB, delší obsah se zkrátí.
  • Nástroj, který spadne (chyba autentizace, vypršení času, chybový stav odpovědi), nevyřadí celou konverzaci — agent chybu uvidí jako běžný výsledek nástroje, může to zkusit znovu nebo pokračovat jinak.

Časté otázky

  • Jak nástroj autentizuji?

    Přidejte autentizaci jako hlavičku (nejčastěji Authorization: Bearer <token>) nebo jako statický query parametr. Samostatný výběr typu autentizace Kanbu nemá — funguje to přes běžné hlavičky, jejichž hodnoty se ukládají šifrovaně.

  • Co se stane, když endpoint spadne nebo neodpoví?

    Konverzace neskončí. Agent dostane chybovou zprávu jako výsledek nástroje a může to zkusit znovu, použít jiný nástroj, nebo uživateli chybu poctivě vysvětlit.

  • Jak velká může být odpověď z API?

    Do 1 MB, delší odpověď se ořízne. Pokud API vrací velký JSON, zvažte pole Mapování odpovědi a předejte agentovi jen relevantní část.

  • Můžu jeden nástroj přiřadit víc agentům?

    Ano, buď vybere konkrétní agenty, nebo zapnete Dostupné pro všechny agenty.

  • Co když moje API potřebuje složitější autentizaci (víc kroků, OAuth)?

    Ozvěte se svému Kanbu kontaktu — vlastní HTTP nástroj počítá se statickou autentizací (hlavička nebo query parametr). Pro OAuth zvažte i MCP napojení, které OAuth podporuje nativně.

Související

Zpět na SkillsPokračovat na Úprava odpovědí