LLM Connector

Descubra mais sobre o LLM Connector e como utilizá-lo na Digibee Integration Platform.

O LLM Connector envia solicitações para Modelos de Linguagem de Grande Escala (LLMs) dentro de pipelines da Digibee, permitindo tarefas como classificação de texto, extração de informações, sumarização e avaliação de conteúdo.

Ele suporta autenticação integrada e funciona com os principais provedores: OpenAI, Google Gemini, Anthropic Claude, Azure OpenAI, Amazon Bedrock e DeepSeek. A configuração permite controlar o comportamento do modelo, o formato da resposta e a estrutura da saída com base nas necessidades da integração.

Parâmetros

Configure o conector usando os parâmetros abaixo. Os campos que suportam expressões Double Braces são marcados na coluna Suporta DB.

General

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Alias	Nome (alias) para a saída deste conector, permitindo que você a referencie posteriormente no fluxo usando expressões Double Braces. Saiba mais.	String	❌	llm-1
LLM Provider	Especifica o provedor LLM a ser usado. Opções disponíveis: OpenAI, Google Gemini, Anthropic Claude, Azure Open AI, Amazon Bedrock e DeepSeek. Ao selecionar provedores privados (Azure Open AI e Amazon Bedrock), você deve incluir o endpoint.	String	❌	N/A
Use Custom Model	Habilite para selecionar um modelo de IA personalizado. Habilite esta opção para usar um modelo customizado no Amazon Bedrock. Informe o ARN do modelo da sua conta AWS.	Booleano	❌	False
Custom	Modelo personalizado de IA a ser utilizado baseado no provedor selecionado. Deve ser inserido manualmente.	String	✅	N/A
Model	O modelo de IA a ser utilizado, baseado no provedor selecionado. Apenas modelos de texto são suportados; geração de imagem não está disponível.	String	❌	N/A
Account	A conta para autenticação com o conector. Deve estar previamente registrada na página Accounts. Tipo suportado: Secret Key.	Account	❌	N/A
Timeout	Tempo máximo (em milissegundos) permitido para a conclusão da operação. Se esse limite for excedido, a operação será abortada.	Integer	✅	30000
Max Retries	Define o número máximo de tentativas de repetição após uma operação falhar. Por exemplo, um valor de 3 significa que o sistema tentará a operação até três vezes.	Integer	✅	1
System Prompt	Uma instrução predefinida que define o tom e o comportamento da IA. Você pode usá-la para definir funções ou o tipo de resposta que o modelo deve sempre seguir.	Plain Text	✅	N/A
User Prompt	O prompt enviado para o modelo de IA. Suporta sintaxe Double Braces para incluir dados ou variáveis de etapas anteriores.	Plain Text	✅	N/A
File	Permite que o usuário utilize arquivos para incluir dados em seu prompt. Insira o nome do arquivo com a extensão correta, por exemplo, bankslip_1.pdf O nome do arquivo é referenciado neste parâmetro através de Double Braces.	String	✅	N/A

Para configurar o conector com o Amazon Bedrock, selecione o tipo de conta AWS-V4. Como não existem modelos pré-definidos para este provedor, é necessário habilitar a opção Custom model e informar o ARN (Amazon Resource Name) do modelo desejado na conta AWS do usuário.

Tools

Clique em Adicionar para adicionar um novo servidor MCP remoto. Um servidor MCP (Model Context Protocol) gerencia a comunicação entre modelos de IA e sistemas de origem, permitindo que os LLMs acessem ferramentas e dados com segurança.

Somente servidores MCP remotos são suportados.

