Xây dựng trình tìm thẻ bài AI Commander với Scryfall

Một trình tìm thẻ bài Scryfall Commander biến mô tả về lá bài bạn cần thành một truy vấn mà bạn có thể kiểm tra. Trong hướng dẫn này, bạn sẽ xây dựng Open Query, một Agent Quickchat AI hiển thị truy vấn Scryfall của nó, trả về các bản ghi thẻ bài thực và giải thích vì sao mỗi ứng viên có thể phù hợp với bộ bài của bạn.

Hãy bắt đầu với một vị trí trong bộ bài Commander đơn xanh lá. Bạn muốn một sinh vật có trample và giá dưới năm đô la Mỹ. Đến cuối bài, bạn có thể gõ yêu cầu đó, mở các thẻ bài được trả về và tinh chỉnh tìm kiếm mà không cần ghi nhớ mọi toán tử.

Phần hữu ích xuất hiện khi yêu cầu trở nên khó hơn. “Draw when another creature enters” nghe có vẻ chính xác, nhưng tìm kiếm các từ enters và draw cũng tìm ra những lá bài làm việc khác. Bạn sẽ bắt được sự lệch đó và thu hẹp truy vấn, dùng văn bản thẻ bài được trả về làm bằng chứng.

Bạn sẽ xây gì và cần những gì?

Bạn sẽ kết nối một API Action chỉ đọc với Scryfall, cung cấp cho Agent hướng dẫn tìm kiếm và thử nghiệm nó trong một cuộc trò chuyện. Action gọi một URL cố định. Mô hình cung cấp một truy vấn và số trang. Scryfall trả về các bản ghi mà câu trả lời dựa vào.

1. Tạo một tài khoản Quickchat AI và một Agent tên là Open Query. Bạn cần có AI credits khả dụng cho các cuộc trò chuyện và bài kiểm thử. Xem các gói hiện tại.
2. Giữ sẵn Identity, Actions & MCPs và AI Preview của Agent trong lúc làm. Không cần tải lên bộ sưu tập thẻ bài.
3. Dùng API công khai của Scryfall. Bạn không cần tài khoản hoặc khóa API Scryfall cho các lượt tìm kiếm này.

Bộ khởi đầu chứa Main Prompt, công thức Action, các đường dẫn bộ lọc phản hồi và các tin nhắn kiểm thử. Các ví dụ dùng văn bản Oracle tiếng Anh và giá USD. Hãy giữ nguyên các toán tử truy vấn và tên thẻ bài như đã viết khi làm theo bằng ngôn ngữ khác.

Bước 1: Làm thế nào để biến một yêu cầu thẻ bài thành truy vấn Scryfall?

Một truy vấn Scryfall kết hợp các ràng buộc được ngăn cách bằng dấu cách. Với yêu cầu đầu tiên của chúng ta, hãy dùng:

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

Hai lựa chọn nhỏ rất quan trọng. kw:trample tìm theo từ khóa. o:trample tìm theo từ trong văn bản Oracle. Một sinh vật có thể nhắc đến trample mà bản thân nó không có khả năng đó. Chúng tôi đã thử cả hai. Tìm kiếm theo văn bản cho ra một tập rộng hơn.

“Phù hợp với bộ bài đơn xanh lá” cũng khác với “có đúng danh tính xanh lá.” Cách đầu cho phép các thẻ bài vô sắc. Dùng id=g cho trường hợp sau, hoặc id<=ur để tìm trong màu của một commander xanh dương đỏ. Đây là các ràng buộc về danh tính, không phải một phép kiểm tra tính hợp lệ bộ bài hoàn chỉnh.

Tài liệu tham chiếu cú pháp tìm kiếm của Scryfall giải thích các toán tử này. Với hướng dẫn này, hãy giữ truy vấn hiển thị trong mọi câu trả lời để bạn có thể nhận ra một màu bị bỏ sót, một loại tiền tệ bất ngờ hoặc một lượt tìm kiếm rộng hơn yêu cầu của bạn.

Bước 2: Làm thế nào để kết nối API Scryfall với Agent của bạn?

