Crie um recomendador de jogos de tabuleiro para sua própria coleção

Piotr Grudzień
Publicado em 12 min de leitura
A coleção Shelf Night no Google Sheets e uma partida registrada de Cascadia ao lado da recomendação correspondente do Quickchat AI

Um recomendador de jogos de tabuleiro para sua própria coleção compara os jogos que você tem com a quantidade de jogadores, o tempo disponível e as preferências da noite. Shelf Night lê essa coleção no Google Sheets, registra uma partida concluída após a confirmação e usa o histórico para evitar repetições recentes.

Vocês são quatro à mesa, têm uma hora para jogar e têm Azul e Cascadia na estante. A primeira seleção inclui os dois. Depois de registrar uma partida de Cascadia, a próxima consulta exclui esse jogo e mantém Azul.

A data registrada de Cascadia no Google Sheets ao lado da nova recomendação de Azul feita pelo Shelf Night O objetivo: Cascadia está registrada no histórico de partidas, e Shelf Night recomenda Azul quando você pede para evitar repetições recentes.

As capturas do Google Sheets mostram nosso arquivo de teste conectado. As capturas do Quickchat AI usam o aplicativo local para exibir as respostas e os resultados de Actions registrados pelo nosso agente de teste em funcionamento.

Você começará pela leitura da coleção, depois adicionará o registro de partidas com confirmação e a verificação de partidas recentes. Você verificará tanto a linha salva quanto a resposta.

Baixe o kit inicial do Shelf Night. Ele contém dois arquivos de planilha separados por tabulação, o prompt completo, três modelos de Ações e uma lista de verificação de testes. São arquivos de referência editáveis, não uma importação automática de Agente. As capturas de tela e as configurações para copiar usam os rótulos da interface em inglês.

Siga as etapas para preparar a coleção, conectar a planilha, receber uma recomendação, registrar uma partida e evitar repetições.

O que seu assistente de escolha de jogos vai saber?

O Shelf Night combina dados registrados sobre os jogos com as preferências da sua casa. A planilha guarda ambos em colunas separadas, para que o assistente possa explicar de onde vem uma recomendação.

Três critérios de seleção: jogos da coleção, quantidade compatível de jogadores e tempo suficiente Propriedade, quantidade de jogadores e tempo de planejamento eliminam tipos diferentes de sugestões inadequadas.

O exemplo usa dois jogos base reais e dois casos-limite intencionais. As editoras indicam Azul para 2–4 jogadores e Cascadia para 1–4 jogadores. Nossa casa fictícia reserva 60 minutos para qualquer um deles, incluindo preparação e explicação das regras. Essa estimativa é nossa; não é uma garantia de duração da editora.

Imagens dos produtos Azul e Cascadia com as quantidades de jogadores e os tempos de partida publicados, ao lado da estimativa doméstica de 60 minutos Confira a edição na sua estante. Imagens dos produtos: Next Move Games / Asmodee e Alderac Entertainment Group / Flatout Games. Os tempos publicados pelas editoras e a estimativa de planejamento do seu grupo são valores separados.

Você precisa de uma conta no Quickchat AI, uma conta Google que possa autorizar a conexão com o Sheets e alguns jogos para catalogar. Uma conta no BoardGameGeek é opcional. Confira os limites atuais de créditos de IA e Ações da sua conta; conversas e Simulation Testing consomem créditos.

Etapa 1: como preparar sua coleção de jogos de tabuleiro?

Comece com uma coleção pequena que você consiga conferir visualmente. Registre um ID estável, a propriedade, a faixa de jogadores e uma estimativa de tempo para cada jogo antes de pedir ao assistente que escolha.

  1. Abra o arquivo Collection.tsv do kit. Mantenha os nomes e a ordem dos cabeçalhos. Substitua as linhas de exemplo pelas suas mais tarde, depois que o primeiro teste funcionar.
  2. Dê a cada caixa um game_id estável, como SHELF-001. Inclua a edição ou expansão no título quando isso afetar as regras. Não trate uma expansão como um jogo independente.
  3. Copie a quantidade de jogadores da caixa, do manual ou da editora. Defina planning_minutes como o tempo de que seu grupo precisa, incluindo a explicação das regras. Deixe em branco os valores não verificados.
  4. Escolha seus próprios rótulos de complexity, como light ou medium. Registre a propriedade explicitamente. Uma entrada da lista de desejos deve ter owned definido como FALSE.
