Skip to main content
Dovednosti a agenti jsou aktuálně v alfa fázi. Funkce funguje, ale stále se vyvíjí.
Aplikace mohou definovat schopnosti AI, které fungují přímo v pracovním prostoru — znovupoužitelné pokyny pro dovednosti a agenty s vlastními systémovými prompty.
Dovednosti definují znovupoužitelné pokyny a schopnosti, které mohou agenti AI používat ve vašem pracovním prostoru. K definování dovedností s vestavěnou validací použijte defineSkill():
src/skills/example-skill.ts
Hlavní body:
  • name je jedinečný identifikátor dovednosti (doporučuje se kebab-case).
  • label je uživatelsky čitelný název zobrazovaný v UI.
  • content obsahuje pokyny dovednosti — je to text, který agent AI používá.
  • icon (volitelné) nastavuje ikonu zobrazovanou v UI.
  • description (volitelné) poskytuje doplňující kontext o účelu dovednosti.
Agenti jsou asistenti AI, kteří běží ve vašem pracovním prostoru. K vytvoření agentů s vlastním systémovým promptem použijte defineAgent():
src/agents/example-agent.ts
Hlavní body:
  • name je jedinečný identifikátor agenta (doporučuje se kebab-case).
  • label je zobrazovaný název v UI.
  • prompt je systémový prompt, který definuje chování agenta.
  • description (volitelné) poskytuje kontext o tom, co agent dělá.
  • icon (volitelné) nastavuje ikonu zobrazovanou v UI.
  • modelId (volitelné) přepíše výchozí model AI používaný agentem.
  • responseFormat (volitelně) určuje tvar výstupu agenta. Výchozí hodnota je { type: 'text' } pro volný text. Použijte { type: 'json', schema } k vynucení strukturovaného výstupu ve formátu JSON.
Ve výchozím nastavení agent vrací volný text. Chcete-li získat strukturovaný výstup, nastavte responseFormat na { type: 'json' } a poskytněte schema:
src/agents/structured-agent.ts
Poznámky ke schématu:
  • Schéma je plochý objekt: type každé vlastnosti musí být primitivní typ (string, number nebo boolean). Vnořené objekty a pole nejsou podporovány.
  • description (volitelně) u každé vlastnosti navádí model, co má na toto místo doplnit.
  • required (volitelně) vypisuje vlastnosti, které musí model vždy vrátit.
  • additionalProperties: false (volitelně) zakáže jakoukoli vlastnost, která není deklarována v properties.
runAgent() umožňuje logické funkci spustit jednoho z agentů vaší aplikace (s jeho dovednostmi a nástroji). Identifikujte agenta pomocí universalIdentifier, který jste předali do defineAgent(). Předejte buď řetězec prompt, nebo historii konverzace messages, ale ne obojí zároveň:
src/logic-functions/run-enricher.ts
U vícekrokových botů (Slack, Discord, Teams, …) předejte historii vlákna jako messages místo jednoho prompt:
src/logic-functions/reply-in-thread.ts
Hlavní body:
  • Zadejte přesně jednu z možností: prompt (řetězec) nebo messages (1 až 100 položek { role: 'user' | 'assistant', content: string }).
  • Agent běží synchronně a může sám číst/aktualizovat záznamy pomocí vlastních nástrojů — runAgent() vrátí výsledek až po dokončení běhu.
  • Aplikace může spouštět pouze své vlastní agenty.
  • Výchozí role aplikace musí udělovat příznak oprávnění AI — přidejte SystemPermissionFlag.AI do permissionFlagUniversalIdentifiers (nebo nastavte canAccessAllTools: true). Bez něj runAgent() selže s chybou oprávnění.
  • Nastavte u logické funkce velkorysou hodnotu timeoutSeconds — běh agenta může trvat několik sekund.
  • success je true a result není null po dokončení běhu; při chybě je success false, result je null a error obsahuje důvod (například když během běhu workspace vyčerpal AI kredity).
src/roles/default-role.ts
Vyhněte se smyčkám: pokud voláte runAgent() z databázového triggeru *.updated a agent aktualizuje stejný záznam, omezte trigger pomocí updatedFields na pole, do kterého agent nikdy nezapisuje (např. zdrojovou URL), nebo před voláním runAgent() zkontrolujte, zda je některé cílové pole stále prázdné.

Spuštění jménem člena pracovního prostoru

Předejte runAsWorkspaceMemberId, když je spuštění vyvoláno osobou — například chatbotem odpovídajícím na zprávu — aby agent jednal jako tento člen, nikoli jako aplikace:
src/logic-functions/answer-question.ts
Spuštění pak jedná s vlastní rolí člena: může dělat vše, co může tento člen a nic navíc, záznamy, které vytváří, jsou mu připsány a uplatňují se na něj jeho oprávnění na úrovni řádků. Role agenta se toho neúčastní — je výchozí rolí aplikace pro spuštění, za nimiž nestojí žádný uživatel. Toto pole vynechejte u autonomních spuštění (plánované úlohy, spouštěče databázových událostí): ta si ponechají vlastní roli agenta. Aplikace, která jedná, zůstává kvůli doložení původu navázaná na kontext spuštění, aniž by zužovala oprávnění člena.Vaše aplikace je zodpovědná za mapování osoby, která spuštění vyvolala, na člena pracovního prostoru. Pojmenování člena vyžaduje přístupový token aplikace a to, koho může token pojmenovat, závisí na tom, zda je navázán na uživatele:
  • Token, který nemá přiřazeného žádného uživatele, může pojmenovat libovolného člena. Logická funkce běží s takovým tokenem a totéž platí pro tokeny vytvořené prostřednictvím client_credentials nebo z klíče API.
  • Token vydaný jménem uživatele, jaký obdrží front-endová komponenta, smí pojmenovat pouze člena daného uživatele.
Cokoli jiného — běžná uživatelská relace, API klíč bez tokenu aplikace — vůbec nesmí pojmenovat žádného člena.
runAgent() vyvolá výjimku, pokud nelze člena pracovního prostoru určit — neznámý nebo odebraný člen, případně člen bez role. Nikdy se nevrací zpět k vlastní roli agenta, protože to by udělilo více oprávnění, než o která volající požádal.