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.
Visão geral
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:
Explicação de cada opção de configuração
Recursos avançados como tools, recuperação de conteúdo, guardrails e respostas mock
Dica: Você pode encontrar mais exemplos reais do Agent Component na seção Use Cases.
Campos com assistência de IA
Campos marcados com nesta documentação suportam geração de conteúdo com assistência de IA. Na plataforma, esses campos exibem um botão de brilho () no canto superior direito. Use-o para gerar ou editar o conteúdo do campo a partir de uma descrição em linguagem natural, sem precisar escrevê-lo manualmente.
Para usar o assistente:
Clique no ícone de brilho (). Um painel será aberto para você descrever o que precisa.
Insira sua descrição e clique em Gerar.
Quando a geração for concluída, você pode escolher uma das seguintes opções:
Aplicar: Substitui o conteúdo atual do campo pelo resultado gerado.
Tentar novamente: Retorna ao prompt para repetir a mesma descrição ou testar uma nova.
Fechar: Descarta o resultado e mantém o conteúdo atual do campo.
Aplicar um resultado gerado sobrescreve o que estiver atualmente no campo.
Configuração básica
Com os dois passos abaixo, seu Agent já está pronto para tarefas simples e diretas.
Selecione o modelo
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.
Conta
Conta usada para autenticar no provedor LLM. Deve ser cadastrada em Contas. Suporta Secret Key ou AWS-V4 (para Bedrock).
Conta
❌
N/A
Certificado
Conta usada para permitir comunicação HTTPS segura com endpoints externos. Ela deve estar previamente registrada em Contas. Tipo compatível: Certificate Chain.
Conta
❌
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
Os parâmetros disponíveis dependem do modelo selecionado. Cada campo aparece somente se o modelo oferecer suporte a ele. Parâmetros não suportados pelo modelo selecionado são ocultados automaticamente.
Temperatura
Controla a criatividade. Valores mais baixos produzem respostas mais focadas; valores mais altos produzem respostas mais variadas.
Top P
Controla a variabilidade usando limites de probabilidade. Valores mais baixos produzem respostas mais focadas.
Máximo de Tokens de Saída
Define o tamanho máximo da resposta.
Esforço de raciocínio
Controla o quanto o modelo raciocina antes de responder.
Orçamento de raciocínio
Define o número máximo de tokens que o modelo pode usar em seu processo interno de raciocínio.
Incluir raciocínio
Quando ativado, o raciocínio interno do modelo é retornado junto com a resposta final.
Verbosidade
Controla o nível de detalhe e o tamanho da resposta.
Parâmetros Avançados
Os demais parâmetros suportados são agrupados em Parâmetros avançados, recolhidos por padrão. O cabeçalho da seção exibe um badge com o número de parâmetros avançados configurados — por exemplo, Parâmetros avançados · 2 configurados.
Ajuste de amostragem
Top K: Limita o número de tokens candidatos considerados a cada etapa.
Min P: Filtra tokens abaixo de uma probabilidade mínima em relação ao token principal.
Top A: Filtra tokens com base em sua probabilidade em relação ao quadrado da probabilidade do token principal.
Controle de repetição
Penalidade de frequência: Reduz a repetição de palavras idênticas.
Penalidade de presença: Incentiva o modelo a introduzir novos tópicos.
Penalidade de repetição: Aplica uma penalidade direta a tokens que já aparecem na saída.
Controle de saída
Escolha de ferramenta: Controla se e como o modelo utiliza as ferramentas disponíveis.
Sequências de parada: Define sequências que sinalizam ao modelo para parar de gerar conteúdo.
Semente: Define um valor fixo para saídas determinísticas; entradas idênticas retornarão a mesma resposta.
Depuração e observabilidade
Retornar log-probabilidades: Retorna as probabilidades logarítmicas dos tokens de saída.
Top log-probabilidades: Retorna os N tokens mais prováveis e suas probabilidades em cada posição.
Viés de logits: Ajusta a probabilidade de tokens específicos aparecerem na saída.
Parâmetros personalizados
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âmetros Personalizados
Parâmetros personalizados adicionais para enviar à API do modelo.
Pares chave-valor
❌
N/A
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
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.
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
Usar Modo de Resposta Completa
Habilita metadados adicionais no output, incluindo sources e toolExecutions.
Booleano
❌
N/A
Configure as mensagens
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 avançada
As configurações avançadas 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.
Adicione tools
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.
Adicionar ferramentas MCP a partir do Registro
Se você tiver pipelines implantados com o MCP Server Trigger em Test ou Prod, eles estarão disponíveis na aba MCP Do Registro.
Nesta aba, você pode visualizar:
O nome do pipeline
O tipo de autenticação
As tools configuradas e seus respectivos parâmetros
A versão do pipeline implantado
Pipelines MCP que estão sendo usados atualmente como tools no componente (identificados com a tag Em uso)
Para adicionar um pipeline MCP como ferramenta no seu Agent Component, selecione o pipeline desejado e clique em Adicionar Ferramenta. Você será redirecionado para a aba Adicionar Ferramentas MCP para concluir a configuração.
Adicionar Ferramentas MCP
Use esta aba para configurar a sua ferramenta MCP.
Se o pipeline MCP tiver sido selecionado pela aba MCP Do Registro, alguns parâmetros são preenchidos automaticamente:
Nome: Preenchido automaticamente com o nome do pipeline.
URL do Servidor: Preenchido automaticamente com o endpoint do pipeline.
Cabeçalhos: Se um método de autenticação estiver configurado, o campo Chave é preenchido automaticamente de acordo com o tipo de autenticação:
Se API Key estiver habilitado, o header será
apiKey.Se Token JWT estiver habilitado, o header será
Authorization.Se External JWT estiver habilitado, o header será
externalJWT.
Você deve informar manualmente o Valor correspondente.
Consulte a descrição dos parâmetros abaixo para mais detalhes sobre cada opção de configuraçã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
Conta de Certificado
Conta usada para permitir comunicação HTTPS segura com endpoints externos. Ela deve estar previamente registrada em Contas. Tipo compatível: Certificate Chain.
Conta
❌
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
Ferramentas Disponíveis
Este campo está disponível apenas quando um pipeline MCP é selecionado na aba MCP Do Registro.
Ele exibe as ferramentas configuradas no pipeline MCP selecionado. Habilite as ferramentas que você deseja disponibilizar para o Agent Component.
Booleano
❌
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)
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
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
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)
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
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
Adicione arquivos
Para incluir documentos externos (PDFs, imagens, etc.) como contexto:
Faça upload usando um storage connector (ex.: S3, Azure Blob, Digibee Storage).
Clique no botão (+).
Insira o nome do arquivo (ex.:
bankslip_1.pdf) ou use Double Braces.
O conteúdo será injetado no prompt como contexto adicional.
Configure guardrails
Use guardrails quando suas entradas podem conter dados sensíveis (como PII) ou quando você deve controlar estritamente o que é enviado ao LLM.
Clique no ícone de engrenagem (⚙) ao lado de Guardrails.
Marque as validações desejadas ou use Selecionar Tudo.
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 user@example.com. 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 +55 11 99999-9999. 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 Testes no lado direito da página para validar sua configuração antes de executar o pipeline completo.
Para obter orientações detalhadas sobre como realizar testes no Agent Component e explorar todos os detalhes técnicos disponíveis, consulte a documentação Construindo testes no Agent: Datasets, Casos de Teste e Avaliações.
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.
Versionando o componente
O Agent Component oferece suporte opcional a versionamento. Você pode aplicar o Agent diretamente ao pipeline ou salvar versões para acompanhar e reutilizar diferentes configurações ao longo do tempo.
Você pode começar a versionar o componente apenas após salvar o pipeline.
Sem versionamento
Por padrão, o componente é aberto no modo Rascunho. Se você optar por não usar versionamento, configure o componente e clique em Confirmar, no canto superior direito, para aplicar a configuração diretamente ao pipeline.
Apenas a configuração atual é armazenada, e nenhum histórico de versões é criado.
Com versionamento
O versionamento permite salvar, organizar e reutilizar diferentes configurações do Agent Component.
Para criar ou gerenciar versões:
Após fazer alterações no componente, clique em Salvar ao lado do indicador Rascunho, no canto superior esquerdo, e selecione Criar nova versão.
No modal, selecione Criar nova versão ou Atualizar versão existente, dependendo de já existirem versões.
Opcionalmente, adicione tags para ajudar a identificar a versão, como o nome do modelo (por exemplo, OpenAI – gpt-4o).
Clique em Salvar.
Cada versão salva recebe um número de versão, como v1, além das tags definidas. Depois de criadas, as versões não podem ser excluídas.
Para aplicar uma versão salva ao pipeline, clique em Confirmar. A versão atualmente aplicada é marcada com a tag No pipe.
Salvando e aplicando alterações em uma versão
Após atualizar a configuração do componente, você pode escolher como prosseguir:
Salvar (canto superior esquerdo): Salva as alterações em uma versão e mantém o componente aberto para edições adicionais.
Salvar e Confirmar (canto superior direito): Salva as alterações em uma versão e a aplica imediatamente ao pipeline.
Você pode acessar qualquer versão criada a qualquer momento pelo canto superior esquerdo para carregar, revisar ou comparar versões anteriores.
Fazendo o deploy de uma versão
Ao fazer o deploy de um pipeline que inclui um Agent Component com versões, o deploy usa automaticamente a versão atualmente aplicada ao pipeline.
Dica: Para confirmar qual versão está aplicada, abra o componente e verifique qual versão está marcada com a tag No pipe.
Depois que uma versão é implantada, ela não pode mais ser alterada e recebe a tag Bloqueado. As outras versões que não foram implantadas permanecem editáveis e podem ser atualizadas normalmente.
Configurando 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:
Clique em Criar resposta mock.
Defina um Nome.
Insira o JSON da resposta mock no campo Resposta JSON.
Ative Definir como ativo para usar esse mock nos testes.
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.
Documentando 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.
Atualizado
Isto foi útil?