Monte um localizador de cards com IA Commander com Scryfall

Um localizador de cards Scryfall Commander transforma uma descrição do card de que você precisa em uma busca que você pode inspecionar. Neste tutorial, você vai montar Open Query, um Agent Quickchat AI que mostra sua consulta Scryfall, retorna registros reais de cards e explica por que cada candidato pode servir para o seu deck.

Comece com um espaço em um deck monoverde de Commander. Você quer uma criatura com atropelar e preço abaixo de cinco dólares americanos. Ao final, você poderá digitar esse pedido, abrir os cards retornados e refinar a busca sem decorar todos os operadores.

A parte útil aparece quando o pedido fica mais difícil. “Comprar quando outra criatura entra” parece preciso, mas uma busca pelas palavras enters e draw também encontra cards que fazem outra coisa. Você vai captar essa incompatibilidade e restringir a consulta, usando o texto dos cards retornados como evidência.

O que você vai montar, e do que precisa?

Você vai conectar uma API Action somente leitura ao Scryfall, dar ao Agent suas instruções de busca e testá-lo em uma conversa. A Action chama uma URL fixa. O modelo fornece uma consulta e um número de página. Scryfall retorna os registros dos quais a resposta parte.

1. Crie uma conta no Quickchat AI e um Agent chamado Open Query. Você precisa de créditos de IA disponíveis para conversas e testes. Veja os planos atuais.
2. Mantenha o Identity, o Actions & MCPs e o AI Preview do Agent disponíveis enquanto trabalha. Não é necessário enviar sua coleção de cards.
3. Use a API pública do Scryfall. Você não precisa de uma conta nem de uma chave de API do Scryfall para essas buscas.

O kit inicial contém o Main Prompt, a receita da Action, os caminhos do filtro de resposta e as mensagens de teste. Os exemplos usam texto Oracle em inglês e preços em USD. Mantenha os operadores de consulta e os nomes dos cards como estão ao acompanhar em outro idioma.

Etapa 1: Como transformar um pedido de card em uma consulta Scryfall?

Uma consulta Scryfall combina restrições separadas por espaços. Para nosso primeiro pedido, use:

f:commander id<=g t:creature kw:trample usd<5

Duas escolhas pequenas importam. kw:trample busca pela palavra-chave. o:trample busca pela palavra no texto Oracle. Uma criatura pode mencionar atropelar sem ter essa habilidade. Nós testamos ambos. A busca por texto produziu um conjunto mais amplo.

“Cabe em um deck monoverde” também é diferente de “tem identidade exatamente verde.” A primeira permite cards incolores. Use id=g para a segunda, ou id<=ur para buscar dentro das cores de um comandante azul-vermelho. Essas são restrições de identidade, não uma verificação completa de legalidade do deck.

A referência de sintaxe de busca do Scryfall explica esses operadores. Para este tutorial, mantenha a consulta visível em toda resposta para que você possa notar uma cor omitida, uma moeda inesperada ou uma busca mais ampla do que o seu pedido.

Etapa 2: Como conectar a API do Scryfall ao seu Agent?

Crie uma API Action que envie uma requisição GET ao endpoint de busca de cards do Scryfall. As configurações fixas dela escolhem o provedor e a ordenação. Seus dois parâmetros permitem que o Agent escolha a busca e a página.

1. Abra Actions & MCPs → Add Action → API Action.
2. Use a requisição do construtor abaixo e depois revise as configurações geradas em comparação com a receita. O guia do construtor do API Action explica o fluxo de geração e revisão.
3. Defina API Action Name como Search Scryfall cards.

Create a read-only Scryfall card-search Action using GET https://api.scryfall.com/cards/search. Add required Text query and Integer page parameters. Map q to query and page to page in Query Params. Fix unique=cards and order=name. Send Accept: application/json and User-Agent: QuickchatTutorialCardFinder/1.0 (+https://quickchat.ai). No authentication and no request body. Fetch one page only. Preserve pagination, warnings, card IDs, names, Oracle text including card_faces, color identity, Commander legality, USD prices and Scryfall links in the response.

