AI Orquestrador

Backend conversacional para concessionária, focado em orquestrar ferramentas de negócio com apoio de LLM.

A proposta do sistema é:

• receber uma mensagem em linguagem natural
• deixar o modelo interpretar a intenção do usuário
• usar ferramentas do sistema quando precisar consultar dados ou executar ações
• devolver uma resposta objetiva ao usuário

Hoje o projeto já implementa esse fluxo, mas ainda inclui camadas de suporte ao modelo, como extração estruturada, memória temporária por usuário, coleta incremental de dados e fallback determinístico de resposta.

Visão Geral

O domínio atual do projeto cobre dois fluxos principais:

• vendas
• revisão/pós-venda

O sistema consegue:

• consultar estoque de veículos
• validar cliente para compra
• avaliar veículo para troca
• criar pedido de compra
• cancelar pedido
• agendar revisão
• listar revisões agendadas
• cancelar revisão
• remarcar revisão

Além do roteamento por tool, o orquestrador também trata cenários conversacionais como:

• mensagens com mais de um pedido na mesma entrada
• coleta de parâmetros em múltiplas mensagens
• reaproveitamento de contexto temporário
• confirmação antes de trocar de assunto
• sugestão de próximo horário quando uma revisão entra em conflito

Stack Atual

Componente	Tecnologia	Observação
Backend	FastAPI	API principal
LLM	Google Vertex AI	Modelos Gemini
Banco de tools	MySQL	Metadados das ferramentas
Banco mock de negócio	MySQL	Veículos, clientes, usuários, pedidos e revisões
ORM	SQLAlchemy	Acesso aos dois bancos
Runtime	Python 3.11+	Aplicação principal
Integração de canal	Telegram Bot API	Long polling via serviço satélite
Containerização	Docker	Ambiente local e deploy

Como o Sistema Funciona

Fluxo principal do /chat:

1. O usuário envia uma mensagem.
2. O OrquestradorService inicializa ou atualiza o contexto temporário do usuário.
3. O sistema tenta separar múltiplos pedidos contidos na mesma mensagem.
4. O LLM ajuda a extrair intenções e entidades estruturadas.
5. Se houver fluxo em aberto, o orquestrador continua a coleta dos dados faltantes.
6. Quando necessário, o modelo escolhe uma tool.
7. A tool é executada pelos handlers do sistema.
8. O resultado é devolvido ao usuário, usando resposta do modelo ou fallback determinístico.

Importante:

• a memória de conversa atual é volátil e fica em memória do processo
• o sistema ainda não persiste histórico conversacional entre reinícios
• o response_formatter responde direto ao usuário; ele não devolve o resultado para o modelo

Estrutura do Projeto

app/
  main.py
  api/
    routes/
      chat.py
      mock.py
      tools.py
      dependencies.py
    schemas.py
  core/
    settings.py
  db/
    database.py
    mock_database.py
    init_db.py
    tool_seed.py
    mock_seed.py
    models/
      tool.py
  repositories/
    tool_repository.py
    user_repository.py
  integrations/
    telegram_satellite_service.py
  services/
    ai/
      llm_service.py
    flows/
      order_flow.py
      review_flow.py
    orchestration/
      orquestrador_service.py
      orchestrator_config.py
      conversation_state_store.py
      prompt_builders.py
      response_formatter.py
    tools/
      handlers.py
      tool_registry.py
    user/
      user_service.py

Organização das Camadas

services/orchestration

Núcleo do orquestrador:

• coordenação do fluxo conversacional
• controle de contexto ativo
• fila de pedidos
• construção de prompts
• fallback de resposta

services/flows

Fluxos incrementais de negócio:

• criação e cancelamento de pedido
• agendamento, listagem, cancelamento e remarcação de revisão

services/ai

Integração com Vertex AI e Gemini.

services/tools

Registro das tools e implementação dos handlers que executam as ações reais.

services/user

Serviços ligados à identificação e persistência de usuários de canal, como Telegram.

Ferramentas Disponíveis

As tools padrão são semeadas a partir de app/db/tool_seed.py:

