Sprawdzone metody dotyczące WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Opublikowano: 18 maja 2026 r.

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 Imperative API czy Declarative API, postępuj zgodnie z tymi sprawdzonymi metodami:

  • Zanim zaczniesz tworzyć narzędzie, opracuj strategię jego działania.
  • Używaj jasnego języka i semantycznego kodu HTML.
  • Zaprojektuj schematy i obsługuj dane wejściowe.
  • Twórz niezawodne narzędzia.
  • Testuj i debuguj.

Osobno napisaliśmy o tworzeniu narzędzi z myślą o bezpieczeństwie.

Tworzenie strategii narzędzia

Podobnie jak w przypadku każdej aplikacji, pierwszym krokiem powinno być zaplanowanie strategii narzędzia:

  • 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 może dopasowywać pola wejściowe do informacji o użytkowniku. Uważaj, aby nie tworzyć narzędzi, które się pokrywają, ponieważ agent może nie wiedzieć, którego z nich użyć. Zastanów się, czy możesz wykonać kilka zadań za pomocą tej samej funkcji.
  • Zarządzaj 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ć.
    • Imperatywny interfejs API: możesz dynamicznie zarządzać rejestracją za pomocą registerTool.
    • Deklaratywny interfejs API: możesz dynamicznie zarządzać rejestracją, dodając lub usuwając atrybuty narzędzia w formularzu za pomocą funkcji toolname i tooldescription.
  • Zmniejsz złożoność: w przypadku 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 potrzebne do wykonania zadania, zamiast oczekiwać, że będzie zarządzać dokładnym przepływem działań.

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. Eksperymentuj, aby określić, co jest odpowiednie dla Twojej aplikacji.

Pomaga to tworzyć pojedyncze narzędzia, które nie mają nakładających się celów, i zarządzać ich dostępnością.

Używaj jasnego języka i semantycznego kodu

Używaj jasnego i precyzyjnego języka, aby nazywać narzędzia i opisywać ich zastosowanie. Pomaga to agentom znajdować to, czego potrzebują, rozumieć to, co znajdują, i używać tych informacji zgodnie z oczekiwaniami dewelopera.

Podczas pisania nazw narzędzi 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 wydarzeń, ale start-event-creation-process to narzędzie, które przekierowuje użytkownika do formularza tworzenia wydarzenia.

Jasny opis powinien zawierać informacje o tym, co robi narzędzie i kiedy go używać. Zamiast języka negatywnego, np. ograniczeń, używaj języka pozytywnego i preferencji.

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

Ograniczenia powinny być domyślnie zawarte w dobrze napisanym opisie.

Tak

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

Zamiast mówić modelowi co ma robić, ten język opisuje działania, które może wykonać narzędzie.

Minimalizowanie obliczeń poznawczych

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

  • Akceptuj nieprzetworzone dane wejściowe użytkownika. Nie proś agenta o wykonywanie obliczeń ani przekształcanie ciągów wejściowych. Jeśli na przykład użytkownik powie „11:00–15:00”, narzędzie powinno zaakceptować to jako ciąg znaków. Nie proś modelu o obliczenie liczby minut między tymi godzinami.
  • Deklaruj określone typy parametrów, takie jak ciąg znaków, liczba lub wyliczenie.
  • Wyjaśnij, dlaczego podjęto określone decyzje. Podjęta decyzja powinna być oczywista. Wyjaśnienie pomaga agentom 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.

Priorytetowe traktowanie niezawodności

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

  • Ustaw płynne przechodzenie do stanu awaryjnego w przypadku limitów liczby żądań. Narzędzia powinny umożliwiać rozsądne powtarzanie, np. w przypadku porównywania cen. Jeśli narzędzie jest ograniczone limitem liczby żądań, zwróć zrozumiały błąd lub poinformuj użytkownika, aby ręcznie wykonał zadanie.
  • Po zakończeniu funkcji zaktualizuj stan interfejsu. Agenci mogą polegać na interfejsie, aby planować kolejne kroki, a funkcje mogą działać dłużej niż wczytywanie interfejsu. Po zaktualizowaniu interfejsu agent powinien potwierdzić, że funkcja została wykonana, lub ponownie poprosić o aktualizację.
  • Sprawdzaj poprawność kodu, a nie schematu. W przypadku funkcji i kodu z logiką binarną należy używać ograniczeń i testowania. Ograniczenia schematu mogą być przydatne, ale nie są gwarantowane. Dodaj do kodu funkcji opisowe błędy, aby umożliwić modelowi samodzielne poprawianie błędów i ponawianie prób z nowymi, prawidłowymi parametrami.

Testowanie i debugowanie oceny

Utwórz testy oceny i udostępnij narzędzia do debugowania. W przeciwieństwie do deterministycznych testów jednostkowych ocen nie można zakodować na stałe, ponieważ wyniki mogą przyjmować nieoczekiwane formy.

  • Zdefiniuj problem. Problem możesz sformułować jako umowę API, w tym typ danych wejściowych, format danych wyjściowych i wszelkie dodatkowe ograniczenia.
  • Określ punkt odniesienia i idealny wynik. Szczególnie w przypadku danych wejściowych w postaci tekstu ważne jest, aby zrozumieć, jakie typy wyników mogą dać oczekiwane dane wyjściowe.
  • Określ, jak będą oceniane dane wyjściowe. Prawdopodobnie będziesz identyfikować i mierzyć subiektywne, jakościowe wyniki na podstawie jakości danych wejściowych, przydatności i możliwości wykonania następnego zadania. Do oceny danych wyjściowych możesz użyć kilku technik, w tym sprawdzania kodu pod kątem danych wyjściowych opartych na regułach (limity znaków) i LLM-as-a-judge.

Unikaj dodawania wąskich reguł, które mają 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, które mają rozwiązywać ten problem, abstrahuj i dostosuj narzędzie. Najlepiej będzie ustawić to pole jako opcjonalne. Następnie poproś agenta, aby zapytał użytkownika, która opcja jest odpowiednia, aby mieć pewność, że użytkownik jest zadowolony z wyniku.

Zaangażuj się i prześlij opinię

WebMCP jest w trakcie aktywnej dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz te interfejsy API i masz jakieś uwagi, chętnie je poznamy.