Agente de Coleta

Papel e localização

Coleta transforma a qualificação técnica em cadastro confirmado para continuidade comercial. Opera em DATA_COLLECT e CONFIRM. Seu builder é build_coleta_system_prompt(), em src/core/agents/coleta/system_prompt.py; ações são interpretadas por dispatch_coleta() e a confirmação final por execute_confirm_action().

O prompt recebe telefone do WhatsApp, segmento, cadastro parcial, intenção, identidade, horário e packages. A assinatura também recebe serviço e qualificação; no texto atual do builder esses parâmetros não são interpolados como blocos próprios. O histórico do encadeamento continua sendo parte importante do contexto técnico.

Campos e coleta

_BASE_FIELDS contém nome, email, telefone, cpf_cnpj, endereco, estado, cidade, cep. O agente deve pedir todos os campos ainda pendentes na mesma mensagem, aceitar respostas parciais e não repetir informação já registrada. O telefone aparece no prompt para confirmação, não para exigir redigitação.

descricao_solicitacao é gerada ao apresentar o resumo e é obrigatória na validação de finalização. Complementos de prompt: agricultor AGRO fornece hectares, producao_principal, problema_observado; nutricionista HUMANO pode fornecer instagram_profissional e clientes_por_semana. Os campos de nutricionista também são condicionais na qualificação dos serviços GoYou. Os complementos agrícolas não são checados em _first_invalid_field(); são instrução de coleta.

Código	Comportamento
1	Merge cadastral; DATA_COLLECT
2	Merge cadastral e CONFIRM; apresenta resumo
3	Correção com merge; retorna/mantém DATA_COLLECT
4	Executa confirmação composta, validações e integrações
5	Handoff default incerteza
6	Responde dúvida e vai para DATA_COLLECT, sem merge nessa ação
97, 98, 99	Confirma assunto, muda após confirmação, solicita package

Os campos aceitam forma aninhada cadastral_data ou solta. A forma aninhada prevalece quando presente. No caso s=2, o dispatcher não verifica completude do resumo; a validação programática completa ocorre em s=4.

Validação de confirmação

src/core/application/confirm_action.py::_first_invalid_field() verifica os campos em ordem e retorna apenas o primeiro problema:

Campo	Regra programática
nome	String com pelo menos 3 caracteres após trim
email	String aceita por is_valid_email
cpf_cnpj	Documento aceito pelos validadores CPF/CNPJ
cep	Formato aceito por is_valid_cep
estado	UF/nome reconhecido por is_valid_uf; normalização para duas letras
telefone, endereco, cidade	Strings não vazias
descricao_solicitacao	String não vazia

Falha incrementa retry_count e devolve uma pergunta fixa, sem pedir à IA para gerar a correção. Normalmente mantém CONFIRM; na terceira falha faz handoff por incerteza. O código não zera genericamente esse contador depois de uma correção parcial, portanto é cumulativo na sessão para esse fluxo.

Sucesso e efeitos

sequenceDiagram
    participant C as Cliente
    participant A as Coleta
    participant U as ConfirmAction
    participant R as CRM
    participant E as eGestor
    participant D as DynamoDB
    C->>A: Confirma dados
    A->>U: s=4 + cadastral_data
    U->>U: Validar, preparar payloads e resumo
    U->>U: Guard antes das integrações
    U->>R: Upsert contato
    U->>E: Upsert cliente
    U->>D: Caller persiste HANDOFF_PENDING e intenção CRM
    Note over R,D: Deal será projetado pelo worker crm_sync

Contatos CRM/eGestor podem ter efeito externo antes da persistência final; o callback de guard delimita o ponto anterior à primeira mutação. A sequência prossegue depois de iniciada. Sucesso guarda egestor_payload, hubspot_payload (contact e deal) e resumo; falha de API usa api_failure e encaminha. A notificação é posterior à persistência no caso de uso.

ConfirmOutcome.terminal=True significa encerrar o turno automatizado. Não significa que HANDOFF_PENDING é um estado terminal do domínio. Flags egestor_synced/hubspot_synced não são comprovação universal de sucesso desta função: a projeção CRM mantém seu próprio status, e a confirmação não atualiza automaticamente todas as flags antigas.

Exemplos fictícios e erros

{"s":1,"cadastral_data":{"nome":"Pessoa Exemplo","email":"teste@example.invalid"}}Registrei seu nome e e-mail. Pode enviar os dados de contato e endereço que faltam?

{"s":3,"cadastral_data":{"estado":"Paraná"}}Atualizei o estado informado. Vamos conferir o restante do cadastro.

Esses exemplos de mensagens são compatíveis com merge. Para s=4, um placeholder <CPF_FICTICIO> é deliberadamente inválido e provocará correção de documento; exemplos documentais não são dados prontos para escrita real. Um aceite sem documento válido não pode ser apresentado como sucesso de integração.

Uma dúvida em CONFIRM com s=6 muda para DATA_COLLECT, preservando os campos, e exige retornar ao resumo/aceite no diálogo. A regra é importante para testar conversas interrompidas por perguntas.

Contexto, limites e testes

Todos os packages ativos podem ser solicitados; exemplos típicos são CLICKSIGN_PROCESS, GOGENETIC_YOU, SAMPLE_INSTRUCTIONS e PRICING_RULES. A Coleta não assina documentos nem gera orçamento final; explica etapas descritas na KB e prepara dados para a equipe. Para saúde humana, guards mantêm limites clínicos independentemente do package.

Testes: tests/unit/agents/test_system_prompts.py, tests/unit/application/test_action_mapping.py, test_confirm_action.py, test_validators.py e test_process_message_use_case.py. Preserve regressões de normalização de UF, cadastro incompleto, terceira falha, confirmação antes de notificar e erro de notificador. Ao mudar campo obrigatório, atualize _BASE_FIELDS, validação final, payload builders, prompt e fixtures. Veja payloads e integrações.