Agent Component — Guia completo de configuração

Aprenda a criar rapidamente seu primeiro Agent e depois explore, passo a passo, todas as opções de configuração disponíveis.

Crie seu próprio Agente de IA com o Agent Component. Esse componente abstrai as APIs dos principais provedores de LLM para que você possa executar facilmente tarefas como classificação de texto, extração de informações, sumarização, avaliação de conteúdo e muito mais, tudo dentro dos seus pipelines Digibee.

Este guia apresenta:

• Como configurar um Agent funcional em poucos minutos

• Explicação de cada opção de configuração

• Recursos avançados como tools, recuperação de conteúdo, guardrails e respostas mock

Início rápido: Crie seu primeiro agent funcional em 5 passos

Pré‑requisitos

Antes de iniciar, você precisa:

• Ter uma conta no provedor de LLM escolhido e uma chave de API (token).

• Registrar essa chave na Digibee como uma Conta do tipo "Secret Key".

Este teste consumirá tokens do seu provedor.

Para adicionar sua chave de API:

Abra Contas, selecione Criar, escolha Secret Key, cole o token do provedor e salve. O token deve ser gerado no console do provedor (por exemplo, o painel da OpenAI). Mantenha-o seguro.

Passos

1. Adicione o Agent Component ao pipeline pela biblioteca de conectores ou pelo Smart Connector.

2. Em Modelo, escolha um modelo de qualquer provedor suportado (por exemplo, OpenAI — GPT-4.1 Mini).

3. Clique no ícone de engrenagem (⚙) e selecione a conta Secret Key que você configurou na página Contas.

4. Na seção Mensagens, insira:

   • System: Você é um assistente.

   • User: Explique o que é uma API em um parágrafo.

5. Clique em Executar para testar o Agent.

6. A resposta deve ser semelhante a esta:

{
  "body": {
    "text": "Uma API (Interface de Programação de Aplicações) é um conjunto de regras e definições que permite que diferentes softwares se comuniquem entre si. Ela funciona como uma ponte, facilitando o envio e recebimento de dados ou comandos entre sistemas distintos, sem que seja necessário conhecer os detalhes internos de funcionamento de cada um. Por meio de uma API, desenvolvedores podem integrar funcionalidades de outros serviços, como pagamentos online, mapas ou redes sociais, em suas próprias aplicações de forma padronizada, segura e eficiente."
  },
  "tokenUsage": {
    "inputTokenCount": 29,
    "outputTokenCount": 104,
    "totalTokenCount": 133
  }
}

Seu Agent agora está funcionando com sucesso.

As próximas seções explicam cada configuração em detalhes.

Configuração detalhada

Algumas configurações são obrigatórias. Depois de concluir a configuração básica, você pode explorar recursos mais avançados.

Configuração obrigatória

Com os dois passos abaixo, seu Agent já está pronto para tarefas simples e diretas.

1

Selecione o modelo (obrigatório)

Escolha o provedor e o modelo que o Agent deve usar. Provedores suportados:

• Anthropic Claude

• DeepSeek

• Google Gemini

• OpenAI

• Azure OpenAI

• Custom Model

• Azure OpenAI (Private)

• Amazon Bedrock (Private)

Ou selecione Custom Model para personalizar o modelo.

Após selecionar o provedor, clique no ícone de engrenagem (⚙) para abrir a página Configuração do Modelo. Preencha os campos a seguir.

Configuração da Conta

Essas configurações definem como a Digibee autentica com o provedor de LLM. Se nenhuma conta for selecionada, o conector não funcionará. Alguns provedores também exigem um Endpoint personalizado, dependendo de como expõem seus modelos.

Provedores privados — como Azure OpenAI (Private) e Amazon Bedrock (Private) — sempre exigem um endpoint personalizado. Ao selecionar um desses provedores, garanta que você informe o endpoint correto para seu ambiente.

Para Amazon Bedrock, é necessário:

• Selecionar o tipo de conta AWS‑V4, método suportado pelo Bedrock.

• Como a Digibee não fornece modelos predefinidos para Bedrock, você deve habilitar Custom Model e informar o ARN (Amazon Resource Name) do modelo presente na sua conta AWS.

Parâmetro	Descrição	Tipo	Suporta DB	Padrão
Conta	Conta usada para autenticar no provedor LLM. Deve ser cadastrada em Contas. Suporta Secret Key ou AWS-V4 (para Bedrock).	Account	❌	N/A
Endpoint	Endpoint personalizado para o provedor selecionado. Necessário para provedores privados.	String	✅	N/A
Permitir conexões inseguras	Permite conexões SSL inseguras. Recomendado apenas para testes ou ambientes internos.	Boolean	❌	false