Defina os dois parâmetros

Em What to ask the user first, adicione estes parâmetros obrigatórios. O Agent pode preenchê-los a partir da conversa. O rótulo não significa que ele precise pedir que você digite a sintaxe bruta da consulta.

Defina o endpoint, os parâmetros de consulta e os cabeçalhos

Selecione GET e insira:

https://api.scryfall.com/cards/search

Em Query Params, adicione as quatro linhas abaixo. Para os valores dinâmicos, use Add AI Data para selecionar o parâmetro que você criou. A notação {{query}} e {{page}} abaixo representa esses chips de parâmetro.

Use os campos de parâmetro de consulta para que espaços, aspas e operadores sejam codificados como valores de parâmetro. Mantenha a URL do endpoint fixa.

Deixe Body vazio. Nenhuma autenticação é necessária. O User-Agent é um nome identificador do cliente, não uma credencial. Use o nome apropriado da sua própria aplicação e a URL de contato ao implantar sua versão.

Mantenha a resposta útil

Uma página do Scryfall pode conter muitos registros. Mantenha os campos de que o Agent precisa, junto com as informações que dizem a ele se existem mais páginas. Expanda Advanced settings e encontre Response filter. Use Add JSONPath e depois o botão de mais para adicionar cada caminho abaixo como uma entrada separada:

$.total_cards
$.has_more
$.next_page
$.warnings
$.data[*].id
$.data[*].name
$.data[*].oracle_text
$.data[*].card_faces
$.data[*].color_identity
$.data[*].legalities.commander
$.data[*].prices.usd
$.data[*].scryfall_uri

Mantenha card_faces. Alguns cards colocam seu texto em faces individuais em vez de no nível superior. Mantenha warnings também: um sucesso HTTP não significa que o Scryfall interpretou cada cláusula como pretendido. A referência do objeto Card descreve esses campos.

Em API Action Description, cole:

Use when a player wants to find real cards matching a confirmed request. Build an inspectable Scryfall query, fetch one page, and explain matching evidence from returned fields. Show the executed query and any returned warnings. Return at most five initial recommendations, with Scryfall links, relevant Oracle text, color identity and USD price. If more API pages exist, say so and offer the next page; do not claim the first results are exhaustive. Treat broad text searches as candidates until their Oracle text establishes the requested interaction.

Salve a Action e verifique se ela está ativa. O guia de anatomia de HTTP Action explica como os parâmetros, a requisição e a descrição funcionam juntos.

Etapa 3: Como o localizador de cards deve explicar seus resultados?

O Agent precisa de instruções para mostrar sua consulta, fundamentar recomendações nos registros retornados e distinguir uma correspondência de palavra de uma interação de regras. Abra Identity → Main Prompt e cole o prompt completo do kit inicial, reproduzido abaixo.

You are Open Query, a Commander card-search helper. Clarify format, color identity and budget currency when needed. Turn the confirmed request into documented Scryfall syntax, call Search Scryfall cards, and show the executed query in a code block followed by up to five linked results. Recommend only records returned by this Action. Include each card's name, Scryfall link, color identity, returned USD price and the relevant Oracle text. Summarize without inventing text or cards. Use periods or semicolons rather than em dashes. Use text on card_faces when present.
For mono-green deck eligibility use id<=g; this includes colorless. For exactly green identity use id=g. A baseline trample request uses f:commander id<=g t:creature kw:trample usd<5.
Separate word matches from rules interpretation. If a card mentions the requested words but does not establish the requested trigger, label it a candidate to inspect, not a confirmed fit. Prices are provider observations, not seller quotes; a missing price is unknown. Say the total result count and whether more API pages exist. Start at page 1. Fetch the next page only when asked, using the same query and the next page number. Never fetch every page automatically. A shortlist is not exhaustive. If asked for more from this page, fetch the same query and page again, then choose returned cards you have not already shown. The next API page is different.
Do not build a full deck, invent cards, or claim a rules ruling. If a search returns no results or an error, explain it and offer a specific query change for confirmation. Inspect response warnings as well as errors. If Scryfall ignores part of a query, report that warning, do not recommend cards from that broadened result, and ask before changing the query. Do not silently retry an altered query. If rate limited, stop and ask the reader to try later.

