Compétences et agents

defineSkill

Définir des compétences pour les agents IA

Les compétences définissent des instructions et des capacités réutilisables que les agents IA peuvent utiliser dans votre espace de travail. Utilisez defineSkill() pour définir des compétences avec validation intégrée :

src/skills/example-skill.ts

import { defineSkill } from 'twenty-sdk/define';

export default defineSkill({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'sales-outreach',
  label: 'Sales Outreach',
  description: 'Guides the AI agent through a structured sales outreach process',
  icon: 'IconBrain',
  content: `You are a sales outreach assistant. When reaching out to a prospect:
1. Research the company and recent news
2. Identify the prospect's role and likely pain points
3. Draft a personalized message referencing specific details
4. Keep the tone professional but conversational`,
});

Points clés :

name est une chaîne d’identification unique pour la compétence (kebab-case recommandé).
label est le nom d’affichage lisible par l’utilisateur dans l’UI.
content contient les instructions de la compétence — c’est le texte que l’agent IA utilise.
icon (optionnel) définit l’icône affichée dans l’UI.
description (optionnel) fournit un contexte supplémentaire sur l’objectif de la compétence.

defineAgent

Définir des agents d'IA avec des prompts personnalisés

Les agents sont des assistants IA qui vivent dans votre espace de travail. Utilisez defineAgent() pour créer des agents avec un prompt système personnalisé :

src/agents/example-agent.ts

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  name: 'sales-assistant',
  label: 'Sales Assistant',
  description: 'Helps the sales team draft outreach emails and research prospects',
  icon: 'IconRobot',
  prompt: 'You are a helpful sales assistant. Help users with their questions and tasks.',
});

Points clés :

name est un identifiant unique pour l’agent (kebab-case recommandé).
label est le nom d’affichage montré dans l’UI.
prompt est le prompt système qui définit le comportement de l’agent.
description (optionnel) fournit un contexte sur ce que fait l’agent.
icon (optionnel) définit l’icône affichée dans l’UI.
modelId (optionnel) remplace le modèle d’IA par défaut utilisé par l’agent.
responseFormat (facultatif) contrôle la forme de la sortie de l’agent. Par défaut, la valeur est { type: 'text' } pour le texte libre. Utilisez { type: 'json', schema } pour forcer une sortie JSON structurée.

Par défaut, un agent renvoie du texte libre. Pour obtenir une sortie structurée, définissez responseFormat sur { type: 'json' } et fournissez un schema :

src/agents/structured-agent.ts

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'c4d5e6f7-a8b9-0123-cdef-456789012345',
  name: 'lead-scorer',
  label: 'Lead Scorer',
  prompt: 'Score the lead and explain your reasoning.',
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
        summary: { type: 'string', description: 'Short reasoning for the score' },
      },
      required: ['score', 'summary'],
      additionalProperties: false,
    },
  },
});

Remarques sur le schéma :

Le schéma est un objet plat : le type de chaque propriété doit être un type primitif (string, number ou boolean). Les objets imbriqués et les tableaux ne sont pas pris en charge.
description (facultatif) sur chaque propriété guide le modèle sur ce qu’il doit y mettre.
required (facultatif) répertorie les propriétés que le modèle doit toujours renvoyer.
additionalProperties: false (facultatif) interdit toute propriété non déclarée dans properties.

runAgent

Exécuter un agent depuis une fonction logique

runAgent() permet à une fonction logique d’exécuter l’un des agents de votre application (avec ses compétences et ses outils). Identifiez l’agent à l’aide du universalIdentifier que vous avez passé à defineAgent(). Passez soit une chaîne de caractères prompt, soit un historique de conversation messages, mais pas les deux :

src/logic-functions/run-enricher.ts

import { runAgent } from 'twenty-sdk/logic-function';

const { result, error, success } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  prompt: 'Enrich House Ad <recordId>: fill empty fields from its listing URL.',
});

Pour les bots multi-tours (Slack, Discord, Teams, …), passez l’historique du fil de discussion en messages au lieu d’un seul prompt :

src/logic-functions/reply-in-thread.ts

import { runAgent } from 'twenty-sdk/logic-function';