Tool	Finalidade
consultar_estoque	Consulta veículos por preço, categoria e ordenação
validar_cliente_venda	Valida elegibilidade de compra por CPF e valor
avaliar_veiculo_troca	Estima valor de troca do veículo do cliente
agendar_revisao	Agenda revisão com cálculo de valor
listar_agendamentos_revisao	Lista revisões do usuário
cancelar_agendamento_revisao	Cancela uma revisão por protocolo
editar_data_revisao	Remarca revisão existente
realizar_pedido	Cria pedido de compra
cancelar_pedido	Cancela pedido existente

Bancos e Seeds

O projeto usa duas conexões distintas:

Banco de tools

Responsável por armazenar:

• nome da tool
• descrição
• schema de parâmetros

Arquivos principais:

• app/db/database.py
• app/db/models/tool.py
• app/db/tool_seed.py

Banco mock de negócio

Responsável por armazenar dados fictícios de:

• veículos
• clientes
• usuários
• pedidos
• agendamentos de revisão

Arquivos principais:

• app/db/mock_database.py
• app/db/mock_models.py
• app/db/mock_seed.py

No startup, a aplicação tenta:

• criar as tabelas dos dois bancos
• popular tools
• popular dados mock
• fazer warmup do LLM

Endpoints

Chat

• POST /chat
  • entrada principal do orquestrador

Tools

• GET /tools/
• POST /tools/
• GET /tools/{tool_id}
• DELETE /tools/{tool_id}

Mock

Endpoints diretos para depuração e testes manuais dos handlers:

• POST /mock/consultar-estoque
• POST /mock/validar-cliente-venda
• POST /mock/avaliar-veiculo-troca
• POST /mock/agendar-revisao
• POST /mock/listar-agendamentos-revisao
• POST /mock/cancelar-agendamento-revisao
• POST /mock/editar-data-revisao
• POST /mock/realizar-pedido
• POST /mock/cancelar-pedido

Documentação interativa:

• GET /docs

Execução Local

Sem Docker

uvicorn app.main:app --reload

Com Docker Compose

docker-compose up

Para testar estado conversacional em Redis com Docker Compose:

docker-compose up redis app

Arquivos úteis:

• TEST_CASES.md
• DEPLOY_SERVIDOR.md
• .env.example

Variáveis de Ambiente

Principais variáveis:

Vertex AI

• GOOGLE_PROJECT_ID
• GOOGLE_LOCATION
• VERTEX_MODEL_NAME

Banco de tools

• DB_HOST
• DB_PORT
• DB_USER
• DB_PASSWORD
• DB_NAME
• DB_CLOUD_SQL_CONNECTION_NAME

Banco mock

• MOCK_DB_HOST
• MOCK_DB_PORT
• MOCK_DB_USER
• MOCK_DB_PASSWORD
• MOCK_DB_NAME
• MOCK_DB_CLOUD_SQL_CONNECTION_NAME
• MOCK_SEED_ENABLED
• AUTO_SEED_TOOLS
• AUTO_SEED_MOCK

Telegram

• TELEGRAM_BOT_TOKEN
• TELEGRAM_POLLING_TIMEOUT
• TELEGRAM_REQUEST_TIMEOUT

Estado Conversacional

• CONVERSATION_STATE_BACKEND (memory ou redis)
• CONVERSATION_STATE_TTL_MINUTES
• REDIS_URL
• REDIS_KEY_PREFIX
• REDIS_SOCKET_TIMEOUT_SECONDS

Telegram Satellite Service

Existe um serviço satélite para atendimento via Telegram em long polling.

Arquivo principal:

• app/integrations/telegram_satellite_service.py

Execução:

python -m app.integrations.telegram_satellite_service

Esse serviço:

• consome mensagens do Telegram
• cria ou recupera o usuário interno
• encaminha a mensagem para o OrquestradorService
• envia a resposta de volta ao chat

Estado Atual do Projeto

O sistema já está além de um MVP simples de tool calling. Hoje ele combina:

• decisão assistida por modelo
• execução determinística de tools
• memória volátil por usuário
• fluxos multi-etapas
• múltiplos pedidos na mesma conversa

Pontos que ainda permanecem em aberto:

• persistência real de histórico conversacional
• suíte automatizada de testes
• evolução da autonomia do modelo
• alinhamento contínuo entre prompts, fluxo e regras de negócio