Plugins de Agente

Plugins permitem adicionar funções JavaScript customizadas aos agentes. O agente pode chamar esses plugins como tools durante conversas, executando lógica local (formatação, cálculos, transformações de dados) sem chamadas externas.

O que são Plugins?

Um plugin é uma função JavaScript que você escreve e associa a um agente. Quando o agente precisar executar essa função durante uma conversa, ele a chama como uma tool — e o resultado é injetado na resposta.

Diferente de integrações OAuth (HubSpot, Salesforce), plugins são executados localmente no servidor, sem chamadas externas. São ideais para transformações de dados, formatações, cálculos e validações.

✅ Use para

Cálculos matemáticos
Formatação de dados (CPF, CEP, datas)
Geração de slugs, hashes
Validações locais
Transformação de strings

❌ Não use para

Chamadas fetch/HTTP externas
Acesso ao sistema de arquivos
Operações com banco de dados
Processamento longo (> 5s)
Acesso a process.env

Segurança (Sandbox)

Todo código de plugin é executado em um ambiente restrito. As seguintes APIs globais são bloqueadas:

// BLOQUEADOS no ambiente de plugin:
fetch        // sem chamadas HTTP
require      // sem imports Node.js
process      // sem acesso ao processo
eval         // sem eval dinâmico
Function     // sem new Function() aninhado
XMLHttpRequest
WebSocket

Além disso, existe um timeout de 5 segundos. Se o plugin demorar mais que isso, ele é interrompido com erro.

Como Criar um Plugin

1
Acesse Dashboard → Agentes, abra um agente e clique em Plugins
2
Clique em Novo Plugin e preencha: nome, descrição, input schema (JSON Schema) e código JS
3
Use o botão Testar para validar com um input JSON antes de salvar
4
O plugin fica disponível automaticamente no agente como uma tool

Exemplos de Código

Calculadora Simples

Executa operações matemáticas básicas

Input Schema:

{
  "type": "object",
  "properties": {
    "operacao": { "type": "string", "enum": ["soma", "subtracao", "multiplicacao", "divisao"] },
    "a": { "type": "number" },
    "b": { "type": "number" }
  },
  "required": ["operacao", "a", "b"]
}

Código JavaScript:

const { operacao, a, b } = input;
switch (operacao) {
  case 'soma': return a + b;
  case 'subtracao': return a - b;
  case 'multiplicacao': return a * b;
  case 'divisao':
    if (b === 0) throw new Error('Divisão por zero');
    return a / b;
  default: throw new Error('Operação desconhecida: ' + operacao);
}

Formatador de CEP

Formata CEP no padrão XXXXX-XXX

Input Schema:

{
  "type": "object",
  "properties": {
    "cep": { "type": "string" }
  },
  "required": ["cep"]
}

Código JavaScript:

const cep = String(input.cep).replace(/\D/g, '');
if (cep.length !== 8) throw new Error('CEP deve ter 8 dígitos');
return cep.slice(0, 5) + '-' + cep.slice(5);

Gerador de Slug

Converte texto em slug para URLs

Input Schema:

{
  "type": "object",
  "properties": {
    "texto": { "type": "string" }
  },
  "required": ["texto"]
}

Código JavaScript:

const texto = String(input.texto);
return texto
  .toLowerCase()
  .normalize('NFD')
  .replace(/[\u0300-\u036f]/g, '')
  .replace(/[^a-z0-9\s-]/g, '')
  .replace(/\s+/g, '-')
  .replace(/-+/g, '-')
  .trim();

Limites por Plano

Plano	Plugins por agente
Free	2 plugins por agente
Pro	10 plugins por agente
Business	Ilimitado

O limite é por agente. Um agente Pro pode ter até 10 plugins ativos simultaneamente. Ver planos

API de Plugins

GET/api/agents/:id/pluginsLista plugins do agente

POST/api/agents/:id/pluginsCria novo plugin (valida sintaxe JS)

PATCH/api/agents/:id/plugins/:pluginIdEdita plugin (nome, código, enabled)

DELETE/api/agents/:id/plugins/:pluginIdRemove plugin

POST/api/agents/:id/plugins/:pluginId/testTesta plugin com { input: {...} }

Getting Started

Agent-to-Agent