Fortics IA – Guia de Diagnóstico e Solução de Problemas

Este documento apresenta um guia prático para diagnóstico e resolução de problemas no Fortics IA, abordando os principais cenários que impactam o funcionamento da plataforma, o consumo de recursos e a qualidade das soluções implementadas.

Os tópicos abordados são:

1. Visão Geral 
2. Custo de LLM está caro, o que fazer?
   2.1. Revisão do Prompt do Agente
   2.2. Jornada e Insights Ativos
   2.3. Configuração da LLM
   2.4. Atenção nas Integrações (APIs)
   2.5. Escolha Adequada da LLM por Tipo de Agente
3. Agente não está respondendo o que eu quero
   3.1. Clareza do Prompt
   3.2. Qualidade e Completude dos Dados
   3.3. Evitar Respostas Indevidas
   3.4. Definição Clara de Regras e Comportamentos
   3.5. Validação de Fluxo e Contexto
   3.6. Integrações e Dados Externos
   3.7. Escolha da LLM Adequada
4. A Integração do Workflow não está funcionando
   4.1. Exposição do Workflow para Testes Externos
   4.2. Teste Prévio Fora do Fortics IA
   4.3. Debug Passo a Passo (Componentização)
   4.4. Análise de Logs do Workflow
   4.5. Uso da Documentação dos Componentes
   4.6. Estruturação Correta da Requisição no Workflow
5. Análise de Logs no Playground 
6. Para que serve o Agente Curador e Como Configurar
   

1. Visão Geral

Este guia tem como objetivo apoiar na identificação, análise e resolução de problemas relacionados ao uso da plataforma IA.

Ao longo da operação, é comum surgirem cenários que impactam diretamente a performance das soluções, o consumo de recursos e o funcionamento geral das funcionalidades disponibilizadas.

Pensando nisso, este material foi estruturado como um guia prático de diagnóstico, organizado por cenários recorrentes, apresentando para cada um deles:

• Possíveis causas do problema
• Pontos de validação técnica e funcional
• Boas práticas de correção e prevenção

O objetivo é permitir uma análise mais assertiva e direcionada, reduzindo o tempo de investigação e facilitando a identificação da origem dos problemas.

2. Custo de LLM está caro, o que fazer?

O aumento no custo de utilização de LLMs geralmente está relacionado à forma como os agentes, integrações e configurações da plataforma estão estruturados.

Em muitos casos, o consumo elevado não está ligado apenas ao volume de interações, mas principalmente a fatores como tamanho do prompt, escolha do modelo e envio de dados desnecessários para processamento.

Nesta seção, são apresentados os principais pontos de atenção e boas práticas para otimizar o consumo de tokens e reduzir custos operacionais.

2.1. Revisão do Prompt do Agente

O tamanho do prompt impacta diretamente no consumo de tokens, pois ele é enviado integralmente a cada interação com a LLM. Isso significa que, mesmo em conversas curtas, prompts extensos podem gerar consumo elevado de forma recorrente.

Além disso, prompts mal estruturados ou com informações redundantes aumentam o custo sem necessariamente melhorar a qualidade das respostas do agente.

Pontos de atenção:

• Validar o tamanho dos campos: 

• Persona do Agente 
• Papel do Agente

• Identificar conteúdos repetidos ou desnecessários 
• Verificar se há instruções que não são utilizadas na prática 

Boas práticas:

• Manter o prompt objetivo, direto e sem redundâncias 
• Consolidar instruções semelhantes em uma única orientação 
• Priorizar apenas informações essenciais para o funcionamento do agente
  

2.2. Jornada e Insights Ativos

Funcionalidades como Relatório de Jornada e Insights realizam processamentos adicionais sobre as interações, o que pode gerar aumento no consumo de tokens, especialmente em cenários com alto volume de mensagens.

Esse impacto ocorre porque essas funcionalidades utilizam a LLM para gerar análises e registros complementares, ampliando o volume total de processamento além da resposta do agente.

Pontos de validação:

• Verificar se as funcionalidades de Relatório de Jornada e Insights estão habilitadas
• Identificar em quais fluxos estão sendo utilizadas 

• Avaliar a frequência de uso em cenários de alto volume 

Recomendação:

• Manter essas funcionalidades ativas apenas quando houver necessidade real de análise 
• Desativar em fluxos operacionais onde não agregam valor direto

