---
title: Habilidades e agentes
description: Defina habilidades e agentes de IA para o seu aplicativo.
icon: robot
---
As habilidades e os agentes estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
Os aplicativos podem definir capacidades de IA que residem dentro do espaço de trabalho — instruções de habilidades reutilizáveis e agentes com prompts de sistema personalizados.
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:
```ts 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.
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:
```ts 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`:
```ts 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()` 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:
```ts 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 : 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`:
```ts 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](/l/pt/developers/extend/apps/config/roles) 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).
```ts 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:
```ts 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.