upstream-twenty/packages/twenty-docs/l/pt/developers/extend/apps/logic/skills-and-agents.mdx

---
title: Habilidades e agentes
description: Defina habilidades e agentes de IA para o seu aplicativo.
icon: robot
---

<Warning>
  As habilidades e os agentes estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
</Warning>

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.

<AccordionGroup>
<Accordion title="defineSkill" description="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:

```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.

</Accordion>
<Accordion title="defineAgent" description="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:

```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`.

</Accordion>
<Accordion title="runAgent" description="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:

```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 <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`:

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

<Warning>
  **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()`.
</Warning>

### 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.

<Warning>
  `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.
</Warning>

</Accordion>
</AccordionGroup>