Přeskočit na hlavní obsah

Externí API

Externí API umožňuje externím systémům volat Siesta AI přímo. Je určeno pro zákaznické aplikace, interní portály, automatizační backendy a integrační služby, které potřebují vytvářet agenty, volat agenta, nahrávat soubory, spravovat úkoly, seznam dostupných připojení nebo číst auditní data.

Tato stránka popisuje API z pohledu produktu a integrace. Pro kompletní referenci koncových bodů čitelnou pro stroj použijte dokumentaci API, kterou poskytuje aplikace Siesta AI.

Externí API se liší od Rest API připojení. Rest API připojení umožňuje Siesta AI volat jiné HTTP API. Externí API umožňuje jinému systému volat Siesta AI.

Reference koncových bodů​

Použijte referenci externího API k procházení všech koncových bodů ze specifikace OpenAPI, kontrole parametrů a schémat a kopírování ukázkových požadavků se zástupnými autentizačními hlavičkami.

Typické případy použití​

  • Vložit agenta Siesta AI do interní aplikace nebo zákaznického portálu.
  • Odeslat otázku uživatele agentovi a uložit vrácené conversationId.
  • Nahrát dočasný soubor a poslat ho agentovi jako kontext.
  • Vytvářet nebo aktualizovat úkoly z CRM, systému pro správu tiketů nebo pracovního enginu.
  • Spustit realtimovou hlasovou nebo streamovací relaci s agentem.
  • Exportovat záznamy auditního protokolu pro dodržování předpisů nebo provozní monitoring.
  • Seznam dostupných pracovních prostorů úkolů, kolekcí datových zdrojů nebo připojení před vytvořením integračního toku.

Autentizace​

Volání externího API jsou autentizována pomocí klíče API organizace.

Požadované hlavičky:

X-Api-Key: <api-key>
X-Org-Id: <organization-id>

Klíče API jsou spravovány v Organizace -> Klíče API. Zacházejte s klíči API jako s tajemstvími backendu. Neodhalujte je v kódu určeném pouze pro prohlížeč, veřejných mobilních klientech nebo widgetech na straně klienta, kde mohou uživatelé zkoumat síťový provoz.

Doporučené postupy:

  • Používejte samostatný klíč API pro každou integraci.
  • Používejte různé klíče pro vývoj, staging a produkci.
  • Pravidelně otáčejte klíče a okamžitě po podezření na únik.
  • Odstraňte klíče, které již nejsou používány.
  • Zkontrolujte auditní protokol po provedení změn v produkčních integracích.

Základy API​

Aktuální základní cesta externího API je:

/api/v1

Většina koncových bodů používá JSON těla požadavků a odpovědí. Koncové body pro nahrávání a stahování souborů používají souborové payloady. Realtime komunikace používá požadavek na vytvoření relace následovaný připojením WebSocket.

Běžné konvence:

  • Identifikátory zdrojů jsou hodnoty GUID.
  • Seznamové koncové body podporují parametry stránkování, jako jsou offset a limit, kde je to možné.
  • Některé seznamové koncové body také podporují search, třídění a doménově specifické filtry.
  • Přístup je omezen na organizaci spojenou s klíčem API.
  • Chování agenta stále závisí na konfiguraci agenta, připojení modelu, kolekcích dat, nástrojích, nastaveních zabezpečení organizace a pravidlech správy připojení.

Agenti​

Agenti jsou hlavním vstupním bodem pro integraci poháněnou AI.

Seznam agentů​

GET /api/v1/Agent

Použijte tento koncový bod k seznamu agentů dostupných pro integraci. Odpověď zahrnuje pole jako ID agenta, název, datum vytvoření, veřejný stav, ikonu, barvu ikony a název modelu.

Použijte to, když externí aplikace umožňuje uživatelům vybrat agenta nebo když integrace potřebuje ověřit, že nakonfigurovaný agent stále existuje.

Vytvořit agenta​

POST /api/v1/Agent

Vytváří nového agenta z externího systému.

Požadavek na vytvoření může definovat konfiguraci agenta relevantní k produktu, jako jsou:

  • název a popis,
  • systémová zpráva a počáteční zpráva,
  • název modelu a parametry modelu,
  • úsilí o uvažování,
  • kolekce datových zdrojů,
  • sdílené a soukromé nástroje,
  • sub-agenti,
  • veřejné chatové a widgetové nastavení,
  • nastavení zpětné vazby a nahrávání souborů.