2.3. Configuração da LLM

A configuração do modelo de LLM é um ponto crítico para o controle de custos, pois impacta diretamente o consumo de tokens em funcionalidades que utilizam essa definição de forma global.

A escolha de um modelo mais robusto pode gerar aumento significativo no consumo, mesmo em recursos que não exigem alta complexidade de processamento.

Pontos de atenção:

• Validar qual modelo está configurado em Configurações Gerais
• Considerar o impacto dessa configuração em todas as funcionalidades que utilizam a LLM

Boas práticas:

• Utilizar modelos mais leves, como GPT-4.1 mini, principalmente para:
  • Geração de Insights 
  • Relatório de Jornada 

Importante:
Esses recursos utilizam a configuração global da LLM. Portanto, a escolha de um modelo mais robusto pode impactar diretamente no consumo, mesmo em cenários que não exigem maior capacidade de processamento.

Material complementar:
Para mais detalhes sobre os modelos de LLM e recomendações de uso, consulte a documentação completa sobre o assunto:
Fortics IA - Como Escolher o Melhor LLM para sua Operação 

2.4. Atenção nas Integrações (APIs)

Integrações realizadas via API podem impactar diretamente o consumo de tokens, especialmente quando retornam grandes volumes de dados que são enviados para processamento pela LLM.

Em muitos casos, esses retornos incluem informações desnecessárias para a resposta do agente, aumentando o consumo sem gerar valor adicional.

Problema comum:

• Envio de grandes volumes de dados irrelevantes ou não utilizados na resposta do agente
  

Pontos de atenção:

• Avaliar o conteúdo retornado pelas APIs integradas 
• Identificar informações que não são utilizadas pelo agente 
• Verificar se os dados estão estruturados de forma adequada para consumo
  

Boas práticas:

• Filtrar e tratar os dados antes de enviar para a LLM 
• Retornar apenas os campos realmente relevantes para a resposta 
• Evitar payloads extensos e não estruturados
  

2.5. Escolha Adequada da LLM por Tipo de Agente

A definição do modelo de LLM deve considerar o objetivo e a complexidade de cada agente. Nem todos os cenários exigem o uso de modelos robustos, e a escolha inadequada pode gerar aumento de custo sem ganho proporcional de qualidade.

A utilização de modelos mais avançados deve ser reservada para casos em que há necessidade real de maior capacidade de interpretação, análise ou personalização.

Boas práticas:

• Utilizar modelos mais leves para tarefas simples e operacionais 
• Reservar modelos mais avançados para cenários que exigem maior capacidade cognitiva
  

Exemplos de aplicação

Agentes simples (baixo consumo recomendado):

• FAQ (perguntas e respostas) 
• Consulta de status (pedido, protocolo, financeiro) 
• Coleta de dados estruturados 

Indicação: modelos leves como GPT-4.1. mini

Agentes intermediários:

• Atendimento com múltiplos caminhos 
• Interpretação básica de contexto 
• Apoio a vendas com roteiros definidos 

Indicação: modelos intermediários

Agentes avançados (alto consumo justificado):

• Vendas consultivas 
• Análises mais complexas 
• Interações abertas com maior nível de personalização 

Indicação: modelos mais robustos como GPT-5.2.

Material complementar:
Para mais detalhes sobre os modelos de LLM e recomendações de uso, consulte a documentação completa sobre o assunto:
Fortics IA - Como Escolher o Melhor LLM para sua Operação

3. Agente não está respondendo o que eu quero

3.1. Clareza do Prompt

O agente responde com base no que foi instruído no prompt, e não no que é esperado implicitamente. Isso significa que qualquer ambiguidade, ausência de informação ou instrução incompleta pode impactar diretamente a qualidade da resposta.

Se o direcionamento fornecido ao agente não for claro e objetivo, a resposta tende a refletir essa falta de precisão.

Pontos de atenção:

• Verificar se as instruções estão claras e objetivas 
• Identificar possíveis ambiguidades no prompt 
• Garantir que todas as orientações necessárias estão explicitamente definidas

Regra de ouro:
O agente responde o que foi pedido, não o que era esperado.

 
3.2. Qualidade e Completude dos Dados (Base de Conhecimento)