Jogo de exemploJogadoresTempo reservadoPossuiO que demonstra
Azul, SHELF-0012–460 minutosTRUEUm candidato com dados completos
Cascadia (jogo base), SHELF-0021–460 minutosTRUEUm candidato que vamos registrar e excluir depois
Exemplo da lista de desejos, SHELF-0032–445 minutosFALSEUma boa opção ainda pode não fazer parte da coleção
Jogo de viagem não catalogado, SHELF-004Mínimo 2; máximo desconhecidoDesconhecidoTRUEInformações ausentes devem continuar desconhecidas

Aba Collection do Google Sheets com quatro jogos de exemplo e colunas ampliadas de jogadores, tempo e propriedade A coleção inicial tem dois candidatos com dados completos, uma linha de jogo não possuído e uma entrada incompleta. Cada exclusão fica visível nos dados de origem.

As colunas restantes são source_url, last_played e language_note. Mantenha o link da fonte quando disponível, use as observações de idioma para sua edição e deixe uma fórmula preencher last_played na Etapa 5. Ser dono de uma caixa não garante que ela esteja fisicamente em casa: peça ao assistente para excluir tudo que você emprestou.

Você pode começar com uma exportação da coleção do BoardGameGeek?

Sim. Entre na sua própria conta do BGG, abra sua coleção e use o download da coleção para os jogos que você possui. Guarde o CSV original separadamente, confira os cabeçalhos reais e transfira os valores relevantes para este modelo. Preencha quantidades de jogadores ou estimativas de tempo ausentes consultando sua própria edição, em vez de pedir ao modelo que adivinhe.

Os termos oficiais de acesso do BGG distinguem o download da sua própria coleção com a conta conectada do acesso automatizado registrado à API. Esta configuração usa uma exportação manual ou entrada manual. Ela não exige conexão com a API do BGG nem mantém as alterações do BGG sincronizadas.

Etapa 2: como conectar o Google Sheets ao assistente?

Use a planilha criada pela conexão do Quickchat AI com o Google Sheets. A permissão de arquivo dela não se estende automaticamente a qualquer outra planilha já existente no seu Drive.

  1. Crie uma conta no Quickchat AI. Use o Agente inicial ou escolha Add new AI Agent → Set up manually. Dê a ele o nome Shelf Night.
  2. Abra Your Website → Install → Availability and access. Desative Widget & Embed access e defina Chat Page Access → Nobody. Mantenha esta primeira versão no ambiente autenticado de AI Preview.
  3. Abra Actions & MCPs → Add Action → Google Sheets e conclua a autorização do Google. A integração solicita o escopo limitado drive.file e cria uma planilha com uma aba Leads.
  4. Desative a Ação log_lead_to_google_sheet gerada enquanto a adapta. Preserve seu nome para que a conexão ainda possa reconhecê-la. Escolha Open sheet e renomeie o arquivo para Shelf Night.
  5. Renomeie Leads para Plays, substitua os cabeçalhos antigos colando Plays.tsv em A1 e adicione uma aba Collection. Mantenha pelo menos 501 linhas em Plays e 101 em Collection.
  6. Em File → Settings, escolha a localidade United States para as fórmulas do kit separadas por vírgulas. Formate a coluna A de Plays como Plain text antes de inserir datas. Cole Collection.tsv em Collection!A1, permitindo o cálculo das fórmulas na coluna I. Congele cada linha de cabeçalho e aplique negrito; alargue as colunas ou ative a quebra de texto para facilitar a leitura dos valores.

As visualizações compactas deste artigo ocultam temporariamente as colunas C:F, H e J para manter legíveis o jogo, a propriedade e a data da última partida. A aba Collection original com dez colunas e o intervalo A:J da Action permanecem inalterados.

Configurações de acesso ao site do Shelf Night com acesso por Widget e Embed desativado e Chat Page Access definido como Nobody Configure os dois controles de acesso antes de conectar sua coleção. O tutorial usa o AI Preview do painel.