Se você selecionar um modelo privado, também deve configurar o Nome do Modelo Personalizado. Para personalizar totalmente o modelo, configure o Nome do Modelo Personalizado e selecione um provedor compatível.

Parâmetros do Modelo

Esses valores determinam a personalidade e o comportamento do modelo.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Temperatura	Controla a criatividade. Valores baixos = mais foco; valores altos = mais diversidade.	Float	✅	0.7
Máximo de Tokens de Saída	Limita o número de tokens na saída.	Integer	✅	1024
Top K	Limita quantas opções de palavras o modelo considera a cada etapa. Valores baixos = mais seguro; valores altos = mais diverso.	Integer	✅	64
Top P	Controla a variabilidade usando limites de probabilidade. Valores baixos = respostas mais focadas.	Integer	✅	1
Penalidade de Frequência	Reduz a repetição de palavras idênticas.	Integer	✅	N/A
Penalidade de Presença	Incentiva o modelo a trazer novas ideias em vez de permanecer no mesmo tópico.	Float	✅	N/A

Configurações Avançadas

Use essas opções para ajustar o desempenho e a resiliência do modelo. Você pode modificá-las conforme necessário ou manter a configuração padrão.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Timeout	Tempo máximo permitido (em ms) para a operação ser concluída.	Integer	✅	30000
Máximo de Tentativas	Número de tentativas de repetição após uma falha.	Integer	✅	1
Parâmetros Personalizados	Parâmetros personalizados adicionais para enviar à API do modelo.	Pares chave-valor	❌	N/A

Formato da Resposta

Define como o modelo deve estruturar a saída. Quando o provedor oferece suporte, configurar um Esquema JSON é recomendado para garantir respostas mais precisas e consistentes.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Usar Esquema JSON	Permite fornecer um Esquema JSON para reforçar a estrutura da resposta.	Boolean	❌	false
Definição do Esquema JSON	O Esquema que define a estrutura esperada.	JSON	❌	N/A
Usar Modo JSON	Permite enviar um exemplo em JSON para orientar a resposta.	Boolean	❌	false
Definição JSON	O exemplo JSON que o modelo deve seguir.	JSON	❌	N/A

2

Configure as mensagens (obrigatório)

• Mensagem do Sistema: Descreve regras, tom e comportamento geral.

  • Exemplo: “Você é um analista de dados sênior…”

• Mensagem do Usuário: O prompt em si. Você pode injetar dados do pipeline usando Double Braces.

  • Exemplo: “Resuma o conteúdo abaixo…”

Depois de adicionar suas mensagens, você já pode testar o Agent.

Cada execução consome tokens do seu provedor. Para reduzir o uso ao testar o pipeline completo, considere adicionar uma resposta mock.

Configuração opcional

As configurações opcionais permitem estender e personalizar o comportamento do Agent. Elas não são obrigatórias, mas são úteis quando você precisa de integrações, recuperação de contexto externo, validação ou testes controlados.

1

Adicione tools (opcional)

As tools expandem o que o Agent pode fazer. Use-as quando o Agent precisar:

• Chamar APIs

• Acessar sistemas internos

• Acionar outros pipelines

• Buscar conteúdo externo na web

Se você estiver apenas gerando texto ou fazendo classificação, pode ignorar ferramentas.

Veja como configurar os tipos de ferramentas suportadas.

Servidor MCP

Um servidor Model Context Protocol (MCP) gerencia a comunicação entre o modelo de IA e sistemas externos, permitindo que o LLM acesse ferramentas e dados externos com segurança.

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Nome	Identificador deste MCP server.	String	✅	N/A
URL do Servidor	Endpoint que recebe a requisição.	String	✅	N/A
Conta	Conta usada para autenticação. Deve ser configurada em Contas. Tipo suportado: Secret Key.	Account	❌	N/A
Conta Personalizada	Conta secundária referenciada por Double Braces, por exemplo {{ account.custom.value }}.	String	❌	N/A
Cabeçalhos	Cabeçalhos HTTP incluídos na requisição.	Pares chave-valor	❌	N/A
Parâmetros de Consulta	Parâmetros de consulta incluídos na requisição.	Pares chave-valor	❌	N/A

Recuperação de Conteúdo

Habilite Retrieval-Augmented Generation (RAG) para permitir que o modelo use contexto externo armazenado em um banco vetorial.

Modelo de Embedding

Um modelo de embedding converte texto em vetores que representam seu significado. Escolha um provedor e modelo que correspondam à sua arquitetura. Opções suportadas:

Local (all-MiniLM-L6-v2)

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Máximo de Resultados	Número máximo de vetores retornados da busca por similaridade.	Integer	❌	N/A
Pontuação Mínima	Similaridade mínima (0.0 a 1.0) para que um resultado seja considerado relevante. Quanto maior, mais restritivo.	String	✅	0.7

