Automatize o Reabastecimento com MMF, Databricks Genie e Amazon Quick

O problema que essa solução resolve

No varejo, uma previsão de demanda tem prazo de validade curto. Até o momento em que um planejador exporta o relatório, cruza com a disponibilidade dos fornecedores e percorre dezenas de milhares de Unidades de Manutenção de Estoque (SKUs, do inglês Stock Keeping Units), os produtos mais vendidos já esgotaram. Por muito tempo, o gargalo era a previsão em si. Com os modelos de fundação, esse problema foi resolvido: hoje é possível prever a demanda de um catálogo inteiro sem ajuste por item.

O gargalo se moveu para outro lugar: o espaço entre uma boa previsão e o pedido de compra gerado a partir dela. Esse gap persiste porque a previsão e a ação vivem em sistemas diferentes — a previsão fica em uma plataforma de dados governada, a disponibilidade do fornecedor fica em um feed operacional separado, e o responsável por fazer o pedido não tem acesso a nenhum dos dois.

Para resolver isso, a AWS publicou um walkthrough técnico que descreve a construção de um loop que detecta picos de demanda, decide qual fornecedor pode atender e faz o pedido sem intervenção humana, escalando para revisão humana apenas quando nenhuma regra se aplica. A solução roda sobre Databricks e Amazon Quick, e o repositório de acompanhamento contém tudo o que é necessário para reproduzi-la.

As quatro etapas da solução

A arquitetura é dividida em quatro estágios. O Databricks cuida da previsão, e o Amazon Quick executa os três estágios seguintes em loop, de acordo com um agendamento:

Prever (Forecast): o Many Model Forecasting (MMF) do Databricks serve o modelo Chronos-2 para prever a demanda dos próximos 7 dias para cada SKU.
Detectar (Detect): um Databricks Genie Agent identifica os SKUs em pico de demanda — definidos como aqueles cuja média dos próximos 7 dias é pelo menos 1,5 vez a média dos 14 dias anteriores, e apenas para SKUs cuja média dos 14 dias anteriores seja de pelo menos 1 (um piso que elimina ruído de baixo volume).
Decidir (Decide): o Amazon Quick cruza cada SKU em pico com a disponibilidade em tempo real dos fornecedores armazenada no Amazon S3 Tables — uma capacidade do Amazon Simple Storage Service (Amazon S3) — e seleciona o fornecedor mais barato que consiga cobrir a demanda.
Agir (Act): o Amazon Quick Flows emite um pedido de compra rotineiro via uma API de Pedidos de Fornecedor, ou abre um ticket de revisão humana quando nenhum fornecedor individual consegue cobrir o pico.

Como as peças se encaixam

O Amazon Quick funciona como o elo central da solução — é o único componente que toca os dois mundos. Ele acessa a previsão por meio do Databricks Genie Agent via Protocolo de Contexto de Modelo (MCP, do inglês Model Context Protocol), puxa o feed de fornecedores do S3 Tables e chama a API de Pedidos por meio de um conector OpenAPI, unindo tudo por uma chave de produto compartilhada no momento da decisão — sem copiar dados para um único data warehouse.

O Databricks produz a inteligência. O Amazon Quick age sobre ela.

Pré-requisitos e configuração

Tudo roda a partir do terminal local com as seguintes ferramentas: Databricks CLI 0.299.0+, AWS CLI 2.36.2+, jq 1.7 e uv (ou Python 3.11) para o carregador do feed de fornecedores.

Dois pré-requisitos no nível de conta precisam ser confirmados antes de começar: o usuário do Amazon Quick precisa ter o papel de Autor ou Autor Pro (os conectores MCP e OpenAPI exigem isso), e a identidade no Databricks precisa de permissão CREATE CATALOG no metastore.

Os valores específicos de cada conta são lidos de um arquivo .supply-chain-automation-env, criado uma vez e carregado com source. Dois scripts cobrem todos os passos automatizáveis via CLI: scripts/setup_databricks.sh e scripts/setup_aws.sh. Ambos pausam nos quatro passos que exigem o console: os dois conectores de ação, a concessão de acesso ao S3 Tables e o dataset.

Um detalhe importante de região: a solução deve ser implantada em uma região que suporte as capacidades agentivas do Amazon Quick (conectores de ação, spaces e flows). Consulte a documentação para a lista atualizada.

Construindo o cérebro de previsão no Databricks

A parte de inteligência é inteiramente no Databricks, em três movimentos: executar os notebooks de previsão, expor os resultados via Genie Agent e registrar um aplicativo OAuth para que o Amazon Quick possa acessar esse agente.

Executar os notebooks