const { result, error, success } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  messages: [
    { role: 'user', content: 'Who owns Acme?' },
    { role: 'assistant', content: 'Sarah owns the Acme account.' },
    { role: 'user', content: 'What was the last touchpoint?' },
  ],
});

Points clés :

Fournissez exactement l’un des deux : prompt (string) ou messages (1 à 100 entrées de { role: 'user' | 'assistant', content: string }).
L’agent s’exécute de manière synchrone et peut lire/mettre à jour lui-même des enregistrements via ses propres outils — runAgent() se résout une fois l’exécution terminée.
Une application ne peut exécuter que ses propres agents.
Le rôle par défaut de l’application doit accorder l’indicateur d’autorisation AI — ajoutez SystemPermissionFlag.AI à ses permissionFlagUniversalIdentifiers (ou définissez canAccessAllTools: true). Sans cela, runAgent() échoue avec une erreur d’autorisation.
Définissez une valeur généreuse pour timeoutSeconds sur la fonction logique — les exécutions d’agent peuvent prendre plusieurs secondes.
success est true et result est non nul lorsque l’exécution se termine ; en cas d’échec, success est false, result est null, et error contient la raison (par exemple, lorsque l’espace de travail épuise ses crédits AI en cours d’exécution).

src/roles/default-role.ts

import { defineApplicationRole, SystemPermissionFlag } from 'twenty-sdk/define';

export default defineApplicationRole({
  universalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
  label: 'Default function role',
  // runAgent() requires the AI permission flag on the app's default role.
  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.AI],
});

Évitez les boucles : si vous appelez runAgent() à partir d’un déclencheur d’événement de base de données *.updated et que l’agent met à jour le même enregistrement, limitez le déclencheur avec updatedFields à un champ que l’agent n’écrit jamais (par exemple l’URL source), ou vérifiez si un champ cible est encore vide avant d’appeler runAgent().

Exécution au nom d’un membre de l’espace de travail

Passez runAsWorkspaceMemberId lorsque l’exécution est déclenchée par une personne — par exemple un chatbot répondant à un message — afin que l’agent agisse comme ce membre plutôt qu’en tant qu’application :

src/logic-functions/answer-question.ts

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  prompt: 'How many open opportunities do we have?',
  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
});

L’exécution agit alors avec le propre rôle du membre : elle peut faire tout ce que ce membre peut faire et rien de plus, les enregistrements qu’elle crée lui sont attribués, et ses permissions au niveau des lignes s’appliquent. Le rôle de l’agent ne participe pas — il s’agit de la valeur par défaut de l’application pour les exécutions sans personne derrière. Omettez ce champ pour les exécutions autonomes (tâches planifiées, déclencheurs d’événements de base de données) : celles-ci conservent le rôle propre de l’agent. L’application qui agit reste rattachée au contexte de l’exécution à des fins de traçabilité, sans restreindre les permissions du membre.Votre application est responsable de faire correspondre la personne qui a déclenché l’exécution à un membre de l’espace de travail. Nommer un membre nécessite un jeton d’accès de l’application, et ce qu’un jeton peut nommer dépend du fait qu’il soit ou non associé à un utilisateur :

Un jeton sans utilisateur associé peut nommer n’importe quel membre. Une fonction logique s’exécute avec un tel jeton, tout comme les jetons créés via client_credentials ou à partir d’une clé d’API.
Un jeton émis au nom d’un utilisateur, comme en reçoit un composant frontal, ne peut nommer que le membre de cet utilisateur lui-même.

Tout autre type — une simple session utilisateur, une clé d’API sans jeton d’application — ne peut pas nommer de membre du tout.

runAgent() lève une exception lorsque le membre de l’espace de travail ne peut pas être résolu — un membre inconnu ou supprimé, ou un membre sans rôle. Elle ne revient jamais au rôle propre de l’agent, car cela accorderait plus d’accès que ce que l’appelant a demandé.

Vue d'ensemble

Applications

API

Auto-hébergement

Contribuer

Exécution au nom d’un membre de l’espace de travail

​Exécution au nom d’un membre de l’espace de travail

Exécution au nom d’un membre de l’espace de travail