Sprawdzone metody dotyczące WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Data publikacji: 18 maja 2026 r.

Deklaracja narzędzia WebMCP powinna być jasna i nie wymagać od deweloperów ani agentów sprawdzania wyników i ponawiania prób. Niezależnie od tego, czy używasz interfejsu API w trybie imperatywnym czy deklaratywnym, postępuj zgodnie z tymi sprawdzonymi metodami:

  • Przed rozpoczęciem tworzenia opracuj strategię dotyczącą narzędzi.
  • Używaj jasnego języka i semantycznego kodu HTML.
  • Projektuj schematy i obsługuj dane wejściowe.
  • tworzyć niezawodne narzędzia,
  • Testowanie i debugowanie.

Tworzenie strategii dotyczącej narzędzi

Podobnie jak w przypadku każdej aplikacji, pierwszym krokiem powinno być zaplanowanie strategii dotyczącej narzędzi:

  • Każde narzędzie powinno składać się z jednej funkcji. Na przykład jedno narzędzie może kierować użytkownika do określonego typu formularza, a inne narzędzie powinno dopasowywać pola wejściowe do informacji o użytkowniku. Uważaj, aby nie tworzyć nakładających się narzędzi, ponieważ agent może mieć problem z określeniem, którego z nich użyć. Zastanów się: czy mogę wykonać kilka zadań za pomocą tej samej funkcji?
  • Zarządzanie rejestracją narzędzia Rejestruj narzędzia, gdy są przydatne w określonym stanie strony, a następnie wyrejestrowuj je, gdy nie można ich już używać.
    • Imperative API: możesz dynamicznie zarządzać rejestracją za pomocą metod registerTool i unregisterTool.
    • Deklaratywny interfejs API: możesz dynamicznie zarządzać rejestracją, dodając lub usuwając atrybuty narzędzia w formularzu za pomocą toolName i toolDescription.
  • Zmniejsz złożoność: w większości aplikacji domyślnym podejściem powinna być rejestracja statyczna.
  • Zaufaj agentowi, że wykona zadanie*. Zamiast pisać sztywne lub negatywne instrukcje, załóż, że agent jest w stanie zrozumieć, co jest wymagane do wykonania zadania, zamiast oczekiwać, że będzie zarządzać dokładnym przepływem kroków.

Nie ma maksymalnej liczby dozwolonych narzędzi, ale każde z nich zajmuje część okna kontekstu i wydłuża czas realizacji. Im więcej narzędzi udostępnisz i im bardziej będą się one pokrywać, tym trudniej będzie agentowi wybrać właściwe narzędzie. Eksperymentuj, aby określić, co jest odpowiednie dla Twojej aplikacji.

Ułatwia to tworzenie poszczególnych narzędzi, które nie mają wspólnego celu, oraz zarządzanie ich dostępnością.

Używaj zrozumiałego języka i kodu semantycznego.

Używaj jasnego i bezpośredniego języka, aby nazywać narzędzia i opisywać ich zastosowanie. Dzięki temu agenci mogą znaleźć potrzebne informacje, zrozumieć je i wykorzystać zgodnie z oczekiwaniami dewelopera.

Podczas pisania nazw narzędzi do pisania odróżniaj wykonanie od inicjowania i używaj czasowników, które dokładnie opisują, co się dzieje. Na przykład create-event to narzędzie do natychmiastowego tworzenia zdarzeń, a start-event-creation-process to narzędzie, które przekierowuje użytkownika do formularza, w którym może utworzyć zdarzenie.

Jasny opis powinien zawierać informacje o tym, do czego służy narzędzie i kiedy należy go używać. Zamiast używać negatywnego języka, np. ograniczeń, stosuj pozytywny język i określenia.

Nie

„Nie używaj tego narzędzia do sprawdzania pogody”.

Ograniczenia powinny być zawarte w dobrze napisanym opisie.
Tak

„To narzędzie może utworzyć wydarzenie w kalendarzu zaplanowane na konkretną datę i godzinę”.

Minimalizowanie przetwarzania poznawczego