OpenAI

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Conta de Embedding	Conta OpenAI usada para embeddings. Suporta: Basic, Secret Key.	Select	❌	N/A
Nome do Modelo de Embedding	Nome do modelo, por exemplo text-embedding-3-large.	String	✅	N/A
Dimensão do Vetor	Número de dimensões do embedding. Deve corresponder ao banco vetorial.	Integer	❌	N/A
Máximo de Resultados	Número máximo de vetores similares retornados.	Integer	❌	N/A
Pontuação Mínima	Similaridade mínima para considerar um resultado. Valores altos = mais restritivo.	String	✅	0.7

Hugging Face

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Conta de Embedding	Credenciais Hugging Face. Suporta: Basic, Google Key.	Select	❌	N/A
Nome do Modelo de Embedding	Nome do modelo, ex.: sentence-transformers/all-mpnet-base-v2.	String	✅	N/A
Dimensão do Vetor	Dimensão do vetor gerado. Deve corresponder ao seu store.	Integer	❌	N/A
Aguardar Modelo	Se o sistema deve aguardar o carregamento do modelo (true) ou retornar erro se indisponível (false).	Boolean	❌	true
Máximo de Resultados	Máximo de vetores retornados.	Integer	❌	N/A
Pontuação Mínima	Similaridade mínima para considerar relevância.	String	✅	0.7

Armazenamento Vetorial

Um armazenamento vetorial é um banco otimizado para armazenar e recuperar embeddings. Você pode conectar:

PostgreSQL (PGVector)

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Host	Hostname ou IP do servidor PostgreSQL.	String	✅	localhost
Porta	Porta de conexão.	Number	❌	5432
Nome do Banco de Dados	Nome do banco com a tabela vetorial.	String	✅	N/A
Conta do Armazenamento Vetorial	Conta com credenciais de acesso.	Select	❌	N/A
Nome da Tabela	Nome da tabela onde embeddings são armazenados.	String	✅	embeddings

Neo4j

Parâmetro	Descrição	Tipo de dado	Suporta DB	Padrão
Nome do Banco de Dados	Nome do banco Neo4j usado.	String	✅	N/A
Conta do Armazenamento Vetorial	Credenciais de conexão.	Select	❌	N/A
Nome do Índice	Índice que contém os vetores.	String	✅	N/A
URI	URI para conexão.	String	✅	N/A
Rótulo do Nó	Label dos nodes que armazenam embeddings.	String	✅	Document
Propriedade de Embedding	Propriedade com o vetor.	String	✅	embedding
Propriedade de Texto	Propriedade com o texto ou documento original.	String	✅	text

2

Adicione arquivos (opcional)

Para incluir documentos externos (PDFs, imagens, etc.) como contexto:

1. Faça upload usando um storage connector (ex.: S3, Azure Blob, Digibee Storage).

2. Clique no botão (+).

3. Insira o nome do arquivo (ex.: bankslip_1.pdf) ou use Double Braces.

O conteúdo será injetado no prompt como contexto adicional.

3

Configure guardrails (opcional)

Use guardrails quando suas entradas podem conter dados sensíveis (como PII) ou quando você deve controlar estritamente o que é enviado ao LLM.

1. Clique no ícone de engrenagem (⚙) ao lado de Guardrails.

2. Marque as validações desejadas ou use Selecionar Tudo.

Parâmetro	Descrição
Mask on detection	Mascara as PIIs detectadas antes de enviar a entrada para o LLM. Se desativado, a execução é interrompida e um erro é retornado.
CNPJ detection	Detecta padrões de CNPJ (Cadastro Nacional da Pessoa Jurídica) na Mensagem de Usuário, como 00.000.000/0000-00. Não valida a lógica numérica.
Credit Card detection	Detecta padrões de números de cartão de crédito na Mensagem de Usuário, variando de 13 a 19 dígitos. Não realiza validação de checksum (Luhn).
IP detection	Detecta padrões de endereços IPv4 e IPv6 na Mensagem de Usuário. Não valida rede nem faixa de IP.
Datetime detection	Detecta padrões de data/hora na Mensagem de Usuário, como 2025-11-05, 05/11/2025 ou Nov 5, 2025. Não valida a lógica da data/hora.
IBAN code detection	Detecta padrões de IBAN (International Bank Account Number) na Mensagem de Usuário, como GB82WEST12345698765432. Não realiza validação de checksum.
CPF detection	Detecta padrões de CPF (Cadastro de Pessoa Física) na Mensagem de Usuário, como 000.000.000-00. Não valida a lógica numérica.
Email detection	Detecta endereços de e-mail na Mensagem de Usuário, como [email protected]. Não valida o domínio nem a existência do endereço.
Crypto Wallet Address detection	Detecta padrões de endereços de carteiras de criptomoedas na Mensagem de Usuário, como endereços Bitcoin que começam com 1 e contêm de 26 a 35 caracteres base58. Não valida checksum nem tipo de blockchain.
Phone number detection	Detecta padrões de números de telefone na Mensagem de Usuário, como (11) 99999-9999 ou [phone]. Não valida operadora nem região.
URL detection	Detecta padrões de URL na Mensagem de Usuário, como http://example.com ou https://www.example.org/path. Não verifica a validade do link.