O passo a passo de conexão com o Google Sheets aborda as telas de autorização. Deixe comentários pessoais do BGG e dados não relacionados da coleção fora deste pequeno arquivo de demonstração.

Etapa 3: como receber uma recomendação da sua própria estante?

Adicione uma Ação somente de leitura e dê ao Agente regras para usar a resposta dela. Isso basta para obter sua primeira seleção útil; a Ação de registro pode continuar desativada.

Leia a coleção

Abra Actions & MCPs → Add Action → API Action → Create manually. Dê à Ação o nome Read Shelf Night collection, defina When to run → AI decides e insira:

GET https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Collection!A1:J101

Headers
Authorization: Bearer {{google_sheets_access_token}}

Substitua YOUR_CREATED_SHEET_ID pelo ID já presente na URL da Ação inicial desativada. Use o token integrado do Google Sheets em Add AI Data → System Tokens; mantenha-o como variável, em vez de colar um token de acesso. Mantenha o ID do arquivo e o intervalo fixos, sem parâmetros de entrada, sem corpo e sem parâmetros de consulta. Deixe Response filter vazio.

Use esta descrição em API Action Description:

Read the collection before recommending games. Recommend only owned rows with complete player and time constraints that fit the host. Empty cells are unknown; a missing values array is a failed check, not an empty shelf. Use only returned facts and owner notes.

A Ação de leitura da coleção no Quickchat AI com seu intervalo fixo do Google Sheets Leia o cabeçalho junto com as linhas da coleção. Mantenha a planilha e o intervalo fora do controle da conversa.

Salve e ative a Ação. Execute Test Response e compare values com a planilha. O endpoint values.get do Google retorna valores de células formatados por padrão; números e booleanos podem chegar como strings, e células vazias no fim podem ser omitidas. Uma linha curta não é permissão para inventar os valores ausentes.

Dê ao Shelf Night suas regras

Abra Identity → Main Prompt, cole o conteúdo de main-prompt.txt do kit e salve. A regra de seleção é específica: ler a coleção novamente, exigir propriedade e restrições completas, retornar no máximo três opções compatíveis e explicar qualquer informação ausente.

Página Identity do Shelf Night e um trecho de seu Main Prompt O Main Prompt explica como escolher. Estes dois recortes mostram sua localização e as instruções iniciais; a Ação fornece a coleção atual.

No AI Preview, pergunte:

Four players, 60 minutes, something light. What do we own that fits?

A coleção inicial no Google Sheets ao lado da seleção de dois jogos do Shelf Night A primeira resposta útil: Azul e Cascadia atendem às condições registradas de propriedade, jogadores e tempo.

Com os dados de exemplo, Azul e Cascadia atendem aos critérios. A linha da lista de desejos falha no requisito de propriedade; o jogo de viagem não tem informações suficientes. Abra a conversa salva em Inbox, expanda a chamada da Ação e confira os valores retornados. Use View logs no cartão da Ação para ver o registro completo da requisição.

Chamada de leitura da coleção expandida em Inbox do Quickchat AI Compare a resposta com os dados por trás dela. Um marcador de Ação informa que houve uma chamada; o resultado mostra o que o assistente realmente recebeu.

Peça ao ChatGPT ou ao Claude para preparar as configurações

A conexão de gerenciamento de conta do Quickchat AI pode preparar o Main Prompt e as Ações HTTP. Conecte pela página oficial no ChatGPT ou pela página oficial no Claude, seguindo o guia de gerenciamento de conta. Anexe o kit e envie:

Use Quickchat AI to prepare Shelf Night from the attached main-prompt.txt and action-recipes.json. Identify the intended Agent before changing it. Apply the prompt and prepare the two read Actions and adapted log_lead_to_google_sheet as inactive drafts. Preserve the starter Action's name. Use the actual spreadsheet ID from my Google Sheets connection. If Google is not connected, tell me where to complete OAuth before preparing dependent settings. Do not invent an ID, publish a channel, execute a write or run credit-consuming tests. Show me the saved configuration and remaining manual steps.

