Gatilhos Generativos

Gatilhos são ações que o LLM pode chamar automaticamente durante uma conversa. Eles conectam o assistente a sistemas externos — APIs, CRMs, calendários, plataformas de saúde — sem que o usuário precise perceber.

Como Funciona

Usuário: "Quero agendar para amanhã às 14h"
                    ↓
         LLM analisa a mensagem
         LLM identifica: "preciso chamar agendar_consulta"
                    ↓
         Platform executa o gatilho
         (ex: Google Calendar API)
                    ↓
         Resposta da integração volta para o LLM
                    ↓
LLM (se InterpretResponse=true): "Sua consulta foi agendada!"
LLM (se InterpretResponse=false): action executada silenciosamente

O LLM decide quando e se chamar um gatilho com base na descrição fornecida e no contexto da conversa.

Estrutura de um Gatilho

Function Calling

Cada gatilho expõe uma função para o LLM via JSON Schema:

json

{
  "name": "consultar_status_pedido",
  "description": "Consulta o status atual de um pedido pelo número. Use quando o cliente perguntar sobre o andamento, localização ou previsão de entrega de um pedido.",
  "parameters": {
    "type": "object",
    "properties": {
      "numero_pedido": {
        "type": "string",
        "description": "Número do pedido, geralmente no formato ORD-XXXXX"
      },
      "incluir_historico": {
        "type": "boolean",
        "description": "Se deve incluir o histórico completo de movimentações"
      }
    },
    "required": ["numero_pedido"]
  }
}

Campos do FunctionCalling

Campo	Obrigatório	Descrição
`name`	✅	Identificador da função (sem espaços, use `_`)
`description`	✅	Crucial: explica QUANDO o LLM deve chamar. Máx 350 chars
`parameters`	➖	JSON Schema dos argumentos que o LLM deve extrair

A Importância da Descrição

A description é o que o LLM usa para decidir se deve ou não chamar o gatilho. Uma descrição ruim leva a chamadas incorretas ou ausentes.

Descrição ruim:

"Agenda consultas"

Descrição boa:

"Agenda uma consulta médica no sistema Feegow. Use quando o paciente
confirmar que deseja agendar, após já ter escolhido o médico, data e horário.
NÃO use para apenas verificar disponibilidade."

Dicas para uma boa descrição:

Indique quando usar (contexto)
Indique quando NÃO usar (evita falsos positivos)
Use verbos de ação no imperativo
Mencione o que o LLM precisa extrair do usuário antes de chamar

Parâmetros e Extração Automática

O LLM extrai automaticamente os parâmetros definidos do contexto da conversa. Você não precisa pedir explicitamente cada dado — o LLM sabe o que precisa coletar.

json

{
  "name": "criar_lead_crm",
  "parameters": {
    "properties": {
      "nome": { "type": "string", "description": "Nome completo do cliente" },
      "email": { "type": "string", "description": "E-mail do cliente" },
      "empresa": { "type": "string", "description": "Nome da empresa onde trabalha" },
      "interesse": {
        "type": "string",
        "enum": ["basico", "pro", "enterprise"],
        "description": "Plano de interesse do cliente"
      }
    },
    "required": ["nome", "email"]
  }
}

Se nome e email já foram mencionados na conversa, o LLM os usa diretamente. Se não, pode perguntar ao usuário antes de chamar.

`MaxInteractions`

Define quantas vezes o LLM pode chamar gatilhos em sequência numa única mensagem do usuário.

Valor	Comportamento
`1`	Chama no máximo 1 gatilho por resposta
`2` (padrão)	Pode chamar 1 gatilho, receber a resposta e chamar mais 1
`3-10`	Permite fluxos mais complexos com múltiplas etapas

Exemplo com MaxInteractions = 3:

Usuário: "Agende para o Lucas, CPF 123.456.789-00"
    ↓
LLM chama: buscar_paciente(cpf="123.456.789-00")
    ↓
Sistema retorna: {id: "pac_42", nome: "Lucas Silva", ...}
    ↓
LLM chama: verificar_disponibilidade(paciente_id="pac_42")
    ↓
Sistema retorna: ["14h", "15h", "16h de amanhã"]
    ↓
LLM pergunta: "Lucas, tenho horários disponíveis amanhã: 14h, 15h ou 16h. Qual prefere?"

`InterpretResponse`

Controla se o LLM lê e interpreta a resposta da integração para formular uma resposta ao usuário.

Valor	Comportamento
`true`	LLM recebe a resposta do gatilho e decide o que dizer ao usuário
`false`	A ação é executada silenciosamente; o LLM responde sem ver o resultado

Quando usar false:

Ações de log/analytics (Meta Pixel, registro de evento)
Ações que não afetam a resposta (atualização de CRM em background)
Quando você quer controlar a mensagem de confirmação via responseDirective

`CopilotOnly`

Marca o gatilho para ser usado exclusivamente no modo copilot. Em sessões normais, este gatilho é ignorado.

Útil para:

Ações internas de backoffice que o usuário final não deve acionar
Integrações de análise e BI
Ferramentas de moderação/supervisão

Ações Disponíveis por Gatilho

Cada gatilho está associado a uma ação de integração. Veja as opções:

Ação	Subtipo	Descrição
`WEBHOOK`	—	HTTP customizado (GET, POST, PUT, DELETE)
`NATIVE`	SEND_TEXT, SEND_BUTTON, SEND_LIST...	Mensagens WhatsApp avançadas
`CRM`	UPSERT_CONTACT	Criação/atualização de contato
`GOOGLE_CALENDAR`	CHECK, LIST, SCHEDULE	Agendamento
`KNOWLEDGE`	SEARCH	Busca na base de conhecimento
`META_ADS`	SEND_EVENT	Pixel de conversão
`CHAT_INTEGRATION`	CHANGE_STATUS, SUMMARIZE	Atendimento humano
`CATALOG`	SEARCH, ADD_CART...	Catálogo de produtos
`FEEGOW`	24 subtipos	Gestão clínica
`Z_API` / `MY_ZAP` / `EVOLUTION`	SET_TAG, RESET_SESSION...	Gerenciamento WhatsApp

Exemplo Completo: Assistente de Vendas

json

{
  "triggers": [
    {
      "name": "qualificar_lead",
      "description": "Registra um lead qualificado no CRM após coletar nome, e-mail e interesse. Use quando o cliente demonstrar interesse genuíno no produto.",
      "parameters": {
        "properties": {
          "nome": { "type": "string" },
          "email": { "type": "string" },
          "interesse": {
            "type": "string",
            "enum": ["demo", "proposta", "informacoes"]
          }
        },
        "required": ["nome", "email", "interesse"]
      },
      "action": { "type": "CRM", "subtype": "UPSERT_CONTACT" },
      "interpretResponse": false
    },
    {
      "name": "agendar_demo",
      "description": "Agenda uma demonstração no Google Calendar. Use APENAS após o lead confirmar nome, e-mail e ter escolhido uma data/hora específica.",
      "parameters": {
        "properties": {
          "nome": { "type": "string" },
          "email": { "type": "string" },
          "data_hora": { "type": "string", "description": "Data e hora no formato ISO 8601" }
        },
        "required": ["nome", "email", "data_hora"]
      },
      "action": { "type": "GOOGLE_CALENDAR", "subtype": "SCHEDULE" },
      "interpretResponse": true
    }
  ]
}