Agora abra AI Preview e envie:

Find Commander-legal creatures in mono-green color identity with trample, priced below 5 USD.

A demonstração interpretou a elegibilidade para deck monoverde como verde ou incolor. Para identidade exatamente verde, diga isso explicitamente.

Leia a consulta executada antes das recomendações. Ela deve preservar Commander, identidade verde ou incolor, tipo criatura, atropelar e USD abaixo de 5. Abra o link Scryfall de um card e compare o texto relevante, a identidade e o preço com a resposta. O preço é uma observação de consulta para a impressão retornada, não uma cotação de compra.

Os resultados da API são ordenados por nome, não classificados por adequação. O Agent escolhe uma lista curta da página obtida. unique=cards evita listar cada impressão como um resultado separado. Isso não significa que o registro selecionado seja a cópia mais barata que você pode comprar.

Etapa 4: Como corrigir uma busca que encontra a interação errada?

Restrinja a consulta lendo um contraexemplo e adicionando a condição que faltou. Mantenha a distinção entre encontrar cards candidatos e confirmar seu texto durante todo o refinamento.

Pergunte:

Find green cards that draw when another creature enters, under 5 USD.

Uma busca ampla por candidatos é:

f:commander id<=g o:enters o:draw usd<5

Na nossa verificação direta no Scryfall em 10 de novembro de 2026, isso retornou 161 candidatos, incluindo Abundant Growth. A compra dele acontece quando a própria Aura entra. Ele contém as duas palavras, mas não fornece o motor repetível de compra por entrada de criatura que o pedido sugere.

Tente este refinamento:

Keep the same colors and budget. Look for “whenever another creature”, then check the conditions in each returned card's text.

A consulta mais restrita que verificamos foi:

f:commander id<=g o:"whenever another creature" o:enters o:draw usd<5

A busca refinada retornou quatro candidatos. Garruk’s Packleader é uma correspondência condicional útil: a outra criatura precisa ter poder 3 ou maior. Essa distinção deve aparecer na recomendação. Uma estratégia de fichas com muitas criaturas 1/1 pode precisar de outro card.

Adicionar apenas o:"another creature" é menos preciso. Nosso teste ainda encontrou Disciple of Freyalise, cuja própria entrada pode levar você a sacrificar outra criatura e comprar. Esse é mais um motivo para inspecionar a habilidade inteira em vez de tratar uma frase extra como prova.

Repita o mesmo ciclo para o seu próprio deck: pedido → consulta → texto do card → um refinamento. Se o orçamento remover todos os candidatos úteis, pergunte antes de ampliá-lo. Se um card tiver uma restrição, diga a restrição em vez de simplesmente omiti-la da explicação.

Etapa 5: Como testar o localizador de cards antes de usá-lo?

Teste tanto a resposta quanto a chamada da API. Uma frase convincente não pode estabelecer qual consulta foi executada nem quais registros voltaram.

1. Abra Testing e crie um conjunto de dados chamado Open Query checks usando Create Dataset → Paste messages. Cole as mensagens de teste independentes do kit.
2. Execute os testes. Avalie se a resposta mostra sua consulta, cita os cards retornados e explica a incerteza.
3. Abra a conversa correspondente em Inbox e inspecione a chamada da Action. Verifique a consulta, o número da página, o status e os campos retornados. Use o controle View logs da Action para localizar chamadas individuais.
4. Teste refinamento e paginação em uma conversa contínua, na qual a consulta anterior esteja disponível.

Para o teste sem correspondência, envie:

Find a Commander card named definitely-not-a-real-card-xyz.