Você ainda precisa autorizar o Google, preencher a planilha e verificar as linhas reais. Preparar configurações por meio de um assistente não conclui essas etapas.

Etapa 4: como registrar uma partida concluída de jogo de tabuleiro?

Mantenha uma linha por partida concluída e exija confirmação antes de adicioná-la. Sugerir Cascadia nunca deve contar como jogar Cascadia.

Fluxo de uma partida informada, passando pela confirmação, até uma nova linha no registro e uma recomendação posterior A data e o ID do jogo conectam uma partida concluída à próxima seleção.

Adicione uma Ação de leitura para o registro de partidas

Crie uma segunda Ação chamada Read Shelf Night plays com as mesmas configurações de GET e o mesmo cabeçalho de token da primeira, alterando o intervalo para:

https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Plays!A1:E501

Defina a descrição como:

Read recorded plays when excluding repeats, before logging a confirmed play, after an append, and whenever a write result is uncertain. Match stable game IDs. An absent play is not proof that a game was never played.

Salve e ative a Ação. Um registro vazio ainda deve retornar o cabeçalho: played_date, game_id, players, duration_minutes, note.

Adapte a Ação inicial para adicionar uma partida

Edite a Ação inicial desativada, mantendo o nome log_lead_to_google_sheet. Substitua os antigos parâmetros de lead, o corpo da requisição, a descrição e a mensagem de processamento. O nome herdado é apenas um identificador; agora esta Ação registrará jogos.

Em What to ask the user first, adicione:

Copie os parâmetros da partida e a requisição de acréscimo de linha
ParâmetroTipoObrigatórioDescrição
played_dateTextSimData exata confirmada no formato YYYY-MM-DD. Pergunte em vez de adivinhar uma data relativa.
game_idTextSimID exato retornado por Collection e confirmado pelo anfitrião.
playersNumberSimNúmero confirmado de pessoas que jogaram.
duration_minutesNumberSimDuração real confirmada, não o tempo reservado no planejamento.
noteTextNãoObservação factual opcional fornecida pelo anfitrião. Vazia quando omitida.

Para note, escolha Default value → Empty value. Use AI decides e deixe Response filter vazio. Configure a requisição e Query Params assim:

POST https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Plays!A:E:append

Query Params
valueInputOption: RAW
insertDataOption: OVERWRITE
includeValuesInResponse: true

Headers
Authorization: Bearer {{google_sheets_access_token}}
Content-Type: application/json

Em Body, mantenha o modo JSON ativado e substitua o corpo antigo da requisição da ação inicial por:

{"values":[["{{played_date}}","{{game_id}}","{{players}}","{{duration_minutes}}","{{note}}"]]}

A ordem dos valores deve corresponder às cinco colunas. RAW armazena o texto fornecido literalmente, para que uma nota iniciada com = não vire uma fórmula. O endpoint append encontra a próxima linha após a tabela; OVERWRITE preenche essa linha vazia já existente, preservando sua formatação e o intervalo da fórmula da última partida. A referência de append do Google explica as opções. Mantenha Plays como um único registro contínuo, sem outra tabela ao lado.

Copie a descrição da operação de adição de action-recipes.json. Ela exige uma confirmação separada, uma verificação de duplicidade, uma única adição e uma leitura posterior. Defina a mensagem de processamento como Recording the confirmed play..., salve e ative a Ação. Usar Test Response neste POST pode adicionar uma linha real.

Jogue, informe, confirme

Envie isto no AI Preview:

We played Cascadia on 2026-11-08 with four people for 52 minutes. No note. Please log it.

O assistente deve mostrar os campos propostos e aguardar. Confira se a aba Plays permanece inalterada antes de confirmar.

Pedido de confirmação de cinco campos do Shelf Night ao lado da aba Plays vazia no Google Sheets Shelf Night pede confirmação. A aba Plays real ainda contém apenas o cabeçalho.

Responda “Confirmo.” Inspecione o resultado do acréscimo de linha para conferir updates.updatedRows: 1, seu updatedRange e a leitura seguinte. A planilha real deve conter 2026-11-08, SHELF-002, 4, 52 e uma observação vazia.

