Sukurkite AI Commander kortų paiešką su Scryfall

Scryfall Commander kortų paieška paverčia jums reikalingos kortos aprašymą į paiešką, kurią galite peržiūrėti. Šioje pamokoje sukursite Open Query, Quickchat AI Agentą, kuris rodo savo Scryfall užklausą, grąžina tikrus kortų įrašus ir paaiškina, kodėl kiekvienas kandidatas gali tikti jūsų kaladei.

Pradėkite nuo vienos vietos vienžalėje Commander kaladėje. Norite būtybės su trample ir mažesne nei penkių JAV dolerių kaina. Pabaigoje galėsite įvesti šį prašymą, atverti grąžintas kortas ir tikslinti paiešką neįsimindami kiekvieno operatoriaus.

Naudingoji dalis prasideda tada, kai užklausa tampa sudėtingesnė. „Traukia, kai įeina kita būtybė“ skamba tiksliai, bet žodžių enters ir draw paieška taip pat randa kortas, kurios daro ką nors kita. Jūs pastebėsite šį neatitikimą ir susiaurinsite užklausą, naudodami grąžintą kortų tekstą kaip įrodymą.

Ką sukursite ir ko jums reikės?

Prijungsite vieną tik skaitymui skirtą API Action prie Scryfall, suteiksite Agentui jo paieškos instrukcijas ir išbandysite jį pokalbyje. Veiksmas kviečia fiksuotą URL. Modelis pateikia užklausą ir puslapio numerį. Scryfall grąžina įrašus, kuriais remiasi atsakymas.

1. Susikurkite Quickchat AI paskyrą ir Agentą pavadinimu Open Query. Pokalbiams ir testams jums reikės prieinamų AI kreditų. Žr. dabartinius planus.
2. Dirbdami turėkite po ranka Agento Identity, Actions & MCPs ir AI Preview. Kortų kolekcijos įkelti nereikia.
3. Naudokite viešąją Scryfall API. Šioms paieškoms jums nereikia Scryfall paskyros ar API rakto.

Pradiniame rinkinyje yra Main Prompt, veiksmo receptas, atsakymo filtro keliai ir testiniai pranešimai. Pavyzdžiuose naudojamas angliškas Oracle tekstas ir USD kainos. Sekdami kitu kalbos variantu, užklausų operatorius ir kortų pavadinimus palikite tokius, kaip parašyta.

1 žingsnis: kaip kortos užklausą paversti į Scryfall užklausą?

Scryfall užklausa sujungia tarpais atskirtus apribojimus. Pirmajai mūsų užklausai naudokite:

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

Svarbūs du maži pasirinkimai. kw:trample ieško raktažodžio. o:trample ieško žodžio Oracle tekste. Būtybė gali minėti trample, pati neturėdama šio gebėjimo. Išbandėme abu variantus. Teksto paieška davė platesnį rinkinį.

„Tinka vienžalei kaladei“ taip pat skiriasi nuo „turi tiksliai žalią tapatybę“. Pirma formuluotė leidžia bespalves kortas. Pastarajai naudokite id=g, arba id<=ur, jei ieškote mėlynai raudono vado spalvose. Tai tapatybės apribojimai, o ne pilnas kaladės legalumo patikrinimas.

Scryfall paieškos sintaksės nuorodoje paaiškinami šie operatoriai. Šioje pamokoje kiekviename atsakyme palikite užklausą matomą, kad pastebėtumėte praleistą spalvą, netikėtą valiutą ar paiešką, kuri yra platesnė nei jūsų prašymas.

2 žingsnis: kaip prijungti Scryfall API prie savo Agento?

Sukurkite vieną API Action, kuris siunčia GET užklausą į Scryfall kortų paieškos galinį tašką. Jo fiksuoti nustatymai parenka tiekėją ir rikiavimą. Du jo parametrai leidžia Agentui pasirinkti paiešką ir puslapį.