Tạo một API Action gửi yêu cầu GET đến điểm cuối tìm kiếm thẻ bài của Scryfall. Các thiết lập cố định của nó chọn nhà cung cấp và thứ tự sắp xếp. Hai tham số của nó cho phép Agent chọn lượt tìm kiếm và trang.

1. Mở Actions & MCPs → Add Action → API Action.
2. Dùng yêu cầu cho builder bên dưới, rồi rà soát các thiết lập được tạo ra theo công thức. Hướng dẫn builder API Action giải thích luồng tạo và rà soát.
3. Đặt API Action Name thành 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.

Xác định hai tham số

Trong What to ask the user first, thêm các tham số bắt buộc này. Agent có thể điền chúng từ cuộc trò chuyện. Nhãn này không có nghĩa là nó phải yêu cầu bạn gõ cú pháp truy vấn thô.

Đặt điểm cuối, tham số truy vấn và header

Chọn GET và nhập:

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

Trong Query Params, thêm bốn hàng bên dưới. Với các giá trị động, dùng Add AI Data để chọn tham số bạn đã tạo. Ký hiệu {{query}} và {{page}} bên dưới đại diện cho các chip tham số đó.

Hãy dùng các trường tham số truy vấn để dấu cách, dấu ngoặc kép và toán tử được mã hóa thành giá trị tham số. Giữ URL điểm cuối cố định.

Để trống Body. Không cần xác thực. User-Agent là tên client nhận diện, không phải thông tin xác thực. Hãy dùng tên ứng dụng và URL liên hệ phù hợp của riêng bạn khi triển khai phiên bản của mình.

Giữ cho phản hồi hữu ích

Một trang Scryfall có thể chứa nhiều bản ghi. Hãy giữ lại các trường mà Agent cần, cùng với thông tin cho biết liệu còn trang nào nữa hay không. Mở rộng Advanced settings và tìm Response filter. Dùng Add JSONPath, rồi nút dấu cộng, để thêm từng đường dẫn bên dưới dưới dạng mục riêng biệt:

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

Giữ card_faces. Một số thẻ bài đặt văn bản của chúng trên từng mặt riêng thay vì ở cấp cao nhất. Cũng giữ warnings: một lần thành công HTTP không có nghĩa là Scryfall đã diễn giải mọi mệnh đề đúng như dự định. Tài liệu tham chiếu đối tượng Card mô tả các trường này.

Trong API Action Description, dán:

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.

Lưu Action và kiểm tra rằng nó đang hoạt động. Hướng dẫn cấu trúc HTTP Action giải thích cách các tham số, yêu cầu và mô tả phối hợp với nhau.

Bước 3: Trình tìm thẻ bài nên giải thích kết quả như thế nào?

Agent cần hướng dẫn để hiển thị truy vấn của nó, neo các gợi ý vào các bản ghi được trả về và phân biệt giữa khớp từ ngữ với tương tác theo luật. Mở Identity → Main Prompt và dán toàn bộ prompt từ bộ khởi đầu, được chép lại bên dưới.

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.

Bây giờ mở AI Preview và gửi:

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

Bản demo diễn giải điều kiện hợp lệ cho bộ bài đơn xanh lá là xanh lá hoặc vô sắc. Nếu muốn đúng danh tính xanh lá, hãy nói rõ điều đó.

Hãy đọc truy vấn đã thực thi trước khi xem các gợi ý. Nó nên giữ nguyên Commander, danh tính xanh lá hoặc vô sắc, loại sinh vật, trample và USD dưới 5. Mở liên kết Scryfall của một thẻ bài và so sánh văn bản liên quan, danh tính và giá với câu trả lời. Giá là một quan sát tra cứu cho bản in được trả về, không phải báo giá thanh toán.

Kết quả API được sắp xếp theo tên, không được xếp hạng theo độ phù hợp. Agent chọn một danh sách ngắn từ trang đã tải. unique=cards tránh liệt kê mọi bản in như một kết quả riêng. Điều đó không có nghĩa bản ghi được chọn là bản sao rẻ nhất bạn có thể mua.

Bước 4: Làm thế nào để sửa một lượt tìm kiếm tìm ra sai tương tác?