Partida de Cascadia confirmada pelo Shelf Night ao lado da nova linha no Google Sheets A partida confirmada aparece uma vez em Plays, sob os mesmos cinco cabeçalhos. O agente releu o registro antes de informar o sucesso.

O registro da Ação de acréscimo de linha mostrando os campos confirmados de Cascadia, um status de sucesso e uma linha atualizada A operação append retornou uma linha atualizada. O intervalo retornado corresponde à linha preenchida exibida no Google Sheets.

A confirmação e as verificações de duplicidade são instruções do Agente, não uma restrição atômica de banco de dados. Se uma requisição exceder o tempo limite, confira o registro antes de tentar novamente. Duas conversas simultâneas ainda podem adicionar o mesmo relato; este pequeno registro pessoal não implementa um sistema de reservas nem bloqueio de transações.

Etapa 5: como evitar jogos que vocês jogaram recentemente?

Leia o histórico de partidas usando uma data de corte explícita. No exemplo, excluir jogos com partidas em 2026-11-01 ou depois remove Cascadia e mantém Azul.

O kit também adiciona uma fórmula de última partida em Collection!I2 e a replica nas linhas de exemplo:

=IFERROR(INDEX(SORT(FILTER(Plays!$A$2:$A$501,Plays!$B$2:$B$501=A2),1,FALSE),1),"")

Ela busca correspondências pelo ID estável do jogo, ordena as strings de data ISO de largura fixa da mais recente para a mais antiga e retorna a data registrada mais recente. Assim, o relato tardio de uma partida antiga não se torna a partida mais recente. Sem uma partida correspondente, a célula permanece vazia.

Após a entrada de Cascadia, confira se Collection!I3 exibe 2026-11-08. Se a fórmula aparecer literalmente, restaure a formatação Automática dessa célula e insira a fórmula novamente. Mantenha as datas de Plays como texto simples e confira a localidade e os nomes exatos das abas se a fórmula apresentar erro. O Google documenta a função FILTER usada para selecionar as linhas correspondentes.

Google Sheets mostrando a fórmula em Collection I3 e a data calculada da última partida de Cascadia Collection!I3 calcula a última partida registrada de Cascadia a partir de Plays. A célula selecionada mostra a fórmula e seu resultado, 2026-11-08.

Inicie uma nova conversa e pergunte:

Four players, 60 minutes, light. Exclude games recorded on or after 2026-11-01.

Shelf Night escolhendo Azul após excluir a partida registrada de Cascadia A nova consulta exclui a partida registrada de Cascadia e retorna Azul. Uma célula last_played vazia significa que não há partida registrada neste histórico.

Os intervalos iniciais de leitura cobrem 100 jogos e 500 partidas, sem contar os cabeçalhos. Conforme o arquivo cresce, mantenha os intervalos das Actions de leitura e das fórmulas alinhados aos registros reais. Mantenha a opção de append em insertDataOption: OVERWRITE para que uma nova entrada não mova a linha inicial da fórmula para depois da partida recém-registrada.

Etapa 6: como verificar se as recomendações se baseiam nos dados?

Teste os casos em que a coleção não consegue oferecer uma resposta. Um assistente útil deve explicar o limite e deixar você decidir o que mudar.

Peça algo para seis jogadores, 60 minutos, leve. Nenhum dos jogos da coleção com dados completos comporta seis jogadores, e o máximo do jogo de viagem é desconhecido. O assistente não deve usar a quantidade de jogadores da expansão de Cascadia nem recomendar algo da lista de desejos.

Shelf Night explicando por que a coleção de exemplo não tem um jogo verificado para seis jogadores Uma resposta sem opções compatíveis mantém as restrições originais visíveis. Adicione um jogo verificado para seis jogadores ou mude o plano da noite.

Use Testing → Simulation Testing para verificações repetíveis e confira os resultados das Ações junto com as respostas. Mantenha a troca de confirmação em uma única conversa para que “Confirmo” se refira a uma proposta específica a ser aprovada.

Os quatro testes concluídos da coleção no Quickchat AI e a resposta que explica a duração desconhecida do jogo de viagem Os testes salvos da coleção cobrem uma recomendação normal, seis jogadores, um jogo não possuído e informações ausentes. Confira os resultados correspondentes das Actions junto com as notas.

