Agente de Qualificação¶

Papel e implementação¶

Qualificação transforma uma necessidade em serviço canônico e parâmetros suficientes para o comercial. build_qualificacao_system_prompt() está em src/core/agents/qualificacao/system_prompt.py; _service_table() renderiza REQUIRED_FIELDS diretamente de src/core/domain/services.py, evitando manter uma segunda tabela estática de campos no prompt.

AgentInvokerImpl recebe qualification_so_far, segmento, intenção, instância, horário e packages. O histórico vem apenas da sessão atual. A chamada inicia em QUALIFYING, inclusive imediatamente após Triagem s=2, sem esperar nova mensagem do cliente.

Contrato e completude¶

dispatch_qualificacao() interpreta:

Código	Efeito
`1`	Merge de campos técnicos e permanência
`2`	Exige `servico`; verifica nome canônico e campos estáticos/condicionais
`3`	Responde dúvida, sem merge técnico nessa ação
`4`	Handoff; motivo default `incerteza`
`5`	Apresenta alternativas, permanece; `opcoes_apresentadas` não é validado programaticamente
`97`, `98`, `99`	Controles globais de assunto e contexto

Campos podem vir em qualification_data ou diretamente no JSON. Quando o objeto aninhado existe, ele é usado; não é mesclado com campos técnicos soltos no mesmo JSON. _dispatch_qualificacao_s2() combina esses campos com os já persistidos antes de chamar missing_required_fields().

Serviço desconhecido encaminha ao humano por incerteza. Serviço conhecido incompleto continua em QUALIFYING e envia o texto que o agente gerou. Serviço completo atualiza service_identified, faz merge, muda para DATA_COLLECT e chama Coleta no mesmo turno. Se a Qualificação escreveu uma mensagem final, ela é combinada com a solicitação da Coleta.

missing_required_fields() considera ausentes None, strings vazias/em branco e coleções vazias. False e 0 são valores presentes. A função não valida toda semântica: quantidade negativa, alvo fora da KB ou combinação técnica incompatível não são rejeitados apenas por essa checagem de presença.

Regras técnicas do prompt¶

O prompt orienta no máximo duas perguntas por mensagem, reconhecimento dos dados já dados e explicação curta de termos. Microrganismo isolado direciona a Identificação Molecular; material misto a Microbioma conforme objetivo. Dados brutos existentes para análise bioinformática avulsa são tratados como serviço sob medida e encaminhados, sem fingir uma análise de bancada. SSR/corrida de fragmentos e PCR/eletroforese são modalidades distintas de Genotipagem; desenvolver marcadores novos é encaminhamento técnico.

Pedido de kit para uso no laboratório do cliente usa s=4, kit_externo. Não existe serviço canônico “kit” no catálogo. Preços, prazos, primers, alvos e limitações devem vir de packages. Regras de prompt não substituem validação técnica humana: esta página descreve comportamento de software, sem atualizar ou certificar informação científica/comercial da KB.

Para GoYou/HUMANO, os guards vedam diagnóstico, prescrição e promessa clínica, inclusive quando não há package. Não se deve transformar histórico do cliente em recomendação de tratamento.

Packages e exemplos¶

Todos os 15 packages empacotados estão disponíveis; pedidos típicos são TARGETS_QPCR, PRIMERS_SANGER, GENOME_SIZES, SAMPLE_INSTRUCTIONS, CUSTOM_DEVELOPMENT, PRICING_RULES e CLICKSIGN_PROCESS. Um s=99 não muda o estado e não envia texto ao cliente.

{"s":99,"context_needed":"PRIMERS_SANGER"}

Exemplo de etapa parcial fictícia:

{"s":1,"qualification_data":{"tipo_amostra":"DNA de amostra sintética","fitas":2}}Qual primer será utilizado?

Exemplo de conclusão estruturalmente válida, sem alegar que o primer exista no portfólio real:

{"s":2,"servico":"Sanger","qualification_data":{"tipo_amostra":"DNA de amostra sintética","fitas":2,"primer":"primer informado pelo cliente fictício","quantidade_amostras":3}}Registrei os parâmetros da solicitação.

O catálogo confirma presença dos quatro campos e passa para Coleta. A disponibilidade do primer precisa ter sido tratada pelo conhecimento e pelas regras do agente.

Falhas e divergências¶

{"s":2,"servico":"Sanger","tipo_amostra":"DNA"} não avança: faltam fitas, primer e quantidade_amostras. O dispatcher não fabrica uma pergunta corretiva; a mensagem retornada pelo modelo é enviada como veio. Um código inexistente, ausência de servico em s=2 ou formato inválido segue o tratamento de contrato.

Divergência documental

Comentários de action_mapping.py mencionam um contador de três tentativas de qualificação no caso de uso. O caminho atual de campos técnicos incompletos não incrementa retry_count. O limite de três existe na validação cadastral de confirm_action.py; não documente esse limite como garantia de Qualificação.

Testes e manutenção¶

tests/unit/domain/test_services.py cobre campos e condicionais, inclusive False válido. test_action_mapping.py cobre transições incompletas/completas. test_process_message_use_case.py cobre test_qualificacao_s2_chains_to_coleta_same_turn, encadeamento completo, enriquecimento e handoff de dados brutos. test_system_prompts.py verifica instruções de bioinformática, coleta contextual e limites.

Ao adicionar serviço, altere ServiceName, REQUIRED_FIELDS, condicionais e regras de prompt/KB quando necessário, com teste de falta de cada campo e fixture de conclusão. Veja serviços e tutorial.