Skip to main content
Abilitățile și agenții sunt în prezent în stadiu alfa. Caracteristica funcționează, dar este încă în dezvoltare.
Aplicațiile pot defini capabilități AI care există în interiorul spațiului de lucru — instrucțiuni reutilizabile pentru abilități și agenți cu prompturi de sistem personalizate.
Abilitățile definesc instrucțiuni și capabilități reutilizabile pe care agenții AI le pot folosi în spațiul dvs. de lucru. Folosiți defineSkill() pentru a defini abilități cu validare încorporată:
src/skills/example-skill.ts
Puncte cheie:
  • name este un șir identificator unic pentru abilitate (se recomandă kebab-case).
  • label este numele lizibil afișat în interfața cu utilizatorul (UI).
  • content conține instrucțiunile abilității — acesta este textul pe care agentul AI îl folosește.
  • icon (opțional) setează pictograma afișată în UI.
  • description (opțional) oferă context suplimentar despre scopul abilității.
Agenții sunt asistenți AI care există în interiorul spațiului dvs. de lucru. Utilizați defineAgent() pentru a crea agenți cu un prompt de sistem personalizat:
src/agents/example-agent.ts
Puncte cheie:
  • name este un șir identificator unic pentru agent (se recomandă kebab-case).
  • label este numele de afișare din interfața cu utilizatorul (UI).
  • prompt conține promptul de sistem — acesta este textul de instrucțiuni care definește comportamentul agentului.
  • description (opțional) oferă context despre ce face agentul.
  • icon (opțional) setează pictograma afișată în UI.
  • modelId (opțional) suprascrie modelul AI implicit utilizat de agent.
  • responseFormat (opțional) controlează forma ieșirii agentului. Valoarea implicită este { type: 'text' } pentru text liber. Folosește { type: 'json', schema } pentru a impune ieșire JSON structurată.
În mod implicit, un agent returnează text liber. Pentru a obține o ieșire structurată, setează responseFormat la { type: 'json' } și furnizează schema:
src/agents/structured-agent.ts
Note despre schemă:
  • Schema este un obiect plat: type al fiecărei proprietăți trebuie să fie un tip primitiv (string, number sau boolean). Obiectele îmbricate și tablourile nu sunt acceptate.
  • description (opțional) pe fiecare proprietate ghidează modelul cu privire la ce să pună acolo.
  • required (opțional) enumeră proprietățile pe care modelul trebuie să le returneze întotdeauna.
  • additionalProperties: false (opțional) interzice orice proprietate care nu este declarată în properties.
runAgent() permite unei funcții logice să ruleze unul dintre agenții aplicației tale (cu abilitățile și instrumentele sale). Identifică agentul prin universalIdentifier pe care l-ai transmis către defineAgent(). Transmite fie un șir prompt, fie un istoric de conversație messages, nu ambele:
src/logic-functions/run-enricher.ts
Pentru boți multi-turn (Slack, Discord, Teams, …), transmite istoricul firului de discuție ca messages în loc de un singur prompt:
src/logic-functions/reply-in-thread.ts
Puncte cheie:
  • Furnizează exact unul dintre prompt (șir) sau messages (1 până la 100 de intrări de { role: 'user' | 'assistant', content: string }).
  • Agentul rulează sincron și poate citi/actualiza direct înregistrări prin propriile sale instrumente — runAgent() este rezolvat după ce rularea se încheie.
  • O aplicație poate rula doar propriii săi agenți.
  • Rolul implicit al aplicației trebuie să acorde indicatorul de permisiune AI — adaugă SystemPermissionFlag.AI la permissionFlagUniversalIdentifiers (sau setează canAccessAllTools: true). Fără acesta, runAgent() eșuează cu o eroare de permisiune.
  • Setează un timeoutSeconds generos pentru funcția logică — rulările agentului pot dura câteva secunde.
  • success este true și result este nenul când rularea se încheie; în caz de eșec success este false, result este null, iar error conține motivul (de exemplu, când spațiul de lucru rămâne fără credite AI în timpul rulării).
src/roles/default-role.ts
Evită buclele: dacă apelezi runAgent() dintr-un declanșator de tip eveniment de bază de date *.updated, iar agentul actualizează aceeași înregistrare, restrânge declanșatorul cu updatedFields la un câmp pe care agentul nu îl scrie niciodată (de exemplu, URL-ul sursă) sau verifică dacă vreun câmp țintă este încă gol înainte de a apela runAgent().

Rulare în numele unui membru al spațiului de lucru

Transmite runAsWorkspaceMemberId atunci când rularea este declanșată de o persoană — de exemplu, un chatbot care răspunde la un mesaj — astfel încât agentul să acționeze ca acel membru în loc să acționeze ca aplicația:
src/logic-functions/answer-question.ts
Rularea acționează apoi cu propriul rol al membrului: poate face orice poate face acel membru și nimic mai mult, înregistrările pe care le creează sunt atribuite lui, iar permisiunile lui la nivel de rând se aplică. Rolul agentului nu participă — este valoarea implicită a aplicației pentru rulările fără nicio persoană în spatele lor. Omite câmpul pentru rulările autonome (joburi programate, declanșatoare de evenimente din baza de date): acelea păstrează propriul rol al agentului. Aplicația care acționează rămâne atașată la contextul rulării pentru proveniență, fără a restrânge permisiunile membrului.Aplicația ta este responsabilă să facă asocierea dintre persoana care a declanșat rularea și un membru al spațiului de lucru. A denumi unul necesită un token de acces al aplicației, iar ceea ce poate denumi un token depinde dacă acesta are sau nu un utilizator asociat:
  • Un token fără niciun utilizator atașat poate denumi orice membru. O funcție logică rulează cu unul, la fel și tokenurile emise prin client_credentials sau dintr-o cheie API.
  • Un token emis în numele unui utilizator, așa cum primește un front component, poate denumi doar propriul membru al acelui utilizator.
Orice altceva — o sesiune simplă de utilizator, o cheie API fără un token al aplicației — nu poate denumi deloc un membru.
runAgent() aruncă o eroare atunci când membrul spațiului de lucru nu poate fi identificat — un membru necunoscut sau eliminat, ori unul fără niciun rol. Nu revine niciodată la propriul rol al agentului, deoarece acest lucru ar acorda mai mult acces decât a cerut apelantul.