Os notebooks 01 e 02 vêm do exemplo fresh_retail_net do acelerador MMF, que serve a previsão zero-shot do Chronos-2 em todo o catálogo. Sobre essas tabelas, o repositório adiciona dois notebooks: o 04 (views do Genie) e o 03 (dimensões). Ao final, o catálogo mmf conterá seis objetos que o Genie Agent consultará:

daily_sales_raw e demand_train (notebook 01)
scoring_output_mv e evaluation_metrics_mv (notebook 04)
product_dim e location_dim (notebook 03)

./scripts/setup_databricks.sh notebooks # importa e executa 04 e depois 03 (execute 01 e 02 do acelerador primeiro)

Criar o Genie Agent

Esta etapa transforma uma tabela de previsões em algo que um usuário de negócios pode questionar em linguagem natural. A definição completa do agente está em genie/genie_space.json: as seis tabelas, as instruções de detecção de pico e uma query de exemplo fixada para garantir respostas determinísticas em execuções agendadas.

./scripts/setup_databricks.sh genie

Registrar o aplicativo OAuth

O Amazon Quick acessa o Genie Agent via MCP usando OAuth de três etapas (delegado ao usuário). Genie queries são executadas como a pessoa que autorizou a conexão. Esta etapa registra um aplicativo OAuth confidencial no Databricks e retorna um Client ID e um segredo para o conector. O segredo deve ser copiado imediatamente, pois o Databricks o exibe apenas uma vez.

./scripts/setup_databricks.sh oauth

Feed de fornecedores e API de Pedidos

O lado de ação precisa de duas coisas que a previsão não fornece: uma visão em tempo real do que os fornecedores podem enviar, e um sistema para onde enviar o pedido.

O feed de fornecedores é um feed operacional independente no Amazon S3 Tables (Apache Iceberg). O carregador gera três fornecedores por produto e cidade em uma janela de 7 dias, produzindo 63.861 linhas de forma determinística. Um conjunto de fornecedores é deliberadamente sub-abastecido para exercitar o caminho de revisão humana.

./scripts/setup_aws.sh feed

A API de Pedidos de Fornecedor é composta por Amazon API Gateway na frente de AWS Lambda e Amazon DynamoDB, com a chave da API armazenada no AWS Secrets Manager. O fluxo a chama para colocar pedidos (POST /orders) ou abrir tickets (POST /tickets). As duas tabelas do DynamoDB são onde os resultados são lidos.

./scripts/setup_aws.sh order-api

Configurando o Amazon Quick

Com o cérebro e os sistemas operacionais prontos, o restante da construção vive no Amazon Quick: a conta, os dois conectores (para o Genie Agent e para a API de Pedidos), a fonte de dados, o dataset e o space que expõem o feed de fornecedores.

Conector Genie Agent (conector MCP)

O Amazon Quick acessa o Databricks Genie Agent por meio de um conector de ação MCP. Os conectores de ação são criados no console do Amazon Quick. Siga os passos de conectores de ação do Amazon Quick, escolha autenticação de usuário (OAuth) e forneça os valores gerados nas etapas anteriores, incluindo o endpoint MCP do Genie, o Client ID e o segredo OAuth.

Conector da API de Pedidos (conector OpenAPI)

O fluxo submete pedidos de compra e abre tickets chamando a API de Pedidos por meio de um conector de ação OpenAPI. Siga os passos de conectores de ação do Amazon Quick e forneça o arquivo order-api/supplier-order-api-openapi-flows.json do repositório. O conector registra duas ações de escrita: SubmitOrder (POST /orders) e CreateTicket (POST /tickets).

Dataset de fornecedores (S3 Tables)

O Amazon QuickSight — a capacidade de business intelligence do Amazon Quick — lê o feed de fornecedores do S3 Tables em modo Direct Query, de modo que cada execução vê a ingestão mais recente, sem cache. Primeiro, é necessário conceder ao Quick acesso ao bucket no console. Em seguida, o script cria a fonte de dados S3 Tables:

./scripts/setup_aws.sh datasource

O dataset é criado no console do Quick escolhendo Direct Query (não SPICE) para manter o feed atualizado. O procedimento completo está em Criando um dataset usando Amazon S3 Tables.

Space de fornecedores e montagem do fluxo autônomo

O passo de busca de fornecedores no fluxo não lê o dataset diretamente — ele lê um Quick Space ao qual o dataset pertence. O script cria esse space e adiciona o dataset supplier_availability a ele:

./scripts/setup_aws.sh space

Com tudo no lugar, o fluxo é criado:

./scripts/setup_aws.sh flow

A estrutura do fluxo (definida em flow/flow_definition.json) é:

Detectar Picos de Demanda: consulta o Genie Agent pelos SKUs em pico.
Processamento de SKU (loop): para cada SKU em pico:
- Buscar Fornecedores: consulta o space S3 Tables.
- Selecionar Melhor Fornecedor: o mais barato cuja capacidade de 7 dias cobre a previsão de 7 dias. Se nenhum cobrir, marca como exceção.
- Emitir Pedido: executa apenas quando a decisão é rotineira.
- Abrir Ticket: executa apenas quando é uma exceção.
- Gerar Resumo do SKU.
Gerar Relatório Consolidado.

Validação

Com os dados de amostra do repositório, uma execução produz seis SKUs em pico, cinco pedidos rotineiros e um ticket de exceção. A exceção é o produto 122 (Nordeste) — o SKU deliberadamente sub-abastecido no feed, onde nenhum fornecedor individual cobre a demanda de 7 dias. Os cinco pedidos rotineiros são os produtos 261, 191, 299_300, 450_300 e 4. Os resultados podem ser confirmados no DynamoDB:

# 5 pedidos: produto, fornecedor e quantidade
aws dynamodb scan --table-name supplier-order-api-orders --region "$REGION" --profile "$AWS_PROFILE_SC" \
  --query "Items[].{product:retailer_product_id.S, supplier:supplier_id.S, qty:quantity.S}" --output table

# 1 ticket: o SKU sub-abastecido
aws dynamodb scan --table-name supplier-order-api-tickets --region "$REGION" --profile "$AWS_PROFILE_SC" \
  --query "Items[].{product:retailer_product_id.S, region:region.S}" --output table

Decisões de design que tornam a solução operacionalmente sólida

Conectar os componentes é a parte direta. Algumas escolhas separam um loop que pode rodar continuamente de uma demo que funciona uma vez — e elas se generalizam além de supply chain:

Coordenar fontes independentes, não consolidar. A previsão, o feed de fornecedores e a API de Pedidos permanecem em seus próprios sistemas, unidos por uma chave de produto compartilhada apenas no momento da decisão. Sem pipeline de ETL (Extração, Transformação e Carga) para quebrar, sem job de sincronização para monitorar, sem bugs de dados desatualizados.
Fixar a query de pico para que a automação seja repetível. O Genie regenera SQL por pergunta — certo para um humano explorando dados, errado para um job agendado que precisa da mesma resposta toda vez. Por isso, a definição do Genie fixa a query de pico e declara explicitamente o piso numérico (média de vendas reais dos últimos 14 dias de pelo menos 1), garantindo que seis SKUs em pico retornem como seis toda vez.
Graduar a autonomia pela decisão. O loop automatiza a maioria previsível e escala o restante: quando um único fornecedor cobre a previsão de 7 dias, o pedido se envia sozinho. Quando nenhum consegue, o SKU vira um ticket.
Não amarrar o design a um único modelo. O loop precisa de uma previsão probabilística que se generalize em um catálogo grande sem ajuste por item. O Chronos-2 entrega isso hoje, mas nada no downstream está amarrado a ele — o loop envelhece bem à medida que os modelos melhoram.

Limpeza dos recursos

Para evitar cobranças contínuas, o script cleanup/cleanup.sh descobre e remove toda a solução em ordem segura de dependências: o fluxo, space, dataset, fonte de dados e conectores do Quick; o Genie Agent, SQL warehouse e catálogo mmf do Databricks; o stack da API de Pedidos (Lambda, DynamoDB e secret); e o bucket S3 Tables. Recursos de nível de conta, como a assinatura do Quick e o aplicativo OAuth do Databricks, são preservados por requererem confirmação explícita.

./cleanup/cleanup.sh

Conclusão

A solução descrita pela AWS entrega um loop de reabastecimento que roda sem um humano no comando: as previsões do Chronos-2 alimentam um Genie Agent que sinaliza picos, e o Amazon Quick reconcilia cada um deles contra o feed de disponibilidade de fornecedores. O Amazon Quick Flows então faz o pedido ou escala a exceção, e o loop inteiro pode ser colocado em um agendamento.

O padrão se generaliza além do varejo: sempre que uma previsão em um sistema precisa ser reconciliada com dados operacionais em outro e transformada em ação, essa estrutura detectar-decidir-agir se aplica. O repositório de acompanhamento contém tudo para reproduzir a solução e adaptá-la ao seu domínio.

Fonte

Automate replenishment with MMF, Databricks Genie, and Amazon Quick (https://aws.amazon.com/blogs/machine-learning/automate-replenishment-with-mmf-databricks-genie-and-amazon-quick/)