Uwagi praktyczne: Sześć wiodących firm technologicznych wspólnie tworzy plugin dla agentów AI
Szczegółowy przewodnik po „Practical notes”: sześć wiodących firm technologicznych wspólnie tworzy standard pakietowania pluginów dla agentów AI po MCP i…: umowy, sprawdzania oraz kod gotowy do użycia.
To przewodnictwo pokazuje, jak odtworzyć proces od surowców do gotowego systemu w przypadku: Sześć głównych firm technologicznych wspólnie tworzy standard pakowania wtyczek agentów AI po MCP i SKILL. Skupiamy się na krokach operacyjnych, wyraźnych sprawdzeniach oraz kodzie, który można bez problemu dodać do repozytorium, nie musząc zgadywać intencji. Aby uzyskać ogólny obraz, zdefiniuj wprowadzenia, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zapisuj czas trwania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z wersji demonstracyjnej do środowisk współdzielonych.
Struktura katalogów
Gdy pracujesz nad strukturą katalogów, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie agenta trwa godzinami.
reports-plugin/
├── plugin.json # Required: The only entry point for the plugin
├── skills/ # Optional: Collection of skills
│ ├── summarize/ # One individual skill
│ │ ├── SKILL.md # Required: Skill definition file
│ │ ├── scripts/ # Optional: Scripts used by the skill
│ │ │ └── analyze.sh
│ │ └── references/ # Optional: Reference documentation for the skill
│ │ └── checklist.md
│ ├── deploy/ # A second skill
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ │ └── rollback.sh
│ │ └── references/
│ │ └── runbook.md
│ └── code-review/ # A third skill
│ └── SKILL.md
├── mcp.json # Optional: MCP server configuration
├── com.cursor.tools/ # Optional: Cursor-specific extensions, other clients skip automatically
│ └── hooks/
│ └── hooks.json
├── LICENSE
└── CHANGELOG.md
Specyfikacja plugin.json
Gdy pracujesz nad specyfikacją plugin.json, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Dokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez tego śladu debugowanie agenta trwa godzinami.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "hello-plugin"
}
Odkrywanie komponentów
Podczas pracy nad odkrywaniem komponentów najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Debugowanie bez takich informacji marnuje godziny. Podczas pracy nad odkrywaniem komponentów najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do wspólnych środowisk.
Konfiguracja MCP
Konfiguracja MCP działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Używaj narzędzi o wąskich schematach i wyraźnych etykietach efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą.
Zmienne środowiskowe i trwałość danych
Zmienne środowiskowe i trwałość danych działają najlepiej, gdy są traktowane jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres badania. Zdokumentuj zarówno prawidłowy przebieg operacji, jak i ścieżkę przywracania do stanu poprzedniego. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Udostępnij narzędzia o wąskich schematach i wyraźnych etykietach dotyczących efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim je automatycznie zatwierdzą.
Izolowane częściowe awarie
Izolowane częściowe awarie działają najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden „złoty transkrypt”, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Używaj narzędzi o wąskich schematach oraz z wyraźnymi etykietami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą. Izolowane częściowe awarie działają najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden „złoty transkrypt”, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do wspólnych środowisk.
Niezbadane obszary
Dla obszarów niewykrytych należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Autoryzacja powinna odbywać się przy bramie wejściowej, a ponowna autoryzacja – na poziomie przesyłania danych. Sam token nie stanowi granicy między poszczególnymi użytkownikami.
Wspierający i nieobecni
Dla zwolenników i osób nieobecnych należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Autoryzacja powinna odbywać się przy bramce wejściowej, a ponowna autoryzacja – na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.
Przykład z praktyki: pełny proces pracy z Google Agents CLI
Jako przykład z praktyki: pełny proces pracy z Google Agents CLI wymaga określenia danych wejściowych, osoby odpowiedzialnej za dany krok oraz kryteriów zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Lepiej używać małych, łatwych do przetestowania jednostek niż rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Uwierzytelniaj się przy bramie wejściowej, a ponownie autoryzuj na poziomie warstwy danych. Sam token nie stanowi granicy między poszczególnymi użytkownikami. Jako przykład z praktyki: pełny proces pracy z Google Agents CLI wymaga określenia danych wejściowych, osoby odpowiedzialnej za dany krok oraz kryteriów zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka operacji ulega zmianie.
Demo opiera się na współdzielonych środowiskach.
Linki powiązane
Pracując z linkami powiązanymi, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie agenta w błędnym cyklu marnuje godziny.
Lista kontrolna operacyjna
Lista kontrolna operacyjna działa najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny zapis działania, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy.
Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań.
Ujawniaj narzędzia o wąskich schematach oraz z wyraźnymi etykietami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania modyfikują stan, zanim dokonają automatycznej aprobaty.
Zastosuj ludzką aprobatę w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia skompilowane w czasie kompilacji nie gwarantują kompletności funkcjonalności biznesowej.
Napisz krótki przewodnik: jak rotować klucze, jak opróżniać kolejkę z zadań, jak cofnąć ostatni proces pobierania danych.
Zdokumentuj zarówno standardową ścieżkę działania, jak i ścieżkę odzyskiwania. Próby ponownych wysiłków, ludzkie kontrolne punkty oraz obsługa wiadomości błędnych stanowią część produktu, a nie element późniejszej dopracowywania.
Zanim wdrożysz całą architekturę, zamroź wersje oprogramowania, utwórz idealny zapis działań dla kluczowej ścieżki oraz potwierdź kroki konieczne do cofnięcia zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkowników oraz jasno określonego odpowiedzialnego za rotację sekretów. Wolisz nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwagi dotyczące 6e2f83d3e5dc: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj transkrypcje obok plików testowych, aby późniejsze zmiany modeli pozostały porównywalne.
Literatura pokrewna
- Praktyczne notatki: MCP, A2A i ACP wyjaśnione – protokoły definiujące agenta AI — Szczegółowy przewodnik po praktycznych notatkach dotyczących MCP, A2A i ACP oraz protokołach określających interoperacyjność agentów AI w 2026 roku: umowy, sprawdzania oraz miejsca na kod do łatwego wdrożenia.