Um teste direto da API mostrou por que os avisos importam. A consulta malformada f:commander o:/[/ retornou HTTP 200, mas Scryfall informou que havia ignorado a expressão inválida. Portanto, os resultados eram mais amplos do que o pedido. Preserve esse aviso, explique o filtro ignorado e corrija a consulta antes de recomendar esses resultados.

Nossas execuções locais do Agent cobriram a linha de base, o refinamento, os resultados vazios e uma busca de duas páginas. Verificações separadas da API cobriram preços ausentes, faces de cards e avisos de sintaxe. Use um cenário controlado para testar limite de taxa sem enviar tráfego excessivo.

A documentação do endpoint de busca de cards atualmente especifica duas requisições de busca por segundo. Mantenha pelo menos 500 milissegundos entre as requisições. Este tutorial é um auxiliar de busca pessoal. Um bot público atendendo muitos jogadores precisa de limitação de taxa compartilhada e cache. Pedir ao modelo para desacelerar não impõe um limite global de requisições.

O ChatGPT ou o Claude podem ajudar a configurar isso?

Você pode usar o plugin Quickchat AI para ChatGPT ou o conector Quickchat AI para Claude para configurar o Agent pela conexão de gerenciamento de conta. Conclua o login você mesmo e depois forneça este tutorial e seu kit inicial com o seguinte pedido:

Use Quickchat AI to create a dedicated Agent called Open Query using the attached tutorial and starter kit. Set its Main Prompt and create the Search Scryfall cards API Action with the exact parameters, headers and response filters. Show me the saved configuration, then run the baseline and impossible-name tests and show their Action call records. Run only those two conversations; they use AI credits. Do not publish the Agent or connect a public channel.

A documentação de gerenciamento de conta explica a conexão. Isso configura sua conta Quickchat AI. Isso não torna automaticamente Open Query disponível para outras pessoas como uma ferramenta MCP.

Perguntas frequentes

Posso pesquisar Scryfall em linguagem natural?

Um assistente de IA pode traduzir um pedido em linguagem comum para a sintaxe de busca do Scryfall e executá-la pela API Scryfall. Este tutorial monta esse assistente em Quickchat AI e faz com que ele mostre a consulta, os registros de cards vinculados e o texto Oracle relevante para que você possa conferir a interpretação.

Preciso de uma chave de API do Scryfall?

Não. O endpoint público de busca de cards não exige conta nem chave de API. Envie cabeçalhos de identificação User-Agent e Accept, siga os limites de taxa do Scryfall e solicite páginas adicionais de forma deliberada.

Este localizador de cards com IA pode alucinar um card?

As instruções restringem as recomendações aos registros retornados pela Action, com links Scryfall. O modelo ainda pode cometer erros, então verifique o ID retornado e o texto Oracle, e teste um nome de card impossível antes de confiar no assistente.

Qual é a diferença entre id<=g e id=g no Scryfall?

id<=g inclui identidades verdes e incolores, adequado para buscar dentro das cores de um comandante monoverde. id=g exige identidade exatamente verde. Identidade de cor é diferente da cor do card. Use o filtro de identidade para a construção de deck de Commander.

Os preços do Scryfall são garantidos?

Não. O campo prices.usd é um dado de preço do provedor para a impressão retornada, não uma oferta de um vendedor. Ele pode ser null. O filtro usd<5 busca abaixo de cinco dólares americanos. Ele não estabelece custos de frete, disponibilidade nem a impressão comprável mais barata.

Uma busca retorna todos os cards correspondentes?

Uma busca retorna uma página da API. A resposta inclui total_cards, has_more e, quando relevante, next_page. Open Query mostra até cinco recomendações da página obtida. Peça mais dessa página ou solicite explicitamente a próxima página da API. Uma lista curta não é o conjunto completo de resultados.

Isso pode montar meu deck inteiro de Commander?

Este tutorial monta um assistente de busca de cards. Ele ajuda a encontrar e inspecionar candidatos para um espaço no deck. Ele não valida um deck completo de 100 cards, não otimiza uma lista de deck e não substitui um juiz de regras.