chatwoot-develop/progresso/2026-01-16_runbook_faq_lookup_tool.md

Runbook: FAQ Lookup (Captain/Jasmine)

Data: 16/01/2026
Objetivo: documentar como o FAQ Lookup funciona apos o ajuste, para facilitar diagnostico e correcoes futuras.

1. Fluxo esperado (resumo)

1. O agente chama a ferramenta faq_lookup com um query (ou sem query).
2. A ferramenta resolve o melhor texto de busca:
   • usa last_user_message do contexto, se existir e nao for saudacao;
   • senao usa o query passado, se valido;
   • senao busca a ultima mensagem do usuario na conversa.
3. A busca ocorre em @assistant.responses.approved.search(query).
4. Retorna respostas formatadas ou "No relevant FAQs found for: <query>".

2. Onde a logica vive

• enterprise/lib/captain/tools/faq_lookup_tool.rb
• Logs de debug: log/faq_debug.log

3. Requisitos de contexto

Para funcionar de forma confiavel, pelo menos um destes deve existir:

• state[:last_user_message] no tool_context.
• args[:query] ou args['query'] valido.
• conversation.id disponivel no contexto (para fallback).

4. Como o query e resolvido

1. Preferencia 1: state[:last_user_message] (nao-saudacao).
2. Preferencia 2: query explicito (nao-saudacao).
3. Fallback: ultima mensagem recebida na conversa:
   • pega as 10 ultimas mensagens incoming, nao privadas;
   • ignora saudacoes; retorna a mais recente valida.

Saudacoes ignoradas: oi, ola, bom dia, boa tarde, boa noite (normalizadas).

5. Logs importantes

Arquivo: log/faq_debug.log

Entradas esperadas:

• FaqLookupTool CALLED with args: ...
• resolve_query: Using state[:last_user_message] = '...'
• resolve_query: Using explicit query = '...'
• resolve_query: Using fallback = '...'
• SUCCESS: Found X results for '...'
• RETURN: No results for '...'
• RETURN: No query provided

6. Checklist rapido se quebrar

1. Verifique se o tool esta registrado como faq_lookup.
2. Confirme que o tool_context possui last_user_message ou conversation.id.
3. Garanta que o query nao e apenas saudacao (ele sera descartado).
4. Verifique log/faq_debug.log para confirmar o texto usado na busca.
5. Valide se existem responses.approved no assistente.

7. Problemas comuns e acoes

Sintoma: retorna sempre "No relevant FAQs found".
Causas provaveis:

• query vazio (somente saudacao).
• nenhum approved response para o assistente.
• contexto sem conversation.id.

Acoes:

• conferir logs do faq_debug.log;
• testar com query explicito e nao-saudacao;
• validar se os embeddings/indices do FAQ estao ok.