A qualidade das respostas do agente está diretamente relacionada à disponibilidade e à estrutura das informações fornecidas. Quando os dados são incompletos, inconsistentes ou não estão acessíveis no momento da interação, o agente tende a gerar respostas imprecisas ou insuficientes.

Para garantir um bom desempenho, é fundamental assegurar que todas as fontes de informação estejam corretamente configuradas e contenham os dados necessários.

Fontes de dados:

• Base de conhecimento (RAG) 
• Prompt 
• Integrações 

Pontos de validação:

• O conteúdo necessário para a resposta está disponível? 
• As informações estão claras e bem estruturadas? 
• Os dados estão acessíveis no momento da resposta? 

Importante:
Na ausência de dados adequados, o agente pode tentar completar a resposta com base em inferência, o que aumenta o risco de imprecisão. Por outro lado, quando os dados estão completos e bem estruturados, a tendência é de respostas mais assertivas e confiáveis.

3.3. Evitar Respostas Indevidas

Quando o agente é instruído a responder sobre um tema sem que as informações necessárias estejam disponíveis, há uma tendência de geração de respostas incorretas ou imprecisas.

Esse comportamento ocorre porque o agente tenta atender à solicitação mesmo sem possuir dados suficientes, o que pode comprometer a confiabilidade da resposta.

Pontos de atenção:

• Identificar cenários em que o agente pode não possuir informação suficiente 
• Evitar instruções que incentivem respostas sem base de conhecimento 
• Garantir que existam regras claras para tratamento de ausência de dados 

Boas práticas:

• Incluir regras explícitas no prompt para lidar com falta de informação 
• Orientar o agente a não gerar respostas quando não houver dados confiáveis 

Exemplos:

• “Caso não tenha informações sobre o tema, informe que não possui dados suficientes e direcione para atendimento humano.” 
• “Nunca invente uma resposta sobre o produto X.”

Importante:
A definição dessas regras reduz significativamente a ocorrência de respostas incorretas e aumenta a confiabilidade do agente.

3.4. Definição Clara de Regras e Comportamentos

O agente opera com base em um fluxo lógico definido pelas instruções do prompt. Quanto mais detalhadas e específicas forem essas instruções, maior tende a ser a qualidade e consistência das respostas.

Instruções genéricas ou pouco claras podem levar a interpretações incorretas, impactando diretamente o comportamento do agente.

Pontos de atenção:

• Verificar se as regras estão descritas de forma clara e objetiva 
• Evitar instruções genéricas ou abertas à interpretação 
• Garantir que o fluxo de atendimento esteja bem definido 

Boas práticas:

• Estruturar o comportamento do agente como um passo a passo lógico 
• Definir claramente como o agente deve agir em cada etapa da interação 
• Incluir orientações específicas para cenários comuns e exceções 

Exemplo:

• Atenda bem o cliente(inapropriado, pouco detalhado)

• Cumprimente, identifique a necessidade, responda com base na base de conhecimento e, se não souber, direcione para atendimento humano(apropriado, específico edetalhado)

Importante:
O agente deve ser tratado como um recurso que executa exatamente o que foi definido. Quanto mais específico for o direcionamento, maior será a assertividade das respostas.

3.5. Validação de Fluxo e Contexto

O correto funcionamento do agente depende da consistência do fluxo definido e do contexto disponível durante a interação. Problemas nesses pontos podem comprometer a continuidade da conversa e a coerência das respostas.

Falhas no contexto ou conflitos entre regras podem fazer com que o agente perca informações importantes ou adote comportamentos inconsistentes ao longo da jornada.

Pontos de atenção:

• Verificar se o agente está recebendo o contexto correto da conversa 
• Identificar possíveis perdas de informação entre interações 
• Avaliar se existem regras conflitantes ou incoerentes entre si 

Boas práticas:

• Garantir que o fluxo de atendimento esteja bem definido e consistente 
• Revisar regras para evitar sobreposição ou conflito de instruções 
• Validar o comportamento do agente em diferentes etapas da conversa 

Importante:
A consistência entre contexto e regras é essencial para garantir respostas coerentes e uma experiência contínua ao longo da interação.

3.6. Integrações e Dados Externos

As integrações com sistemas externos são uma das principais fontes de dados para o agente, e sua qualidade impacta diretamente a assertividade das respostas.