Forneça os seguintes parâmetros:

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Name	O nome do servidor MCP apenas para identificação.	String	✅	N/A
URL	O endpoint que receberá a chamada.	String	✅	N/A
Account	A conta para autenticação com o provedor do LLM. Ela deve ser previamente cadastrada na página Contas. Tipo suportado: Secret Key.	Account	❌	N/A
Custom Account	A conta personalizada adicional a ser usada pelo conector por meio de expressões Double Braces, por exemplo {{ account.custom.value }}.	String	❌	N/A
Headers	Define os cabeçalhos necessários para a chamada.	Pares chaves-valor	❌	N/A
Query Parameters	Define os parâmetros de consulta para a chamada.	Pares chaves-valor	❌	N/A

Response Format

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Use JSON Schema	Quando ativado, permite que você forneça um JSON Schema para orientar o LLM na geração do formato de resposta esperado.	Booleano	❌	False
JSON Schema definition	O JSON Schema que a IA deve seguir ao gerar a resposta.	JSON	❌	N/A
Use JSON Mode	Quando ativado, permite que você forneça um exemplo de JSON para ajudar o LLM a produzir o formato de resposta desejado.	Booleano	❌	False
JSON definition	O JSON que a IA deve seguir ao gerar a resposta.	JSON	❌	N/A

Settings

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Maximum Output Token	O comprimento máximo da resposta. Números maiores permitem respostas mais longas, números menores as tornam mais curtas. Em alguns modelos mais recentes (principalmente da OpenAI), este parâmetro é chamado de Max Completion Tokens.	Integer	✅	10000
Temperature	Controla a criatividade. Valores mais baixos tornam as respostas mais focadas e previsíveis. Valores mais altos as tornam mais variadas e criativas.	Float	✅	0.1
Top K	Limita a quantidade de opções de palavras que o modelo considera em cada etapa. Números menores representam respostas mais seguras e focadas. Números maiores representam mais variedade.	Integer	✅	64
Top P	Outra forma de controlar a variedade. O modelo analisa apenas as palavras com maior probabilidade de se somarem a essa probabilidade. Valores mais baixos representam respostas mais focadas.	Integer	✅	1
Frequency Penalty	Desencoraja o modelo de repetir as mesmas palavras com muita frequência.	Integer	✅	0
Presence Penalty	Incentiva o modelo a trazer novas ideias em vez de permanecer no mesmo tópico.	Float	✅	0

Error Handling

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Fail On Error	Se ativado, interrompe a execução do pipeline ao ocorrer um erro. Se desativado, a execução continua, mas a propriedade "success" será definida como false.	Booleano	❌	False

Documentation

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Documentation	Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.	String	❌	N/A

Testando o Conector LLM

O conector LLM pode ser testado isoladamente, sem executar o pipeline completo. Isso facilita o rápido refinamento e aprimoramento dos seus prompts.

Após configurar os parâmetros do conector, clique em Executar no canto inferior direito para executar um teste e visualizar as respostas da solicitação. Após verificar se o conector funciona conforme o esperado, clique em Confirmar para salvá-lo e retornar ao fluxo principal.

LLM Connector em ação

Configuração apenas com User Prompt

Essa configuração utiliza apenas o parâmetro User Prompt para enviar uma requisição ao modelo de IA.

Vantagens:

• Fácil de configurar com apenas uma entrada.

• Bom para testar diferentes prompts rapidamente.

• Funciona bem para requisições simples.

Exemplo prático

• Caso de uso: Um pipeline integrado ao Zendesk recebe um novo ticket de cliente. O LLM Connector é utilizado para analisar a solicitação e classificar seu tópico.

• Objetivo: Classificar o tópico de um ticket de suporte.

User Prompt:

Classifique o tópico da seguinte solicitação de cliente:
"Meu pagamento foi recusado, mas o valor foi debitado da minha conta. Preciso de ajuda para resolver isso."

Exemplo de saída:

{
  "status": 200,
  "body": "Problemas de pagamento"
}

Configuração com User + System Prompts

Essa configuração utiliza os parâmetros User Prompt e System Prompt para guiar a resposta da IA.

Vantagens:

• Ajuda a guiar o tom e o comportamento da IA.