Na mesma página, você também pode:

• Ativar a validação por Esquema JSON para as respostas. A saída é validada com base no esquema fornecido. Se for inválida, o Agent envia uma nova solicitação pedindo o formato correto. Se o modelo ainda retornar uma resposta inválida, a execução é encerrada com um erro.

• Definir padrões regex personalizados para validar a entrada. Forneça o Nome do Padrão e o Padrão Regex.

Testando seu Agent

Use o Painel de Teste para validar sua configuração antes de executar o pipeline completo.

1. Insira uma Entrada (opcional).

2. Clique em Executar.

Cada teste bem-sucedido consumirá tokens, e a quantidade utilizada é exibida na saída. Se você quiser testar o pipeline inteiro com uma resposta específica do Agent Component, poderá simular essa resposta (mock) durante a execução do pipeline para evitar custos de uso de IA.

Detalhes do Output

Após executar, você verá nos Detalhes do Output:

Logs

Todos os logs do componente ficam agrupados aqui, mostrando tudo o que aconteceu durante a execução. Eles incluem:

• Configuração: Detalhes sobre o provider e as configurações do modelo usadas. Útil para confirmar que o componente está rodando com a configuração esperada.

• Entrada: Informações sobre o contexto de entrada, incluindo ferramentas configuradas e se a recuperação de conteúdo estava habilitada.

• Usuário: A Mensagem de Usuário exatamente como foi recebida, em texto, Markdown ou JSON. Ajuda a validar se o prompt foi enviado corretamente.

• Sistema: A Mensagem do Sistema aplicada à execução, mostrando as instruções que guiaram o comportamento do modelo.

• Chamada de Ferramenta: Informações sobre chamadas de ferramenta feitas durante a execução, incluindo argumentos e resultados.

• Guardrail de Entrada/Saída: Detalhes sobre quaisquer guardrails de segurança aplicados à entrada e saída e como influenciaram a requisição.

Esses logs oferecem uma visão clara de cada etapa da execução e facilitam validar ou revisar o comportamento do Agent.

Output

O resultado da execução em JSON. Você pode buscar campos específicos usando expressões JSONPath.

Configurar ajustes gerais

Esses parâmetros influenciam como o componente se comporta dentro do seu pipeline, e não como o LLM opera.

Eles podem ser acessados na aba Configurações.

Configure o passo

• Nome do Passo: O nome exibido no seu pipeline.

• Alias: Um alias que você pode usar para referenciar a saída deste conector mais tarde usando Double Braces. Saiba mais.

Configure uma resposta mock

Crie uma mock response para testar seu pipeline sem enviar solicitações reais para um LLM.

Isso é útil quando você deseja:

• Testes determinísticos

• Evitar custos de uso

Mocks substituem chamadas reais ao modelo durante a execução do pipeline.

Etapas para criar um mock:

1. Clique em Criar resposta mock.

2. Defina um Nome.

3. Insira o JSON da resposta mock no campo Resposta JSON.

4. Ative Definir como ativo para usar esse mock nos testes.

5. Clique em Criar Resposta Mock para salvar.

Configure o tratamento de erros

Ative Falhar em Erro se quiser que o pipeline pare em caso de falha. Caso contrário, o conector continua e retorna { "success": false } dentro da saída.

Documente o uso do Agent Component

Use a aba Documentação para registrar:

• Casos de uso

• Regras de negócio

• Entradas necessárias

• Exemplos de saída

Tudo pode ser formatado em Markdown.

Perguntas frequentes

Como posso testar e experimentar meus prompts?

Use o painel de testes localizado no lado direito do formulário de configuração do conector. Para orientações detalhadas, consulte o tópico Testando seu Agent.

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 conector gerar resultados imprecisos ou inventados?

Para tarefas críticas, reduza o risco de alucinações seguindo estas melhores práticas:

• Configure parâmetros como Temperature, Top K, Top P, Frequency Penalty e Presence Penalty.

• Divida os processos em etapas menores, por exemplo, gere primeiro e verifique depois. Essa abordagem oferece melhor controle e permite validar os resultados antes de utilizá-los.

• Crie prompts mais eficazes aplicando técnicas de prompt engineering.

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.