Dados incorretos, mal estruturados ou de difícil interpretação podem comprometer o entendimento do agente e resultar em respostas inconsistentes ou imprecisas.

Pontos de atenção:

• Verificar se as integrações estão retornando dados corretamente 
• Validar se os dados estão estruturados de forma clara e consistente 
• Avaliar se o agenteestáinterpretando corretamente as informações recebidas

Boas práticas:

• Garantir que os dados retornados pelas APIs sejam organizados e relevantes 
• Evitar estruturas complexas ou ambíguas que dificultem a interpretação 
• Validar cenários reais para confirmar o comportamento do agente com dados externos 

Importante:
Dados mal estruturados ou confusos impactam diretamente a qualidade da resposta, mesmo quando o prompt e as regras estão corretamente definidos.

3.7. Escolha da LLM Adequada

A escolha do modelo de LLM pode influenciar na qualidade das respostas do agente, especialmente em cenários que exigem maior capacidade de interpretação ou análise.

Modelos mais simples podem apresentar limitações ao lidar com instruções complexas, enquanto modelos mais avançados podem melhorar o desempenho — desde que o problema não esteja relacionado à ausência de dados ou à definição inadequada de regras.

Pontos de atenção:

• Avaliar se o modelo atual é compatível com o nível de complexidade do agente 
• Identificar limitações do modelo em cenários mais avançados 
• Evitar utilizar modelos mais robustos sem necessidade 

Importante:
Antes de alterar o modelo de LLM, é fundamental validar:

• Prompt 
• Dados 
• Regras 

A troca de modelo deve ser considerada apenas após garantir que esses três elementos estejam corretamente definidos.

Material complementar:
Para mais detalhes sobre os modelos de LLM e recomendações de uso, consulte a documentação completa sobre o assunto:
Clique aqui e entenda Como Escolher o Melhor LLM para sua Operação

4. A Integração do Workflow não está funcionando

4.1. Exposição do Workflow para Testes Externos

A exposição do Workflow por meio de uma rota permite validar sua execução de forma independente, sem a necessidade de interação com o agente.

Essa abordagem facilita a identificação de problemas, isolando a camada de integração e permitindo testes mais controlados.

Para expor um Workflow e permitir sua execução em testes externos, siga o fluxo abaixo na plataforma:

1. Acesse o menu Workflows
2. Clique em Rotas
3. Selecione Criar nova rota
4. Defina o caminho da rota (identificar único da rota)
5. No campo Workflow, vincule o Workflow desejado à rota criada
6. Clique em Salvar

Pontos de atenção:

• Garantir que o identificador da rota seja único e representativo 
• Verificar se o Workflow vinculado está corretamente configurado para execução independente

Ferramentas recomendadas:

• Postman
• Insomnia

Benefício:
Permite validar a integração de forma isolada, facilitando a identificação de falhas sem depender do fluxo completo do agente.

 
4.2. Teste Prévio Fora do Fortics IA

Antes de implementar uma integração dentro do Workflow, é fundamental validar a requisição em ferramentas externas. Esse processo garante que todos os parâmetros estejam corretos antes da configuração na plataforma.

A validação prévia reduz o risco de erros durante a implementação e facilita a identificação de problemas na origem.

Pontos de atenção:

• Estruturar completamente a requisição antes de implementar no Workflow 
• Validar todos os elementos da integração: 
  • Endpoint
  • Headers
  • Body 
  • Autenticação 

Ferramentas recomendadas:

• Postman
• Insomnia

Regra prática:
Se não funciona fora, não funcionará dentro.

4.3. Debug Passo a Passo (Componentização)

Em integrações mais complexas, compostas por múltiplos componentes (como REST, Code, entre outros), o processo de debug deve ser realizado por etapas, e não de forma completa de uma única vez.

A validação isolada de cada componente permite identificar com maior precisão onde está a falha no fluxo.

Pontos de atenção:

• Evitar testar todo o fluxo de uma única vez 
• Isolar componentes para validação individual 
• Identificar em qual etapa o erro ocorre 

Como fazer:

• Testar o fluxo componente por componente 
• Inserir componentes de: 
  • Retorno de rota
    
  • Finish
• Posicionar esses componentes logo após o ponto que deseja validar 

Benefícios:

• Permite inspecionar a entrada e saída de cada etapa 
• Facilita a identificação exata do ponto de falha 
• Reduz o tempo de diagnóstico

 
4.4. Análise de Logs do Workflow

 
Os logs são a principal fonte de diagnóstico para identificação de problemas em workflows, pois registram detalhadamente a execução de cada etapa do fluxo.

Através dos logs, é possível entender o comportamento dos componentes e identificar falhas de forma mais direta.

Pontos de atenção:

• Utilizar os logs como primeira fonte de análise em caso de erro 
• Verificar a execução de cada componente do fluxo 
• Identificar inconsistências entre entrada e saída de dados 

Permite verificar:

• Inputs de cada componente 
• Outputs gerados 

• Se o componente foi executado corretamente 

Importante:
Em muitos casos, o erro já está explícito nos logs, o que torna essa análise essencial para um diagnóstico mais rápido e assertivo.

4.5. Uso da Documentação dos Componentes

Todos os componentes disponíveis no Workflow possuem documentação detalhada, que descreve seu funcionamento, parâmetros esperados e exemplos de uso.

A consulta a essa documentação é fundamental para garantir a correta utilização dos componentes e evitar erros de configuração.

Pontos de atenção:

• Verificar os parâmetros esperados por cada componente 
• Validar se os dados enviados estão no formato correto 
• Utilizar os exemplos disponíveis como referência 

Disponível na documentação:

• Parâmetros esperados 
• Exemplos de uso

 
4.6. Estruturação Correta da Requisição no Workflow

A correta configuração da requisição dentro do Workflow é essencial para o funcionamento das integrações. Pequenas diferenças em relação ao padrão definido pela API podem causar falhas na execução.

Por isso, é importante garantir que a estrutura implementada no Fortics IA esteja fiel ao que foi validado previamente em ferramentas externas.

Pontos de atenção:

• Certificar-se de que a requisição está alinhada com a documentação da API utilizada 
• Garantir que segue o mesmo padrão validado nos testes externos 
• Revisar todos os elementos da requisição: 

• Headers
• Autenticação 
• Estrutura do body 
• Tipagem dos dados 

Importante:
Pequenas inconsistências entre o teste realizado fora da plataforma e a configuração no Workflow podem resultar em falhas na integração.  

5. Análise de Logs no Playground

O Playground deve ser utilizado como ferramenta de auditoria sempre que houver problemas no comportamento do agente. Ele permite testar o agente de forma isolada, facilitando a identificação da origem dos erros com maior clareza.

 
Ao simular interações diretamente no Playground, é possível analisar o comportamento do agente sem interferências externas, tornando o diagnóstico mais preciso. 

Pontos de validação:

• Configuração da LLM 
• Base de conhecimento (se está carregada corretamente) 
• Consistência entre modelos utilizados 
• Limite ou saldo disponível no provedor de LLM 

Boas práticas:

• Simular perguntas reais do usuário 
• Validar se as respostas estão coerentes 
• Verificar se o agente está utilizando corretamente a base de conhecimento 
• Observar possíveis mensagens de erro retornadas
  

Recomendação:
Sempre que surgir um problema no agente: 

• Testar o cenário no Playground 

• Identificar o erro retornado 
• Corrigir na origem (LLM, dados, configuração ou saldo) 

Importante:
O Playground funciona como um recurso de diagnóstico direto do agente, permitindo uma análise mais rápida e assertiva dos problemas.
 

6. Para que serve o Agente Curador e Como Configurar

O Agente Curador atua como uma camada de controle de qualidade, sendo responsável por analisar as respostas geradas pelo agente principal e avaliar sua aderência às diretrizes definidas.

Seu papel é garantir que o agente não apenas responda, mas entregue respostas com qualidade, consistência e assertividade.

Avaliações realizadas:

• Correção das respostas 
• Completude das informações 
• Aderência às diretrizes definidas 
• Capacidade de resolução das dúvidas do cliente 

Objetivos:

• Identificar respostas incompletas 
• Detectar respostas incorretas 
• Apontar falhas de interpretação 
• Sugerir oportunidades de melhoria 

Como configurar:

• Dentro do Fortics IA, acesse Insights e selecione “Crie você mesmo com IA”
  

• Definir claramente o objetivo do agente curador 
• Estruturar instruções voltadas para avaliação de qualidade das respostas