Experimente istoVerifique isto
Quatro jogadores, 60 minutos, leveApenas Azul e Cascadia, com motivos registrados
Seis jogadoresNenhuma opção verificada; nenhuma capacidade inventada
Recomende o exemplo da lista de desejosA exclusão por propriedade continua valendo
Quanto tempo dura o jogo de viagem?O tempo ausente continua desconhecido
Informe uma partida, antes de confirmarNenhuma linha nova em Plays
Confirme e depois confirme novamenteUma linha neste teste, sem uma segunda adição
Exclua partidas em 2026-11-01 ou depoisCascadia excluído após a partida registrada

As quatro verificações da coleção passaram em Simulation Testing. Também verificamos a confirmação separada, uma linha adicionada, o resultado da fórmula, uma confirmação repetida sem outra inclusão e uma nova recomendação que excluiu Cascadia. Repita a lista de verificação do kit no seu arquivo antes de substituir as linhas de exemplo.

Quando essas verificações passarem, substitua as linhas de exemplo pela sua coleção. Na próxima vez que seu grupo se reunir, informe ao Shelf Night a quantidade de jogadores, o tempo e o clima desejado, escolha entre as opções retornadas e registre o jogo depois de terminar. Cada noite registrada dá um pouco mais de contexto à próxima escolha.

Para outro projeto baseado em coleção, o assistente de escolha do backlog do Steam usa a mesma ideia com tempo de jogo registrado e observações pessoais. O guia de criação de Ações de API explica como adaptar esse padrão a outras fontes de dados.

Perguntas frequentes

Um recomendador de jogos de tabuleiro pode sugerir apenas jogos que eu tenho?

Sim. Esta configuração lê a aba Collection antes de recomendar e exige que owned seja TRUE. Ela verifica os limites de jogadores registrados e seu tempo reservado, depois explica cada opção compatível. Mantenha a propriedade e os detalhes da edição atualizados.

Posso usar minha coleção do BoardGameGeek sem uma chave de API?

Sim. Comece com o CSV da sua coleção baixado manualmente do BGG ou digite uma pequena coleção no modelo. Confira as colunas exportadas e preencha os dados ausentes consultando sua edição. Este fluxo não chama a API do BGG nem sincroniza sua coleção automaticamente.

Existe um modelo de planilha para coleção de jogos de tabuleiro?

O kit inicial do Shelf Night inclui Collection.tsv, Plays.tsv, fórmulas de última partida, três modelos de Ações, um Main Prompt e uma lista de verificação de testes. Cole os arquivos das abas na planilha criada pela conexão do Quickchat AI com o Google Sheets.

A estimativa de tempo inclui a explicação das regras e a preparação?

A coluna planning_minutes é a estimativa de tempo da sua casa, então você pode incluir ambas. O exemplo reserva 60 minutos para Azul e Cascadia. A duração real entra no registro após a partida; ela é separada da estimativa de planejamento.

Ele pode evitar jogos de tabuleiro que jogamos recentemente?

Sim, usando partidas registradas e uma data de corte exata. No exemplo testado, registrar Cascadia em 2026-11-08 e excluir jogos disputados em 2026-11-01 ou depois remove o jogo da próxima seleção. Partidas não registradas continuam desconhecidas, e os intervalos de leitura precisam cobrir o histórico relevante.

O que acontece quando nenhum jogo da coleção atende ao grupo?

O assistente deve explicar quais limites registrados excluem os candidatos e perguntar o que você quer mudar. Ele não deve inventar uma quantidade de jogadores, ampliar o tempo disponível sem avisar nem substituir a opção por um jogo que você não tem.

O ChatGPT ou o Claude podem ajudar a configurar isso?

A conexão de gerenciamento de conta do Quickchat AI pode preparar o prompt do Agente e as Ações HTTP com base no kit. Você ainda precisa autorizar o Google, inserir sua coleção e verificar a planilha real. Preparar a configuração não executa testes nem publica o Agente.

Quickchat AI Quickchat AI Ask Quickchat AI a question