Thu hẹp truy vấn bằng cách đọc một phản ví dụ và thêm điều kiện còn thiếu. Hãy giữ sự phân biệt giữa việc tìm các thẻ bài ứng viên và xác nhận văn bản của chúng trong suốt quá trình tinh chỉnh.

Hãy hỏi:

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

Một lượt tìm kiếm ứng viên rộng là:

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

Trong lần kiểm tra Scryfall trực tiếp của chúng tôi vào ngày 10 tháng 11 năm 2026, truy vấn này trả về 161 ứng viên, bao gồm Abundant Growth. Việc rút bài của nó xảy ra khi chính Aura đó đi vào. Nó chứa cả hai từ, nhưng không cung cấp cỗ máy rút bài lặp lại khi sinh vật đi vào như yêu cầu gợi ý.

Hãy thử tinh chỉnh này:

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

Truy vấn hẹp hơn mà chúng tôi kiểm tra là:

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

Lượt tìm kiếm đã tinh chỉnh trả về bốn ứng viên. Garruk’s Packleader là một kết quả khớp có điều kiện hữu ích: sinh vật kia cần có sức mạnh 3 trở lên. Sự khác biệt đó cần xuất hiện trong phần gợi ý. Một chiến lược token với nhiều sinh vật 1/1 có thể cần một lá bài khác.

Chỉ thêm o:"another creature" thì kém chính xác hơn. Bài kiểm tra của chúng tôi vẫn tìm thấy Disciple of Freyalise, nơi việc tự đi vào của nó có thể dẫn bạn đến việc hiến tế một sinh vật khác và rút bài. Đó là một lý do nữa để kiểm tra toàn bộ khả năng thay vì xem một cụm từ bổ sung như bằng chứng.

Lặp lại cùng một vòng cho bộ bài của riêng bạn: yêu cầu → truy vấn → văn bản thẻ bài → một lần tinh chỉnh. Nếu ngân sách loại bỏ mọi ứng viên hữu ích, hãy hỏi trước khi nới rộng nó. Nếu một lá bài có hạn chế, hãy nêu hạn chế đó thay vì âm thầm bỏ nó khỏi phần giải thích.

Bước 5: Làm thế nào để kiểm thử trình tìm thẻ bài trước khi dùng?

Hãy kiểm thử cả câu trả lời lẫn lệnh gọi API. Một câu văn nghe thuyết phục không thể xác lập truy vấn nào đã chạy hoặc những bản ghi nào đã được trả về.

1. Mở Testing và tạo một dataset tên là Open Query checks bằng Create Dataset → Paste messages. Dán các tin nhắn kiểm thử độc lập từ bộ công cụ.
2. Chạy các bài kiểm thử. Chấm xem câu trả lời có hiển thị truy vấn của nó, trích dẫn các thẻ bài được trả về và giải thích sự không chắc chắn hay không.
3. Mở cuộc trò chuyện tương ứng trong Inbox và kiểm tra lệnh gọi Action. Kiểm tra truy vấn, số trang, trạng thái và các trường được trả về. Dùng điều khiển View logs của Action để tìm từng lệnh gọi riêng lẻ.
4. Kiểm thử việc tinh chỉnh và phân trang trong một cuộc trò chuyện tiếp diễn, nơi truy vấn trước đó có sẵn.

Đối với bài kiểm thử không có kết quả khớp, hãy gửi:

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

