Habilidades e agentes

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(). Passe uma string prompt ou um histórico de conversas como messages — não ambos:

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

Para bots de múltiplas interações (Slack, Discord, Teams, …), passe o histórico do tópico como messages em vez de um único 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?' },
  ],
});

Pontos-chave:

Forneça exatamente um de prompt (string) ou messages (de 1 a 100 entradas de { role: 'user' | 'assistant', content: string }).
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().

Executando em nome de um membro do workspace

Passe runAsWorkspaceMemberId quando a execução for acionada por uma pessoa — por exemplo, um chatbot respondendo a uma mensagem — para que o agente atue como esse membro em vez de como o app:

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

A execução então atua com a própria função do membro: ela pode fazer tudo o que esse membro pode fazer e nada além disso, os registros que cria são atribuídos a ele, e as permissões em nível de linha dele se aplicam. A função do agente não participa — ela é o padrão do aplicativo para execuções sem ninguém por trás delas. Omita o campo para execuções autônomas (jobs agendados, gatilhos de eventos de banco de dados): essas mantêm a própria função do agente. O aplicativo atuante permanece vinculado ao contexto da execução para rastreabilidade, sem restringir as permissões do membro.Seu app é responsável por mapear a pessoa que acionou a execução para um membro do workspace. Nomear um requer um token de acesso do app, e o que um token pode nomear depende de o token estar associado a um usuário ou não:

Um token sem nenhum usuário associado pode nomear qualquer membro. Uma função lógica é executada com um, assim como tokens criados por meio de client_credentials ou a partir de uma API key.
Um token emitido em nome de um usuário, como um front component recebe, só pode nomear o próprio membro desse usuário.

Qualquer outra coisa — uma sessão simples de usuário, uma API key sem um app token — não pode nomear nenhum membro.

runAgent() gera uma exceção quando o membro do workspace não pode ser resolvido — um membro desconhecido ou removido, ou um sem função. Ele nunca recorre à própria função do agente, pois isso concederia mais acesso do que o requisitante pediu.

Visão Geral

Aplicativos

API

Auto-Anfitrião

Contribuir

Executando em nome de um membro do workspace

​Executando em nome de um membro do workspace

Executando em nome de um membro do workspace