1. Atidarykite Actions & MCPs → Add Action → API Action.
2. Naudokite toliau pateiktą kūrimo užklausą, tada peržiūrėkite sugeneruotus nustatymus pagal receptą. API Action kūrimo vadove paaiškinamas generavimo ir peržiūros procesas.
3. Nustatykite API Action Name į 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.

Apibrėžkite du parametrus

Skiltyje What to ask the user first pridėkite šiuos privalomus parametrus. Agentas gali juos užpildyti iš pokalbio. Etiketė nereiškia, kad jis privalo prašyti jūsų įvesti neapdorotą užklausos sintaksę.

Nustatykite galinį tašką, užklausos parametrus ir antraštes

Pasirinkite GET ir įveskite:

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

Skiltyje Query Params pridėkite keturias toliau pateiktas eilutes. Dinaminėms reikšmėms naudokite Add AI Data, kad pasirinktumėte sukurtą parametrą. Toliau pateikta žymėsena {{query}} ir {{page}} reiškia tas parametrų žymas.

Naudokite užklausos parametrų laukus, kad tarpai, kabutės ir operatoriai būtų užkoduoti kaip parametrų reikšmės. Galinio taško URL palikite fiksuotą.

Palikite Body tuščią. Autentifikacija nereikalinga. User-Agent yra identifikuojantis kliento pavadinimas, o ne prisijungimo duomenys. Diegdami savo versiją naudokite tinkamą savo programos pavadinimą ir kontaktinį URL.

Išlaikykite atsakymą naudingą

Scryfall puslapyje gali būti daug įrašų. Palikite laukus, kurių reikia Agent, kartu su informacija, kuri jam nurodo, ar yra daugiau puslapių. Išskleiskite Advanced settings ir raskite Response filter. Naudokite Add JSONPath, tada pliuso mygtuką, kad kiekvieną toliau pateiktą kelią pridėtumėte kaip atskirą įrašą:

$.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

Palikite card_faces. Kai kurios kortos savo tekstą pateikia atskiruose veiduose, o ne aukščiausiame lygyje. Palikite ir warnings. HTTP sėkmė nereiškia, kad Scryfall kiekvieną dėmenį interpretavo taip, kaip buvo numatyta. Kortos objekto nuorodoje aprašomi šie laukai.

Į API Action Description įklijuokite:

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.

Išsaugokite veiksmą ir patikrinkite, ar jis aktyvus. HTTP veiksmo sandaros vadove paaiškinama, kaip kartu veikia parametrai, užklausa ir aprašymas.

3 žingsnis: kaip kortų paieška turėtų paaiškinti savo rezultatus?

Agentui reikia instrukcijų, kad jis rodytų savo užklausą, rekomendacijas grįstų grąžintais įrašais ir atskirtų žodžio atitikimą nuo taisyklių sąveikos. Atidarykite Identity → Main Prompt ir įklijuokite visą užklausą iš pradinio rinkinio, atkurtą toliau.

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.

Dabar atidarykite AI Preview ir išsiųskite:

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

Demonstracija interpretavo tinkamumą vienžalei kaladei kaip žalią arba bespalvę tapatybę. Jei norite tiksliai žalios tapatybės, tai aiškiai pasakykite.

Prieš rekomendacijas perskaitykite įvykdytą užklausą. Ji turėtų išlaikyti Commander, žalią arba bespalvę tapatybę, būtybės tipą, trample ir mažesnę nei 5 USD kainą. Atverkite vienos kortos Scryfall nuorodą ir palyginkite aktualų tekstą, tapatybę ir kainą su atsakymu. Kaina yra grąžinto leidimo paieškos metu užfiksuotas rodmuo, o ne atsiskaitymo pasiūlymas.

API rezultatai rikiuojami pagal pavadinimą, o ne pagal tinkamumą. Agentas pasirenka trumpąjį sąrašą iš gauto puslapio. unique=cards padeda neišvardyti kiekvieno leidimo kaip atskiro rezultato. Tai nereiškia, kad pasirinktas įrašas yra pigiausia kopija, kurią galite nusipirkti.

