Referência de action codes

Contrato

O inteiro s não tem significado isolado: o agente selecionado pelo estado define a tabela. s=4 significa fora do portfólio na Triagem, handoff na Qualificação e confirmação cadastral na Coleta. Fontes: src/core/domain/codes.py, src/core/application/action_mapping.py e src/core/application/process_message_use_case.py.

O dispatcher devolve ActionResult e não faz writes. Os efeitos abaixo são aplicados pelo Orchestrator após guards. Persistir sessão com CRM habilitado também pode criar intenção de projeção comercial, mesmo em uma ação sem chamada HTTP síncrona explícita.

Triagem — TriagemCode

s / enum	Significado	Campos / exemplo mínimo	Efeito e próximo estado
1 NEED_MORE_INFO	Falta contexto inicial	{"s":1}	Resposta, TRIAGE
2 SEGMENT_INTENT_OK	Classificação conhecida	{"s":2,"segment":"PESQUISA","intent":"servico"}	Guarda segmento/intenção; QUALIFYING e próximo agente no mesmo turno para servico; outros intents permanecem TRIAGE
3 HANDOFF	Humano necessário	{"s":3,"handoff_reason":"pedido_cliente","intent":"humano"}	Resumo, notificação após persistência, HANDOFF_PENDING
4 OUT_OF_PORTFOLIO	Serviço não oferecido	{"s":4,"out_of_scope_service":"serviço fictício fora do catálogo"}	Registra demanda e OUT_OF_SCOPE
5 GENERAL_QUESTION_ANSWERED	Dúvida respondida	{"s":5}	Resposta, TRIAGE
97 SUBJECT_CHANGE_CONFIRMATION	Confirmar novo assunto	{"s":97}	Guarda texto pendente, mantém estado
98 SUBJECT_CHANGE	Troca de assunto	{"s":98,"subject_change_confirmed":true}	Fecha e abre outra sessão após guard
99 CONTEXT_NEEDED	Enriquecer contexto	{"s":99,"context_needed":"COMPANY_INFO"}	Carrega package, reinvoca, mantém estado

s=2 exige Segment/Intent válidos. s=3 preserva segment, intent e empresa_detectada quando presentes e válidos, mas não exige todos os campos que o prompt recomenda. Razão inválida cai no default pedido_cliente.

Qualificação — QualificacaoCode

s / enum	Significado	Campos / exemplo mínimo	Efeito e próximo estado
1 QUALIFYING	Coleta técnica	{"s":1,"qualification_data":{"tipo_amostra":"amostra sintética"}}	Merge e QUALIFYING
2 SERVICE_IDENTIFIED	Serviço completo	{"s":2,"servico":"Metagenoma_Shotgun","tipo_amostra":"amostra sintética"}	Serviço conhecido+campos completos: DATA_COLLECT e Coleta no mesmo turno; incompleto: QUALIFYING; desconhecido: HANDOFF_PENDING
3 QUESTION_ANSWERED	Dúvida respondida	{"s":3}	Resposta, QUALIFYING; não faz merge técnico
4 HANDOFF	Especialista necessário	{"s":4,"handoff_reason":"kit_externo"}	Resumo/handoff, HANDOFF_PENDING
5 AMBIGUOUS_OPTIONS	Mais de uma opção	{"s":5,"opcoes_apresentadas":["Sanger","Genoma_Completo"]}	Resposta, QUALIFYING; opções não são validadas como catálogo
97 SUBJECT_CHANGE_CONFIRMATION	Confirmar novo assunto	{"s":97}	Mantém estado e salva texto pendente
98 SUBJECT_CHANGE	Troca confirmada	{"s":98,"subject_change_confirmed":true}	CLOSED na anterior; nova TRIAGE
99 CONTEXT_NEEDED	Enriquecer contexto	{"s":99,"context_needed":"TARGETS_QPCR"}	Reinvoca dentro do orçamento

