Assistente Comercial de Pet Shop

Aplicação demonstrativa de atendimento para pet shop. Ela usa agentes de IA para receber mensagens, identificar a intenção do cliente e gerar respostas adequadas para vendas, suporte e relacionamento pós-venda. A interface é uma conversa web em Gradio, com ações extras que simulam gatilhos de um CRM.

O que a aplicação cria

Ao iniciar, o projeto disponibiliza uma interface de chat com:

• respostas a mensagens de clientes, roteadas por intenção;
• recomendações de produtos e serviços do catálogo local, incluindo preço e disponibilidade;
• atendimento de dúvidas operacionais, como horário, endereço e trocas;
• uma mensagem de follow-up para contatos inativos há 24 horas;
• uma mensagem de pós-venda para coletar feedback;
• sinalização de encaminhamento para atendimento humano quando necessário.

É um protótipo: não envia mensagens pelo WhatsApp, não grava conversas em banco de dados e os botões de CRM são simulações locais.

Arquitetura e fluxo

O núcleo da aplicação é o CrewAI. Cada atendimento é executado como uma Crew com um único agente e uma tarefa construída a partir do contexto atual. O módulo orchestrador.py decide qual agente executar e aplica as regras de transferência.

Mensagem do cliente
        |
        v
Classificador
  |       |        |
vendas  suporte  humano
  |
consulta opcional ao catálogo

Agentes

Agente	Responsabilidade
classifier	Recebe a mensagem, dá boas-vindas quando necessário e classifica a intenção. Não vende.
sales	Recomenda produtos e serviços, contorna objeções e conduz ao fechamento ou agendamento.
support	Responde questões operacionais e acolhe reclamações, sem fazer venda.
post_sales	Solicita feedback após uma compra ou serviço e promove relacionamento.

As personas estão em src/config/agents.yaml, e as instruções e formatos de saída em src/config/tasks.yaml.

Eventos do orquestrador

Evento	Origem	Efeito
new_message	Campo de mensagem do chat	O classificador escolhe o destino; o agente especializado responde quando há encaminhamento.
inactive_lead	Botão de teste do CRM	Executa o follow-up pelo agente de vendas.
post_sales	Botão de teste do CRM	Aciona o agente de pós-venda.

Catálogo e contexto

O agente sales recebe a ferramenta Consultar Estoque e Precos. Quando a conversa envolve produtos, serviços, preço ou disponibilidade, ele pode pesquisar automaticamente src/catalogo.json antes de responder. A busca usa uma ou duas palavras-chave e retorna nome, preço, estoque, detalhes e argumentos de venda.

Para manter o prompt compacto, a interface envia apenas as últimas seis interações do chat como histórico contextual (3 mensagens do usuário + 3 interações do agente). Registros visuais dos gatilhos de sistema não são enviados ao modelo. Não há persistência em banco de dados: ao recarregar a página, o histórico é perdido.

Confiabilidade e limites

• Os agentes especializados são instruídos a responder JSON. parse_json extrai o bloco entre chaves com regex e o valida com json.loads, tolerando respostas que venham envoltas em Markdown.
• Se esse JSON vier vazio ou inválido, o orquestrador tenta uma nova decisão pelo classificador. Caso ele também falhe, devolve uma mensagem de erro genérica.
• O sistema aceita somente sales, support e post_sales como destinos internos; decisões desconhecidas são rejeitadas. human produz um handoff terminal.
• Há um limite de MAX_HANDOFFS = 4 transferências entre agentes para evitar ciclos. Ao excedê-lo, o fluxo é encerrado com encaminhamento humano.
• O handoff é apenas sinalizado na interface por enquanto; a integração com uma fila ou atendente humano real ainda não existe.

Requisitos

• Python 3.10 ou superior
• Uma implantação Azure OpenAI compatível com o modelo configurado em src/settings.py
• CrewAI (framework de orquestração de agentes)
• Gradio (interface web)

Instalação

No PowerShell, a partir da raiz do projeto:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Crie um arquivo .env na raiz do projeto com as credenciais da sua Azure OpenAI:

AZURE_API_KEY=sua_chave
AZURE_API_BASE=https://seu-recurso.openai.azure.com/

Se a sua implantação tiver outro nome, ajuste model="azure/gpt-4o" em src/settings.py.

Executar

python src/main.py

Abra no navegador o endereço local exibido pelo Gradio. Use o campo de texto para conversar e os botões do painel de testes para simular follow-up e pós-venda.

Como testar

Objetivo	Mensagem ou ação	Resultado esperado
Saudação	Oi	O classificador cumprimenta e pergunta como pode ajudar.
Venda	Quanto custa o banho para cachorro?	Roteamento para sales, consulta ao catálogo e resposta comercial.
Produto esgotado	Tem ração Gold para gatos?	sales consulta catálogo e informa a indisponibilidade.
Suporte	Qual é o horário de funcionamento?	Roteamento para support e resposta com os dados da loja.
Reclamação grave	Meu pet passou mal depois do serviço e quero falar com alguém.	Encaminhamento humano.
Proteção de loop	Enviar 5+ mensagens que geram transferências contínuas	Após 4 transferências, encaminhamento automático para humano.
Follow-up	Clique em Simular: Cliente inativo há 24h	Mensagem curta de reengajamento gerada pelo agente de vendas.
Pós-venda	Clique em Simular: Serviço Concluído	Mensagem de satisfação gerada por post_sales.

Estrutura

Caminho	Responsabilidade
src/main.py	Inicializa a interface.
src/interface.py	Monta o chat Gradio e transforma ações da tela em eventos.
src/orchestrador.py	Classifica, roteia e controla transferências entre agentes.
src/task_builder.py	Monta as tarefas do CrewAI com o contexto da conversa.
src/settings.py	Carrega credenciais, configura o modelo e instancia os agentes.
src/tools.py	Disponibiliza a busca no catálogo para vendas.
src/catalogo.json	Dados locais de produtos e serviços.

Próximos passos recomendados

• Persistir sessões e histórico em banco de dados ou CRM.
• Substituir o catálogo JSON por uma fonte de estoque e preços em tempo real.
• Adicionar testes para roteamento, parsing de JSON e busca no catálogo.