4 žingsnis: kaip pataisyti paiešką, kuri randa neteisingą sąveiką?

Susiaurinkite užklausą perskaitę priešingą pavyzdį ir pridėję trūkstamą sąlygą. Visą tikslinimo procesą išlaikykite skirtį tarp kandidatinių kortų radimo ir jų teksto patvirtinimo.

Paklauskite:

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

Plati kandidatų paieška yra:

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

Mūsų tiesioginiame Scryfall patikrinime 2026 m. lapkričio 10 d. tai grąžino 161 kandidatą, įskaitant Abundant Growth. Jos traukimas įvyksta tada, kai pati Aura įeina. Joje yra abu žodžiai, bet ji nesuteikia pakartotinai veikiančio būtybės įėjimo traukimo variklio, kurį numano užklausa.

Išbandykite šį patikslinimą:

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

Siauresnė užklausa, kurią tikrinome, buvo:

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

Patikslinta paieška grąžino keturis kandidatus. Garruk’s Packleader yra naudingas sąlyginis atitikimas: kita būtybė turi turėti 3 ar didesnę galią. Šis skirtumas turi būti paminėtas rekomendacijoje. Žetonų strategijai su daug 1/1 būtybių gali reikėti kitos kortos.

Pridėti vien o:"another creature" yra mažiau tikslu. Mūsų testas vis tiek rado Disciple of Freyalise, kurios pačios įėjimas gali paskatinti jus paaukoti kitą būtybę ir traukti. Tai dar viena priežastis peržiūrėti visą gebėjimą, o ne laikyti papildomą frazę įrodymu.

Kartokite tą patį ciklą savo kaladei: užklausa → paieška → kortos tekstas → vienas patikslinimas. Jei biudžetas pašalina visus naudingus kandidatus, prieš jį didindami paklauskite. Jei korta turi apribojimą, įvardykite tą apribojimą, užuot tyliai jį išmetę iš paaiškinimo.

5 žingsnis: kaip išbandyti kortų paiešką prieš ją naudojant?

Tikrinkite ir atsakymą, ir API kvietimą. Įtikinamas sakinys negali parodyti, kuri užklausa buvo paleista ar kurie įrašai buvo grąžinti.

1. Atidarykite Testing ir sukurkite duomenų rinkinį pavadinimu Open Query checks, naudodami Create Dataset → Paste messages. Įklijuokite nepriklausomus testinius pranešimus iš rinkinio.
2. Paleiskite testus. Įvertinkite, ar atsakymas rodo savo užklausą, cituoja grąžintas kortas ir paaiškina neapibrėžtumą.
3. Atidarykite atitinkamą pokalbį skiltyje Inbox ir peržiūrėkite veiksmo kvietimą. Patikrinkite užklausą, puslapio numerį, būseną ir grąžintus laukus. Naudokite veiksmo valdiklį View logs, kad rastumėte atskirus kvietimus.
4. Išbandykite tikslinimą ir puslapiavimą tęstiniame pokalbyje, kuriame prieinama ankstesnė užklausa.

Testui be atitikmenų išsiųskite:

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