Použijte tento koncový bod, když externí administrativní tok nebo proces provisioning potřebuje programově vytvářet agenty.

Odpověď na vytvoření agenta​

POST /api/v1/Agent/{agentId}/response

Vytváří novou konverzaci se zvoleným agentem, odesílá vstupní zprávu a vrací výstup agenta spolu s conversationId.

Příklad požadavku:

{
  "input": "Shrňte nahraný dokument a vyjmenujte hlavní rizika.",
  "fileIds": ["1f4c0e12-4d16-4d7a-bc41-72a69f51d1d2"]
}

Příklad odpovědi:

{
  "output": "Dokument popisuje...",
  "conversationId": "9a53f66d-18f3-42ec-a5ef-920e55f6dcb4"
}

Použijte fileIds pouze pro soubory, které byly nahrány prostřednictvím koncového bodu pro soubory externího API.

Realtime relace agentů​

Realtime relace se používají pro interaktivní nebo hlasově orientované zážitky, kde klient komunikuje s agentem prostřednictvím připojení WebSocket.

Pro celý životní cyklus produktu, veřejné/interní rozlišení, limity relací a očekávání bezpečnosti viz Realtime a hlasové konverzace.

Vytvořit realtime relaci​

POST /api/v1/Agent/{agentId}/realtime-session

Vytváří realtime relaci pro agenta. Požadavek může buď znovu použít existující conversationId, nebo nechat API automaticky vytvořit novou konverzaci.

Odpověď zahrnuje:

  • sessionId,
  • conversationId,
  • expiresAt,
  • cesta WebSocket,
  • podporované formáty audio vstupu a výstupu,
  • maximální délka relace,
  • časový limit nečinnosti,
  • název modelu poskytovatele.

Připojit se k realtime WebSocket​

GET /api/v1/Agent/{agentId}/realtime

Tento koncový bod očekává požadavek WebSocket. Klient předává realtime conversationId a sessionId jako parametry dotazu.

Důležité chování:

  • Realtime relace je vázána na konkrétního agenta a konverzaci.
  • Klient by se měl znovu připojit vytvořením nové relace, když předchozí relace vyprší.
  • Klient musí respektovat podporované audio formáty vrácené koncovým bodem pro vytvoření relace.
  • Časový limit nečinnosti a maximální délka relace jsou vynucovány platformou.

Soubory​

API pro soubory zpracovává dočasné soubory používané jako kontext pro požadavky agentů.

Nahrát soubor​

POST /api/v1/File

Nahrává dočasný soubor a vrací:

  • ID souboru,
  • název souboru,
  • MIME typ.

Aktuální limit nahrávání je 200 MB.

Stáhnout soubor​

GET /api/v1/File/{id}

Stahuje dříve nahraný dočasný soubor.

Nahrané soubory mohou být předány do POST /api/v1/Agent/{agentId}/response pomocí fileIds. Nahrání souboru prostřednictvím tohoto API automaticky nepřidává soubor do dlouhodobé znalostní báze. Použijte kolekce datových zdrojů pro trvalé řízení znalostí.

Kolekce datových zdrojů​

Kolekce datových zdrojů jsou dlouhodobé kontejnery znalostí, které mohou být připojeny k agentům.

Dostupné operace:

GET /api/v1/DataSourceCollection
GET /api/v1/DataSourceCollection/{id}
POST /api/v1/DataSourceCollection
PUT /api/v1/DataSourceCollection/{id}

Použijte kolekce datových zdrojů, když externí systém potřebuje připravit nebo spravovat kontejnery znalostí před jejich přiřazením agentům. Kolekce datových zdrojů může být později použita v konfiguraci agenta s nastaveními, jako jsou maximální kusy a prahová hodnota relevance.

Připojení​

GET /api/v1/Connection

Koncový bod Připojení seznamuje připojení dostupná v organizaci. Může být filtrován podle vyhledávání, rozsahu a typu připojení.

Odpověď zahrnuje:

  • ID připojení,
  • název připojení,
  • typ připojení,
  • datum vytvoření,
  • výchozí stav,
  • režim přístupu.