Một lần kiểm thử API trực tiếp cho thấy vì sao cảnh báo lại quan trọng. Truy vấn lỗi định dạng f:commander o:/[/ trả về HTTP 200, nhưng Scryfall báo rằng nó đã bỏ qua biểu thức không hợp lệ. Vì vậy, các kết quả rộng hơn yêu cầu. Hãy giữ lại cảnh báo đó, giải thích bộ lọc bị bỏ qua và sửa truy vấn trước khi gợi ý các kết quả đó.

Các lần chạy Agent cục bộ của chúng tôi bao quát đường cơ sở, tinh chỉnh, kết quả rỗng và một lượt tìm kiếm hai trang. Các lần kiểm tra API riêng biệt bao quát giá bị thiếu, các mặt thẻ bài và cảnh báo cú pháp. Hãy dùng một fixture được kiểm soát để kiểm thử giới hạn tốc độ mà không gửi lưu lượng quá mức.

Tài liệu điểm cuối tìm kiếm thẻ bài hiện quy định hai yêu cầu tìm kiếm mỗi giây. Hãy giữ khoảng cách giữa các yêu cầu ít nhất 500 mili giây. Hướng dẫn này là một trợ lý tìm kiếm cá nhân. Một bot công khai phục vụ nhiều người chơi cần giới hạn tốc độ dùng chung và bộ nhớ đệm. Yêu cầu mô hình chậm lại không thực thi được giới hạn yêu cầu toàn cục.

ChatGPT hoặc Claude có thể giúp cấu hình phần này không?

Bạn có thể dùng plugin Quickchat AI cho ChatGPT hoặc connector Quickchat AI cho Claude để cấu hình Agent thông qua kết nối quản lý tài khoản. Hãy tự hoàn tất đăng nhập, rồi cung cấp hướng dẫn này và bộ khởi đầu của nó với yêu cầu sau:

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.

Tài liệu quản lý tài khoản giải thích kết nối này. Việc này cấu hình tài khoản Quickchat AI của bạn. Nó không tự động làm cho Open Query khả dụng cho người khác như một công cụ MCP.

Câu hỏi thường gặp

Tôi có thể tìm kiếm Scryfall bằng ngôn ngữ tự nhiên không?

Một trợ lý AI có thể chuyển một yêu cầu bằng ngôn ngữ thông thường thành cú pháp tìm kiếm Scryfall và thực thi nó qua API Scryfall. Hướng dẫn này xây dựng trợ lý đó trong Quickchat AI và khiến nó hiển thị truy vấn, các bản ghi thẻ bài được liên kết và văn bản Oracle liên quan để bạn có thể kiểm tra cách diễn giải.

Tôi có cần khóa API Scryfall không?

Không. Điểm cuối tìm kiếm thẻ bài công khai không yêu cầu tài khoản hoặc khóa API. Gửi các header User-Agent và Accept để nhận diện, tuân theo giới hạn tốc độ của Scryfall và chỉ yêu cầu thêm trang khi có chủ đích.

Trình tìm thẻ bài AI này có thể bịa ra một lá bài không?

Các hướng dẫn giới hạn gợi ý vào những bản ghi do Action trả về, kèm các liên kết Scryfall. Mô hình vẫn có thể mắc lỗi, vì vậy hãy kiểm tra ID và văn bản Oracle được trả về, đồng thời thử một tên thẻ bài không thể tồn tại trước khi dựa vào trợ lý.

Sự khác nhau giữa id<=g và id=g trên Scryfall là gì?

id<=g bao gồm danh tính màu xanh lá và vô sắc, phù hợp để tìm trong màu của một commander đơn xanh lá. id=g yêu cầu đúng danh tính xanh lá. Danh tính màu khác với màu của thẻ bài. Hãy dùng bộ lọc danh tính cho việc xây dựng bộ bài Commander.

Giá Scryfall có được đảm bảo không?

Không. Trường prices.usd là dữ liệu giá từ nhà cung cấp cho bản in được trả về, không phải một lời chào bán từ người bán. Nó có thể là null. Bộ lọc usd<5 tìm dưới năm đô la Mỹ. Nó không xác lập chi phí vận chuyển, tình trạng còn hàng hoặc bản in rẻ nhất có thể mua được.

Một lần tìm kiếm có trả về mọi thẻ bài khớp không?

Một lần tìm kiếm trả về một trang API. Phản hồi bao gồm total_cards, has_more và, khi phù hợp, next_page. Open Query hiển thị tối đa năm gợi ý từ trang đã tải. Hãy yêu cầu thêm từ trang đó hoặc yêu cầu rõ ràng trang API tiếp theo. Một danh sách ngắn không phải là toàn bộ tập kết quả.

Công cụ này có thể xây toàn bộ bộ bài Commander của tôi không?

Hướng dẫn này xây dựng một trợ lý tìm kiếm thẻ bài. Nó giúp tìm và kiểm tra các ứng viên cho một vị trí trong bộ bài. Nó không xác thực một bộ bài hoàn chỉnh 100 lá, không tối ưu danh sách bộ bài và không thay thế trọng tài luật chơi.