Přeskočit obsah

Vytvořte si vlastní addon

Všechno, co vidíte na stránce Addony, je služba, která platformě sdělila, co umí. Můžete si takovou napsat také — a připojit ji ke své instanci bez naší asistence.

Kdy se to vyplatí

Vlastní addon dává smysl tam, kde už nestačí běžná API integrace:

  • Váš systém, vaše pravidla. Logika zůstává ve vašem kódu — dotaz do ERP, skórovací model, cenotvorba — a návrhář flow dostane jeden čistý uzel místo pěti integračních kroků.
  • Znovupoužitelné stavební bloky. Stejný modul nasadíte na každou instanci, kterou provozujete, a aktualizujete ho centrálně.
  • Vlastní obrazovka s nastavením. Přihlašovací údaje, mapování nebo přepínače funkcí, které si nastaví zákazník sám, ve vámi navrženém UI vloženém do administrace instance.
  • Data, která nesmí opustit vaši infrastrukturu. Addon běží na vašich serverech, platforma ho jen volá.

Addon je obyčejná HTTP služba. Popíše se v manifestu a platforma ho volá v průběhu konverzace bota se zákazníkem.

Začněte od šablony

Startovací šablona je veřejná a pod licencí MIT:

github.com/Daktela/daktela-ai-addon-template

Je to funkční addon s ukázkovými moduly, ukázkovou integrací, dynamickým seznamem, volitelnou konfigurační stránkou, testy, Docker images a kompletní příručkou pro vývojáře ve složce docs/.

Sestavit ji lze dvěma způsoby:

basic full
Moduly, integrace, dynamické seznamy ✔ ✔
Vlastní konfigurační stránka (React) — ✔
Vyžaduje Node.js k sestavení ne ano

Začněte s basic, pokud zákazník nemá co nastavovat.

Naklonujte a spusťte — stačí Python 3.13+ a uv:

git clone https://github.com/Daktela/daktela-ai-addon-template.git
cd daktela-ai-addon-template
uv sync --all-extras
uv run uvicorn server.main:app --reload

Služba teď běží na http://localhost:8000 a na http://localhost:8000/manifest uvidíte, co nabízí.

Chcete to rovnou rozjet tak, jak se to nasazuje? docker compose -f docker/compose.yaml up --build addon sestaví a spustí full image na portu 8000, addon-basic totéž pro image jen s moduly na portu 8001. Smyčka úprava–restart je pomalejší než uvicorn --reload, ale je to přesně ta image, kterou pak nasadíte.

Warning

Při vývoji vám tunelovací služba (ngrok, Cloudflare Tunnel, Tailscale Funnel a podobné) zpřístupní lokální port na veřejné URL, aby se k němu vaše instance dostala. Jsou to ale výhradně vývojářské nástroje. Produkční addon musí běžet na serveru se stabilní veřejnou URL — instance ho volá při každé konverzaci, takže notebook za tunelem nepřipadá v úvahu. Obě Docker images jsou na to připravené, detaily najdete v docs/13-deployment.md v repozitáři.

Zaregistrujte addon do instance

Otevřete Addony a klikněte na Přidat addon.

Stránka Addony se zvýrazněným tlačítkem pro přidání vlastního addonu

Vyplňte základní URL addonu a případně autentizační hlavičku, kterou addon očekává. Klikněte na Otestovat — platforma si stáhne manifest a řekne vám, jestli se jí ho podařilo přečíst, takže to zjistíte ještě před uložením. Pak klikněte na Uložit.

Formulář pro přidání vlastního addonu s úspěšně načteným manifestem

Info

Na snímku je lokální adresa, protože vznikl při vývoji přes tunel. V produkci zadejte skutečnou veřejnou URL addonu.

Addon teď má na stránce Addony svou kartu. Klikněte na Aktivovat. Addon bez konfigurační stránky se aktivuje rovnou, addon s konfigurační stránkou obvykle vyžaduje nejdřív vyplnit nastavení.

Karta addonu se zvýrazněným tlačítkem Aktivovat

Kdykoli změníte manifest addonu — nový modul, nový vstup, nová verze — klikněte na Synchronizovat addony, aby se změna propsala.

Ověřte, že to funguje

Otevřete Dialogy, upravte flow a najděte své moduly ve výběru modulů, seskupené pod názvem, který jste uvedli v manifestu. Vložte jeden do flow, připojte výstupní porty a spusťte testovací konverzaci tlačítkem Test v horní liště.

Pak otevřete interakci v Diskusích a podívejte se na její eventy. Každé spuštění modulu tam zapíše event se zdrojem ve tvaru <modul>::<kód addonu>, se zprávou, kterou modul vrátil, a s dobou trvání — právě podle toho poznáte rozdíl mezi „addon se vůbec nezavolal" a „addon se zavolal a odpověděl tohle".

Panel s eventy interakce s eventem zapsaným modulem z addonu

Nechte addon napsat LLM

Šablona je navržená tak, abyste ji předali programovacímu asistentovi (Claude Code, Cursor, Copilot a podobně) spolu se svým zadáním. Nejdřív repozitář naklonujte, otevřete ho v asistentovi a použijte prompty v tomto duchu.

1 — Připravte kostru addonu pro vaši doménu

Naklonoval jsem šablonu addonu pro Daktela AI. Přečti si README.md a docs/01-quickstart.md, abys pochopil strukturu projektu, a pak ho uprav pro naši firmu.

Addon se jmenuje <název> a pracuje s <systém, který integrujete — např. naším skladovým systémem>. Nastav identitu addonu v server/identity.py (code, name, description, author, ikona, barva).

Odstraň ukázkové moduly, které nepotřebuji, a udrž projekt spustitelný a testy zelené. Popiš, co jsi změnil a jak službu nastartovat.

2 — Přidejte modul, který volá vaše API

Podle vzoru v server/modules/catalog/exchange_rate.py a návodu v docs/07-calling-external-apis.md přidej nový modul <název modulu>.

Má volat GET https://api.example.com/orders/{order_id} s bearer tokenem, kde order_id je vstupní atribut, který vyplní návrhář flow.

Dej mu tři výstupní porty — úspěch, nenalezeno a chyba — plus atribut timeout napojený na timeout port. Stav objednávky zapiš do kontextu konverzace, aby s ním mohl pracovat další uzel, a zapiš debug event se surovou odpovědí. Doplň unit testy ve stejném stylu jako ty stávající.

3 — Přidejte stránku s nastavením pro přihlašovací údaje

Přepni tento addon na profil full a přidej konfigurační stránku, kde operátor zadá základní URL API a API token — podle docs/10-configuration-page.md a docs/11-persistence.md.

Hodnoty ulož přes stávající settings store, čti je v mých modulech místo napevno zadaných konstant a zajisti, aby se addon hlásil jako nenakonfigurovaný, dokud nejsou obě hodnoty vyplněné.

4 — Připravte addon do produkce

Projdi tento addon proti docs/13-deployment.md. Sestav obě Docker images, zkontroluj, že se do buildu nedostal žádný secret, a řekni mi, co ještě musím udělat, než tohle pustím na veřejné URL pro zákazníka.

Tip

Odkazujte asistenta na příručku přímo v šabloně, místo abyste mu platformu popisovali. Složka docs/ v repozitáři pokrývá moduly, výstupní porty, integrace, dynamické seznamy, streamované odpovědi, persistenci, testování i nasazení — a právě ona udrží vygenerovaný kód na správné koleji.

Čtěte dále