Použijte tento koncový bod, když integrace potřebuje zjistit, která připojení modelu, nástroje nebo připojení k externím systémům jsou dostupná před vytvořením nebo konfigurací agentů.

Dostupnost připojení je ovlivněna politikou organizace. Pokud je typ připojení nebo funkce zakázána nastavením správy, agenti a pracovní toky by neměli předpokládat, že mohou být použity.

Úkoly​

API pro úkoly umožňuje externím systémům vytvářet a spravovat pracovní položky v Siesta AI.

Dostupné operace:

GET /api/v1/Task
GET /api/v1/Task/{id}
POST /api/v1/Task
PUT /api/v1/Task/{id}

Úkoly mohou zahrnovat:

  • pracovní prostor,
  • shrnutí,
  • stav,
  • výzvu,
  • přiděleného agenta,
  • zdrojového agenta,
  • zdrojovou konverzaci,
  • ikonu.

Typické scénáře:

  • CRM vytváří úkol pro agenta AI po události se zákazníkem.
  • Systém pro správu tiketů posílá nevyřešený případ do Siesta AI k shrnutí nebo návrhu dalšího kroku.
  • Pracovní engine aktualizuje stav úkolu po externím schválení.

Chování provádění úkolů a přezkoumání úkolů závisí na vybraném pracovním prostoru, přiděleném agentovi a konfiguraci aplikace.

Pracovní prostory​

GET /api/v1/Workspace

API pro pracovní prostory seznamuje pracovní prostory úkolů. Pracovní prostor sdružuje související úkoly a může definovat výchozího agenta.

Odpověď zahrnuje:

  • ID pracovního prostoru,
  • název,
  • ID a název výchozího agenta,
  • ikonu výchozího agenta a barvu ikony,
  • nastavení automatického provádění,
  • datum vytvoření.

Použijte tento koncový bod před vytvořením úkolů, aby integrace mohla umístit práci do správného pracovního prostoru.

Auditní protokol​

API auditního protokolu podporuje dodržování předpisů, monitoring a přezkum incidentů.

Dostupné operace:

GET /api/v1/AuditLog
GET /api/v1/AuditLog/{id}

Seznamový koncový bod podporuje filtry, jako jsou časové intervaly, typ změny, uživatel a typ entity. Záznamy auditu zahrnují informace, jako jsou ID korelace, čas vytvoření, uživatel, typ entity a typ změny. Detailní koncový bod zahrnuje změněné vlastnosti se starými a novými hodnotami.

Dostupnost auditního protokolu je ovlivněna nastavením uchovávání auditního protokolu organizace.

Zpracování chyb​

Externí klienti by měli zpracovávat tyto běžné kategorie odpovědí:

  • 400 Bad Request - neplatný vstup, nepodporovaná kombinace parametrů nebo nesprávný payload.
  • 401 Unauthorized - chybějící nebo neplatná autentizace.
  • 403 Forbidden - autentizovaný volající nemá přístup k požadované operaci.
  • 404 Not Found - zdroj neexistuje nebo není dostupný v aktuální organizaci.
  • 429 Too Many Requests - používání je omezeno rychlostí, kvótou nebo kontrolami rozpočtu tokenů, pokud jsou nakonfigurovány.
  • 500 Internal Server Error - neočekávané selhání na straně serveru.

Pro dlouhotrvající nebo uživatelsky orientované integrace zobrazte jasnou záložní zprávu a uchovejte dostatečný místní kontext pro bezpečné opakování.

Zabezpečení a správa​

Integrace externího API by měly dodržovat stejné očekávání správy jako interní používání Siesta AI.

Doporučené kontroly:

  • Uchovávejte klíče API na důvěryhodném backendu.
  • Omezte každou integraci na minimální potřebný pracovní tok.
  • Preferujte samostatné agenty pro různé integrační kontexty.
  • Používejte správu připojení pro nástroje, které mohou číst citlivá data nebo měnit externí systémy.
  • Používejte schválení pro akce, které mění obchodní data.
  • Aktivujte nastavení bezpečnosti obsahu a ochrany výzev pro veřejné nebo zákaznické integrace.
  • Monitorujte používání agentů, provádění nástrojů a auditní protokoly po nasazení.
  • Zkontrolujte limity tokenů a kontrolu nákladů před povolením automatizace s vysokým objemem.

Související stránky​