REST API

REST API je typ připojení v Siesta AI, který umožňuje chatbotům a agentům komunikovat s externími HTTP službami. V rámci jednoho REST API připojení můžete definovat vlastní nástroje, které mapují konkrétní funkce na externí API endpointy.

1. Přidání nového REST API připojení

1. Otevřete sekci Připojení.
2. Klikněte na Add Connection.
3. V dialogu vyberte dlaždici REST API.

2. Základní konfigurace připojení

Po výběru REST API vyplňte:

• Name: popisný název připojení v Siesta AI, například Lamael Timesheet Validation.
• Base URL: kořenová adresa externího API, například https://api.example.com/v1.
• Visibility / Access Policy: určuje, kteří uživatelé, role nebo skupiny mohou připojení používat nebo upravovat.
• Private = připojení je viditelné pouze pro vás.
• Shared = připojení může používat více uživatelů v organizaci.

Tato stránka popisuje odchozí integraci: Siesta AI volá externí HTTP API. Pokud chcete, aby váš vlastní systém volal Siesta AI, použijte External API.

3. Funkce jako nástroje

V části Functions definujete konkrétní volání API. Každá funkce se pro agenta chová jako samostatný nástroj, který může během konverzace vyvolat.

• Add function přidá další endpoint.
• Function name: interní identifikátor funkce pro použití v agentech nebo workflow.
• Description: důležitý popis pro AI agenta. Vysvětluje, co funkce dělá a kdy ji použít.
• HTTP Method: metoda volání, například GET, POST, PUT nebo PATCH.
• Endpoint: cesta endpointu, která se připojí k Base URL. Může obsahovat path template parametry ve dvojitých složených závorkách, například /orders/{{orderId}}.

Prakticky to znamená, že:

• Base URL: https://api.example.com
• Endpoint: /orders
• výsledné volání: https://api.example.com/orders

4. Parametry funkce

V části Parameters můžete pro každou funkci přidat více parametrů přes Add parameter. Tyto parametry určují, jaké hodnoty musí nebo může agent předat při volání nástroje.

Nastavitelné položky:

• Key: přesný název parametru.
• Description: vysvětlení účelu parametru pro AI agenta.
• Value type: datový typ hodnoty. Podporované typy zahrnují String, DateTime, StringArray, Bool, Int a Int64.
• Position: kam se parametr zapisuje v HTTP requestu.
• Required: zda je parametr povinný.
• Static value: volitelná pevná hodnota, která se posílá vždy, například API klíč v hlavičce.

Pozice parametru:

• Path: nahradí placeholder v URL. Pokud endpoint obsahuje dynamický segment, použijte dvojité složené závorky a definujte odpovídající parametr s Position = Path.
• Query: přidá hodnotu jako URL query parametr, například ?key=value.
• Body: přidá hodnotu do JSON payloadu requestu.
• Header: přidá hodnotu jako HTTP hlavičku. Hodí se pro autentizační tokeny nebo vlastní hlavičky.

Příklad path parametru:

• Endpoint: /orders/{{orderId}}
• Parameter: Key = orderId, Position = Path
• pokud agent předá orderId = 42, výsledné volání bude https://api.example.com/orders/42

5. Použití v agentech

Po vytvoření REST API připojení a jeho zpřístupnění chatbotovi nebo agentovi dostane jazykový model definice dostupných nástrojů. To zahrnuje názvy funkcí, jejich popisy a popisy parametrů.

Agent se podle těchto informací může rozhodnout, kdy funkci použít, jaké hodnoty doplnit a jestli má přes API načíst externí data nebo spustit akci v jiném systému.

6. Doporučení pro použití

• Používejte konzistentní pojmenování funkcí podle business akce (např. getOrders, createTicket).
• Popisy funkcí a parametrů pište tak, aby agent pochopil, kdy má nástroj použít a jaké hodnoty má dodat.
• Povinné parametry nastavujte jako Required = true, aby se předešlo nevalidním voláním.
• Citlivé hodnoty posílejte přes Static value v pozici Header, pokud je agent nemá znát nebo doplňovat ručně.
• U sdílených připojení (Shared) průběžně kontrolujte, kdo má k integraci přístup.

Shrnutí

REST API konektor je univerzální způsob, jak do Siesta AI připojit externí systémy přes HTTP endpointy. Umožňuje kombinovat více funkcí v jedné integraci a detailně řídit parametry každého volání.