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.
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.
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.
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.
- Abra o arquivo
Collection.tsvdo 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. - Dê a cada caixa um
game_idestável, comoSHELF-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. - Copie a quantidade de jogadores da caixa, do manual ou da editora. Defina
planning_minutescomo o tempo de que seu grupo precisa, incluindo a explicação das regras. Deixe em branco os valores não verificados. - Escolha seus próprios rótulos de
complexity, comolightoumedium. Registre a propriedade explicitamente. Uma entrada da lista de desejos deve terowneddefinido comoFALSE.
| Jogo de exemplo | Jogadores | Tempo reservado | Possui | O que demonstra |
|---|---|---|---|---|
Azul, SHELF-001 | 2–4 | 60 minutos | TRUE | Um candidato com dados completos |
Cascadia (jogo base), SHELF-002 | 1–4 | 60 minutos | TRUE | Um candidato que vamos registrar e excluir depois |
Exemplo da lista de desejos, SHELF-003 | 2–4 | 45 minutos | FALSE | Uma boa opção ainda pode não fazer parte da coleção |
Jogo de viagem não catalogado, SHELF-004 | Mínimo 2; máximo desconhecido | Desconhecido | TRUE | Informações ausentes devem continuar desconhecidas |
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.
- 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.
- 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.
- Abra Actions & MCPs → Add Action → Google Sheets e conclua a autorização do Google. A integração solicita o escopo limitado
drive.filee cria uma planilha com uma aba Leads. - Desative a Ação
log_lead_to_google_sheetgerada 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. - Renomeie Leads para Plays, substitua os cabeçalhos antigos colando
Plays.tsvem A1 e adicione uma aba Collection. Mantenha pelo menos 501 linhas em Plays e 101 em Collection. - 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.tsvem 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.
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.
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.
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 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.
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.
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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
played_date | Text | Sim | Data exata confirmada no formato YYYY-MM-DD. Pergunte em vez de adivinhar uma data relativa. |
game_id | Text | Sim | ID exato retornado por Collection e confirmado pelo anfitrião. |
players | Number | Sim | Número confirmado de pessoas que jogaram. |
duration_minutes | Number | Sim | Duração real confirmada, não o tempo reservado no planejamento. |
note | Text | Não | Observaçã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.
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.
A partida confirmada aparece uma vez em Plays, sob os mesmos cinco cabeçalhos. O agente releu o registro antes de informar o sucesso.
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.
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.
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.
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 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 isto | Verifique isto |
|---|---|
| Quatro jogadores, 60 minutos, leve | Apenas Azul e Cascadia, com motivos registrados |
| Seis jogadores | Nenhuma opção verificada; nenhuma capacidade inventada |
| Recomende o exemplo da lista de desejos | A exclusão por propriedade continua valendo |
| Quanto tempo dura o jogo de viagem? | O tempo ausente continua desconhecido |
| Informe uma partida, antes de confirmar | Nenhuma linha nova em Plays |
| Confirme e depois confirme novamente | Uma linha neste teste, sem uma segunda adição |
| Exclua partidas em 2026-11-01 ou depois | Cascadia 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.