• Torna as respostas mais consistentes.

• Adiciona contexto que ajuda a IA a entender melhor o prompt.

Exemplo prático

• Caso de uso: Após classificar o ticket de suporte, o pipeline consulta uma base de conhecimento. O LLM Connector é então usado novamente para gerar uma resposta personalizada ao cliente.

• Objetivo: Gerar uma resposta personalizada utilizando tom e estilo predefinidos.

System Prompt:

Você é um agente de suporte amigável e prestativo. Use sempre um tom empático e forneça instruções claras. Retorne a mensagem em texto simples, sem quebras de linha.

User Prompt:

Escreva uma resposta para o cliente abaixo, explicando que iremos investigar o pagamento e responder dentro de 24 horas:
"Meu pagamento foi recusado, mas o valor foi debitado da minha conta. Preciso de ajuda para resolver isso."

Exemplo de saída:

{
  "status": 200,
  "body": "Olá, sinto muito por ouvir que você está passando por problemas com seu pagamento. Posso imaginar que isto pode ser frustrante e quero que saiba que estamos aqui para ajudar. Vamos investigar essa situação o mais rápido possível. O processo de investigação pode levar até 24 horas e entraremos em contato assim que tivermos uma atualização para você. Enquanto isso, sugiro que verifique com sua instituição bancária se há algum problema do lado deles. Muito obrigado pela sua paciência e compreensão."
}

Configuração com Prompts + JSON Schema

O suporte a JSON Schema pode variar entre provedores e modelos de LLM. Recomendamos consultar a documentação oficial do provedor e do modelo antes de configurar para confirmar a compatibilidade.

Essa configuração utiliza User Prompt, System Prompt e JSON Schema para gerar uma resposta estruturada.

Vantagens:

• Mantém a saída consistente com um formato definido.

• Valida automaticamente tipos de campos, campos obrigatórios e valores permitidos.

• Funciona como um contrato entre sistemas, tornando a integração mais confiável.

• Evita que dados inválidos sejam processados.

Exemplo prático

Caso de uso: Um pipeline recebe um comentário gerado por um usuário em uma plataforma de ISV (independent software vendor). O LLM Connector envia o comentário para a IA avaliar se ele é nocivo ou ofensivo. A pontuação retornada é então usada para decidir se o comentário deve ser publicado ou se o usuário deve ser sinalizado.

Objetivo: Avaliar e atribuir uma pontuação ao nível de nocividade de um comentário e determinar se ele deve ser aprovado.

System Prompt:

Você é um moderador de conteúdo. Avalie se o comentário é nocivo, atribua uma pontuação de 0 a 1 para gravidade e indique se ele deve ser aprovado
User Prompt:

User Prompt:

Avalie o seguinte comentário:
"Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa."

JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ModerationResult",
  "type": "object",
  "properties": {
    "status": {
      "type": "integer",
      "enum": [200],
      "description": "Código de status HTTP"
    },
    "body": {
      "type": "object",
      "properties": {
        "score": {
          "type": "string",
          "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",
          "description": "Pontuação de gravidade de 0 a 1"
        },
        "label": {
          "type": "string",
          "description": "Rótulo descrevendo o conteúdo, ex.: inofensivo, potencialmente nocivo"
        },
        "should_approve": {
          "type": "boolean",
          "description": "Indica se o comentário deve ser aprovado"
        }
      },
      "required": ["score", "label", "should_approve"],
      "additionalProperties": false
    }
  },
  "required": ["status", "body"],
  "additionalProperties": false
}

Saída:

{
  "body": {
    "status": "200",
    "body": {
      "score": "0",
      "label": "inofensivo",
      "should_approve": true
    }
  },
  "tokenUsage": {
    "inputTokenCount": 168,
    "outputTokenCount": 22,
    "totalTokenCount": 190
  }
}

Configuração com Prompts + JSON simples

