Visão geral¶
O GoGenetic Agente Digital realiza pré-atendimento comercial por WhatsApp. O cliente conversa com três agentes de IA especializados, mas é o core Python que valida os resultados, controla o estado, persiste a conversa e decide quando acionar integrações ou pessoas.
Um percurso completo¶
- O webhook valida e normaliza o evento recebido da Meta.
- A fila FIFO organiza os turnos por telefone; receipts evitam reprocessar o mesmo evento.
- O orquestrador recupera ou inicia a sessão e seleciona Triagem, Qualificação ou Coleta.
- O agente retorna um JSON de controle seguido do texto ao cliente. O parser e o dispatcher verificam esse contrato.
- Após qualificação e confirmação, o sistema prepara os dados de CRM/eGestor e o handoff. Um worker também projeta a evolução da sessão no CRM de forma assíncrona.
- Operadores autenticados atendem a conversa em
/atendimentoaté sua finalização.
Cada turno pode pedir contexto adicional, permanecer na etapa atual ou escalar uma falha. A máquina de estados define transições legais; uma resposta do modelo não pode criar uma transição arbitrária.
Escolha o ambiente¶
| Ambiente | Como é executado | Persistência | Chamadas externas |
|---|---|---|---|
| Documentação | MkDocs em technical-docs/ |
Arquivos Markdown | Não precisa de credenciais da aplicação |
| Dashboard local | scripts/dashboard.py + FastAPI |
DynamoDB em memória via moto | Chat usa OpenAI; demais adapters dependem de flags |
| Testes unitários/replay | pytest em paths explícitos | Fixtures e moto isolados | Doubles/stubs, sem IA real |
| Aplicação AWS | Recursos de template.yaml |
DynamoDB e filas AWS | Providers habilitados na configuração implantada |
O launcher local não executa a cadeia HTTP API → webhook → SQS → Lambda. Ele chama o caso de uso a partir do emulador. Para validar assinaturas, ordering, retries e consumo de filas, use os testes específicos e uma homologação separada.
Pré-requisitos¶
Para desenvolver a aplicação, siga Python 3.12, a versão de runtime do SAM e da CI. O pyproject.toml aceita >=3.12, mas isso não comprova compatibilidade de deploy com toda versão mais nova. Git e um terminal são suficientes para instalar o ambiente; Docker não é necessário para o launcher que usa moto.
O chat depende de uma chave OpenAI válida e gera chamadas cobradas pelo provider. Os cenários de fixture podem ser usados sem enviar mensagens à IA. AWS CLI, SAM CLI e credenciais AWS só entram no percurso de deploy ou na execução deliberada contra recursos AWS.
Ordem sugerida de leitura¶
- Ambiente local: preparar venv e iniciar o processo.
- Configuração: entender de onde vêm as flags e os segredos.
- Primeira execução: reconhecer sucesso, erro e efeitos esperados.
- Fluxo da mensagem: acompanhar os handlers e o core.
- Estrutura do projeto: localizar o módulo a alterar.
Fontes: README.md, pyproject.toml, scripts/dashboard.py, src/emulator/app.py, src/core/application/process_message_use_case.py, template.yaml, tests/conftest.py.