qualification_data aninhado tem precedência sobre forma plana. Completude significa presença, não validação científica de todos os valores. Falta de campos não incrementa um contador de três tentativas neste caminho.

Coleta — ColetaCode

s / enum	Significado	Campos / exemplo mínimo	Efeito e próximo estado
1 COLLECTING	Cadastro parcial	{"s":1,"nome":"Pessoa Exemplo"}	Merge, DATA_COLLECT
2 SUMMARY_PRESENTED	Resumo para aceite	{"s":2,"descricao_solicitacao":"Solicitação fictícia"}	Merge, CONFIRM; exemplo é estrutural, não cadastro completo
3 CORRECTION	Campo corrigido	{"s":3,"email":"teste@example.invalid"}	Merge e DATA_COLLECT
4 CONFIRMATION_OK	Cliente confirmou	{"s":4} com cadastro já na sessão	Valida; sucesso/erro terminal vai HANDOFF_PENDING; erro de validação antes do terceiro mantém estado
5 HANDOFF	Recusa/incerteza/humano	{"s":5,"handoff_reason":"pedido_cliente"}	HANDOFF_PENDING
6 QUESTION_ANSWERED	Responde e retoma cadastro	{"s":6}	DATA_COLLECT, inclusive vindo de CONFIRM; sem merge
97 SUBJECT_CHANGE_CONFIRMATION	Confirmar novo assunto	{"s":97}	Mantém estado e salva texto pendente
98 SUBJECT_CHANGE	Troca confirmada	{"s":98,"subject_change_confirmed":true}	Fecha e cria nova sessão
99 CONTEXT_NEEDED	Enriquecer contexto	{"s":99,"context_needed":"CLICKSIGN_PROCESS"}	Reinvoca no estado atual

s=4 é uma ação composta: valida nove campos, prepara resumo/payloads, passa pelo guard, atualiza contato CRM e cliente eGestor, guarda intenção de deal e notifica depois da persistência. O prompt orienta usar esse código em CONFIRM; o dispatcher não faz um teste explícito session.state == CONFIRM antes de executar a ação. Não trate essa precondição de prompt como verificação programática adicional.

Códigos globais e falhas

• 97: escreve pending_subject_change_text=original_text, responde pedindo confirmação. Uma resposta comum posterior limpa o pending e continua o fluxo.
• 98: aceita subject_change_confirmed is True ou pending já existente. Sem ambos, vira pedido de confirmação com mensagem fixa. Em troca efetiva, gera resumo, fecha sessão, abre nova com vínculo e reproduz a solicitação original; não apenas a palavra de confirmação.
• 99: exige package resolvível e ativo. Inexistente/sem conteúdo → incerteza. Contador por inbound, default 2; terceira solicitação excede. Não envia o texto posterior ao JSON.

Código fora do enum dispara InvalidAgentCodeError, mapeado para handoff llm_invalid_json no caso de uso. Código válido com transição incompatível ainda pode lançar erro de domínio; validação de código e legalidade de estado são camadas distintas.

Motivos de handoff reais

HandoffReason, em src/core/domain/values.py, aceita: empresa_grande, reclamacao, cancelamento, pos_venda, recusa_texto, incerteza, pedido_cliente, llm_invalid_json, llm_timeout, api_failure, kit_externo, timeout. Alguns são produzidos por fallback/fluxos operacionais e não por exemplos de prompt. No handoff voluntário, motivo desconhecido usa default Triagem=pedido_cliente, Qualificação/Coleta=incerteza.

Verificação e alteração

tests/unit/domain/test_codes.py verifica membership; tests/unit/application/test_action_mapping.py cobre cada dispatcher; test_process_message_use_case.py cobre efeitos reais em repositories; test_confirm_action.py cobre a composição de s=4. Para novo código, atualize enum, dispatcher, prompt, erro, fixture e documentação. Nunca reaproveite um valor sem revisar os três agentes.

Veja parser, máquina de estados e serviços.