Habilidades e agentes - Twenty Documentation

defineSkill

Defina habilidades de agentes de IA

As habilidades definem instruções e capacidades reutilizáveis que os agentes de IA podem usar no seu espaço de trabalho. Use defineSkill() para definir habilidades com validação integrada:

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`,
});

Pontos-chave:

name é uma string de identificador exclusivo para a habilidade (recomenda-se kebab-case).
label é o nome de exibição legível por humanos mostrado na UI.
content contém as instruções da habilidade — este é o texto que o agente de IA usa.
icon (opcional) define o ícone exibido na UI.
description (opcional) fornece contexto adicional sobre a finalidade da habilidade.

defineAgent

Defina agentes de IA com prompts personalizados

Os agentes são assistentes de IA que vivem dentro do seu espaço de trabalho. Use defineAgent() para criar agentes com um prompt de sistema personalizado:

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.',
});

Pontos-chave:

name é a string de identificador exclusiva do agente (recomenda-se kebab-case).
label é o nome de exibição mostrado na UI.
prompt é o prompt do sistema que define o comportamento do agente.
description (opcional) fornece contexto sobre o que o agente faz.
icon (opcional) define o ícone exibido na UI.
modelId (opcional) substitui o modelo de IA padrão usado pelo agente.
responseFormat (opcional) controla o formato da saída do agente. O padrão é { type: 'text' } para texto em formato livre. Use { type: 'json', schema } para forçar a saída em JSON estruturado.

Por padrão, um agente retorna texto em formato livre. Para obter saída estruturada, defina responseFormat como { type: 'json' } e forneça um 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,
    },
  },
});

Observações sobre o esquema:

O esquema é um objeto plano: o type de cada propriedade deve ser um primitivo (string, number ou boolean). Objetos aninhados e arrays não são suportados.
description (opcional) em cada propriedade orienta o modelo sobre o que colocar ali.
required (opcional) lista as propriedades que o modelo deve sempre retornar.
additionalProperties: false (opcional) proíbe qualquer propriedade não declarada em properties.

runAgent

Executar um agente a partir de uma função de lógica

runAgent() permite que uma função de lógica execute um dos agentes do seu app (com suas habilidades e ferramentas). Identifique o agente pelo universalIdentifier que você passou para defineAgent():

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.',
});

Pontos-chave:

O agente é executado sincronamente e pode ler/atualizar registros por conta própria por meio de suas próprias ferramentas — runAgent() é resolvido quando a execução é concluída.
Um app só pode executar os seus próprios agentes.
O papel padrão do app deve conceder o sinalizador de permissão AI — adicione SystemPermissionFlag.AI ao seu permissionFlagUniversalIdentifiers (ou defina canAccessAllTools: true). Sem isso, runAgent() falha com um erro de permissão.
Defina um valor generoso de timeoutSeconds na função de lógica — execuções de agentes podem levar vários segundos.
success é true e result é diferente de nulo quando a execução é concluída; em caso de falha success é false, result é nulo e error contém o motivo (por exemplo, quando o espaço de trabalho fica sem créditos de IA no meio da execução).

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],
});

Evite loops: se você chamar runAgent() a partir de um gatilho de evento de banco de dados *.updated e o agente atualizar o mesmo registro, delimite o gatilho com updatedFields para um campo que o agente nunca escreve (por exemplo, a URL de origem) ou verifique se algum campo de destino ainda está vazio antes de chamar runAgent().