Vienas tiesioginis API testas parodė, kodėl įspėjimai svarbūs. Netaisyklinga užklausa f:commander o:/[/ grąžino HTTP 200, bet Scryfall pranešė, kad netaisyklinga išraiška buvo ignoruota. Todėl rezultatai buvo platesni nei prašyta. Išsaugokite tą įspėjimą, paaiškinkite ignoruotą filtrą ir pataisykite užklausą prieš rekomenduodami tuos rezultatus.

Mūsų vietinio Agento paleidimai apėmė bazinį scenarijų, tikslinimą, tuščius rezultatus ir dviejų puslapių paiešką. Atskiri API patikrinimai apėmė trūkstamas kainas, kortų veidus ir sintaksės įspėjimus. Greičio ribojimą testuokite su kontroliuojamu fikstūros rinkiniu, nesiųsdami perteklinio srauto.

Kortų paieškos galinio taško dokumentacijoje šiuo metu nurodomos dvi paieškos užklausos per sekundę. Tarp užklausų palikite bent 500 milisekundžių. Ši pamoka yra asmeninis paieškos pagalbininkas. Viešam botui, aptarnaujančiam daug žaidėjų, reikia bendro greičio ribojimo ir podėliavimo. Prašymas modeliui sulėtėti neužtikrina visuotinio užklausų limito.

Ar ChatGPT arba Claude gali padėti tai sukonfigūruoti?

Galite naudoti Quickchat AI įskiepį ChatGPT arba Quickchat AI jungtį Claude, kad sukonfigūruotumėte Agentą per paskyros valdymo ryšį. Prisijungimą atlikite patys, tada pateikite šią pamoką ir jos pradinį rinkinį su šiuo prašymu:

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.

Paskyros valdymo dokumentacijoje paaiškinamas šis ryšys. Tai konfigūruoja jūsų Quickchat AI paskyrą. Tai automatiškai nepadaro Open Query prieinamo kitiems žmonėms kaip MCP įrankio.

Dažniausiai užduodami klausimai

Ar galiu ieškoti Scryfall natūralia kalba?

AI asistentas gali išversti paprasta kalba suformuluotą užklausą į Scryfall paieškos sintaksę ir ją vykdyti per Scryfall API. Šioje pamokoje sukursite tokį asistentą su Quickchat AI ir priversite jį rodyti užklausą, susietus kortų įrašus ir aktualų Oracle tekstą, kad galėtumėte patikrinti interpretaciją.

Ar man reikia Scryfall API rakto?

Ne. Viešajam kortų paieškos galiniam taškui nereikia paskyros ar API rakto. Siųskite identifikuojančias User-Agent ir Accept antraštes, laikykitės Scryfall greičio ribų ir papildomų puslapių prašykite apgalvotai.

Ar ši AI kortų paieška gali išgalvoti kortą?

Instrukcijos apriboja rekomendacijas tik įrašais, kuriuos grąžina veiksmas, su Scryfall nuorodomis. Modelis vis tiek gali suklysti, todėl prieš pasikliaudami asistentu patikrinkite grąžintą ID ir Oracle tekstą, ir išbandykite neįmanomą kortos pavadinimą.

Kuo skiriasi id<=g ir id=g sistemoje Scryfall?

id<=g apima žalią ir bespalvę tapatybę, todėl tinka paieškai vienžalio vado spalvose. id=g reikalauja tiksliai žalios tapatybės. Spalvinė tapatybė skiriasi nuo kortos spalvos. Commander kaladės konstravimui naudokite tapatybės filtrą.

Ar Scryfall kainos yra garantuotos?

Ne. Laukas prices.usd yra grąžinto leidimo tiekėjo kainodaros duomenys, o ne pardavėjo pasiūlymas. Jis gali būti null. Filtras usd<5 ieško žemiau penkių JAV dolerių. Jis nenustato siuntimo kainos, prieinamumo ar pigiausio įsigyjamo leidimo.

Ar viena paieška grąžina visas atitinkančias kortas?

Paieška grąžina vieną API puslapį. Atsakyme yra total_cards, has_more ir, kai aktualu, next_page. Open Query rodo iki penkių rekomendacijų iš gauto puslapio. Paprašykite daugiau iš to puslapio arba aiškiai paprašykite kito API puslapio. Trumpasis sąrašas nėra visas rezultatų rinkinys.

Ar tai gali sukurti visą mano Commander kaladę?

Šioje pamokoje kuriamas kortų paieškos asistentas. Jis padeda rasti ir peržiūrėti kandidatus kaladės vietai. Jis netikrina pilnos 100 kortų kaladės, neoptimizuoja kaladės sąrašo ir nepakeičia taisyklių teisėjo.