Essa configuração utiliza User Prompt, System Prompt e JSON simples para gerar uma resposta estruturada.

Vantagens:

• Produz saída em um formato simples e legível.

• Flexível e fácil de trabalhar.

• Bom quando não é necessária validação rigorosa.

Exemplo prático

Usando o mesmo caso de uso acima, os prompts orientam a IA a retornar diretamente um objeto JSON, sem validação de schema.

System Prompt:

Você é um moderador de conteúdo. Avalie se o comentário é nocivo, atribua uma pontuação de 0 a 1 para gravidade e indique se ele deve ser aprovado.

User Prompt:

Avalie o seguinte comentário:
"Tive uma ótima experiência com essa empresa. A equipe é profissional e muito prestativa."

JSON Simples:

{
  "score": "",
  "label": "",
  "should_approve": ""
}

Possível saída:

{
  "body": {
    "score": "0",
    "label": "Inofensivo",
    "should_approve": "sim"
  },
  "tokenUsage": {
    "inputTokenCount": 91,
    "outputTokenCount": 26,
    "totalTokenCount": 117
  }
}

Configuração dinâmica: Prompt com referência Double Braces

Essa configuração utiliza o campo User Prompt para injetar dinamicamente dados de um conector anterior usando expressões Double Braces. Além disso, os campos System Prompt e Output Format são usados para orientar a IA e gerar uma resposta estruturada.

Vantagens:

• Permite prompts contextuais com base em dados do pipeline.

• Conecta a resposta da IA a informações de tempo de execução.

Exemplo prático

• Caso de uso: Um pipeline recebe dados de endereço de um conector REST que consulta a API pública brasileira de CEP (OpenCEP). O LLM Connector é então utilizado para classificar o tipo de endereço como residencial, comercial ou rural, com base no nome da rua e no bairro retornados pela API.

• Objetivo: Categorizar o tipo de endereço utilizando dados dinâmicos do conector anterior.

System Prompt:

Você é um assistente de classificação de endereços. Com base no nome da rua e no bairro, classifique o endereço como residencial, comercial ou rural. Explique seu raciocínio.

User Prompt com Double Braces:

Use o seguinte endereço para fazer sua avaliação: {{message.body}}

Output Format Body:

{
  "tipo": "",
  "razão": ""
}

Possível saída:

{
  "status": 200,
  "body": {
    "tipo": "Residencial",
    "razão": "Os endereços residenciais geralmente são caracterizados por nomes de rua sem identificadores comerciais ou industriais. A 'Rua Abilio Carvalho Bastos' não sugere que seja uma área comercial ou industrial. Além disso, as ruas normalmente representam áreas residenciais em uma cidade ou cidade. O bairro 'Fósforo', por não possuir uma identificação típica de zonas comerciais ou rurais, também sugere ser uma área residencial."
  }
}

Configuração com MCP Server

Essa configuração utiliza um MCP Server, combinado com User Prompt, System Prompt e JSON Schema, para solicitar e estruturar documentação gerada a partir de fontes de dados externas.

Vantagens:

• Permite comunicação segura entre modelos de IA e sistemas de origem.

• Mantém a saída gerada consistente com um formato predefinido.

• Valida automaticamente campos obrigatórios e tipos de dados.

• Garante geração de documentação confiável e precisa.

Exemplo prático

• Caso de uso: Um pipeline se conecta ao servidor MCP Deepwiki para recuperar conhecimento técnico sobre um tópico. A IA transforma essas informações brutas em documentação estruturada.

• Objetivo: Gerar uma seção de documentação sobre Arquitetura Orientada a Eventos (Event-Driven Architecture) com título claro, descrição breve, casos de uso práticos e boas práticas.

MCP Server:

• Name: DeepWiki

• URL: https://mcp.deepwiki.com/mcp

System prompt:

Você é um gerador de documentação técnica. Sempre escreva em inglês claro e conciso, usando um tom profissional, mas simples.
Sua tarefa é transformar informações brutas recuperadas de ferramentas externas (como o Deepwiki) em documentação bem estruturada.
Garanta que sua saída seja consistente, precisa e alinhada com o formato solicitado.

User prompt:

Use as informações recuperadas do servidor MCP Deepwiki sobre o tópico "Event-Driven Architecture" para criar uma seção de documentação.
A documentação deve incluir:
Um título claro.
Uma descrição concisa (2–3 frases).
Pelo menos três casos de uso práticos.
Pelo menos três boas práticas.
Formate a resposta seguindo estritamente o JSON Schema fornecido.

JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "DocumentationSection",
  "type": "object",
  "required": ["title", "description", "use_cases", "best_practices"],
  "properties": {
    "title": {
      "type": "string",
      "description": "O título da seção de documentação"
    },
    "description": {
      "type": "string",
      "description": "Uma descrição concisa do tópico (2-3 frases)"
    },
    "use_cases": {
      "type": "array",
      "description": "Casos de uso práticos para o tópico",
      "items": {
        "type": "string"
      },
      "minItems": 3
    },
    "best_practices": {
      "type": "array",
      "description": "Boas práticas recomendadas para o tópico",
      "items": {
        "type": "string"
      },
      "minItems": 3
    }
  },
  "additionalProperties": false
}

Saída:

{
  "body": {
    "title": "Event-Driven Architecture",
    "description": "Arquitetura Orientada a Eventos (Event-Driven Architecture - EDA) é um padrão de design de software em que os componentes do sistema se comunicam produzindo e consumindo eventos. Essa abordagem possibilita sistemas fracamente acoplados que podem reagir a mudanças em tempo real, aumentando a escalabilidade e a flexibilidade. A EDA é comumente usada em sistemas distribuídos e aplicações que exigem processamento assíncrono.",
    "use_cases": [
      "Construção de microsserviços que precisam se comunicar de forma assíncrona.",
      "Implementação de plataformas de análise em tempo real que processam dados em fluxo.",
      "Automatização de fluxos de trabalho em resposta a eventos de negócios, como processamento de pedidos ou ações de usuários."
    ],
    "best_practices": [
      "Projetar eventos autônomos e descritivos para garantir comunicação clara entre os componentes.",
      "Usar sistemas de mensageria confiáveis para garantir a entrega de eventos e evitar perda de dados.",
      "Monitorar e registrar o fluxo de eventos para detectar e resolver rapidamente problemas no sistema."
    ]
  },
  "tokenUsage": {
    "inputTokenCount": 396,
    "outputTokenCount": 162,
    "totalTokenCount": 558
  }
}

Perguntas frequentes

Como posso testar e experimentar meus prompts?

Use o Painel de Execução para testar seus prompts. A opção Executar seleção é especialmente útil para testar prompts separadamente do restante do pipeline.

Posso usar dados de conectores anteriores?

Sim. Você pode usar expressões Double Braces para referenciar dados de conectores anteriores e incluí-los no seu prompt.

Como os dados sensíveis são tratados?

O conector não redige nem filtra os dados do payload. Recomendamos seguir as mesmas práticas de tratamento de dados usadas com outros conectores.

Posso encadear várias chamadas LLM em um único pipeline?

Sim. Você pode usar a saída de uma chamada LLM como entrada para outra. Por exemplo, primeiro classificar um ticket de suporte, depois gerar uma resposta com base na classificação.

E se o LLM gerar resultados imprecisos ou inventados?

Para tarefas críticas, reduza o risco de alucinação dividindo o processo em etapas menores, como gerar primeiro e verificar depois. Isso proporciona mais controle e permite validar o resultado antes de utilizá-lo.

O que acontece se o provedor demorar muito para responder?

Se o provedor demorar muito para responder, a solicitação será encerrada por tempo excedido e uma mensagem de erro será exibida no Painel de Execução.