Podobnie jak w przypadku ludzi wykonujących złożone zadania, należy zminimalizować obciążenie poznawcze modelu:

  • Akceptowanie nieprzetworzonych danych wejściowych użytkownika Nie proś agenta o wykonywanie obliczeń ani przekształcanie ciągów wejściowych. Jeśli np. użytkownik powie „11:00–15:00”, narzędzie powinno zaakceptować to jako ciąg tekstowy. Nie proś modelu o obliczenie liczby minut między tymi godzinami.
  • Deklarowanie konkretnych typów parametrów, takich jak ciąg znaków, liczba lub wyliczenie.
  • Wyjaśnij, dlaczego podjęto określone decyzje. Twój wybór powinien być oczywisty. Odpowiedź na pytanie „dlaczego” pomaga przedstawicielom podejmować lepsze decyzje. Jeśli na przykład prowadzisz sklep e-commerce, zadeklaruj typ dostawy w języku naturalnym zamiast używać niejednoznacznego identyfikatora: shipping="Express" zamiast shipping_id=1.

Priorytetem jest niezawodność

Agenci i ludzie korzystają z narzędzi, które działają zgodnie z oczekiwaniami:

  • Ustawianie łagodnego przełączania awaryjnego w przypadku limitów szybkości Narzędzia powinny umożliwiać rozsądne powtarzanie, np. w przypadku porównywania cen. Jeśli narzędzie ma ograniczenie liczby żądań, zwróć zrozumiały błąd lub poinformuj użytkownika, aby wykonał zadanie ręcznie.
  • Aktualizowanie stanu interfejsu po zakończeniu funkcji Pracownicy obsługi klienta mogą korzystać z interfejsu, aby planować kolejne kroki, a wykonywanie funkcji może trwać dłużej niż wczytywanie interfejsu. Po zaktualizowaniu interfejsu agent powinien potwierdzić, że funkcja została wykonana, lub ponownie poprosić o aktualizację.
  • Ścisła weryfikacja w kodzie, luźna w schemacie Ograniczenia i testowanie należy stosować w przypadku funkcji i kodu, które mają logikę binarną. Ograniczenia schematu mogą być przydatne, ale nie są gwarantowane. Dodaj do kodu funkcji opisowe błędy, aby umożliwić modelowi samodzielne korygowanie i ponawianie prób z nowymi, prawidłowymi parametrami.

Testowanie i debugowanie oceny

Twórz testy oceniające i udostępniaj narzędzia do debugowania. W przeciwieństwie do deterministycznych testów jednostkowych ocen nie można zakodować na stałe, ponieważ dane wyjściowe mogą przyjmować nieprzewidziane formy.

  • Określ problem. Możesz sformułować swój problem jako umowę interfejsu API, podając typ danych wejściowych, format danych wyjściowych i wszelkie dodatkowe ograniczenia.
  • Określ punkt odniesienia i idealny wynik. Zwłaszcza w przypadku danych wejściowych w postaci tekstu ważne jest, aby wiedzieć, jakie typy wyników mogą zapewnić oczekiwane dane wyjściowe.
  • Określ, jak będą oceniane wyniki. Prawdopodobnie identyfikujesz i mierzysz subiektywne, jakościowe wyniki na podstawie jakości danych wejściowych, przydatności i możliwości wykonania kolejnego zadania. Do oceny danych wyjściowych możesz używać różnych technik, w tym sprawdzania kodu w przypadku danych wyjściowych opartych na regułach (limity znaków) i LLM-as-a-judge.

Nie dodawaj wąskich reguł, aby rozwiązywać problemy z konkretnym modelem. Jeśli na przykład dodasz pole wyboru tytułów grzecznościowych, model może dokonać niewłaściwego wyboru. Zamiast dodawać wąskie reguły, aby rozwiązać ten problem, wyodrębnij i dostosuj narzędzie. Najlepiej będzie, jeśli ustawisz to pole jako opcjonalne. Następnie poproś agenta, aby zapytał użytkownika, która opcja jest dla niego odpowiednia, aby mieć pewność, że użytkownik jest zadowolony z wyniku.

Zaangażuj się i prześlij opinię

WebMCP jest obecnie przedmiotem dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz te interfejsy API i chcesz podzielić się opinią, chętnie ją poznamy.