Strona główna / Artykuły

agent-pluginsmcpagent-skillsai-agentstooling

Agent Plugins 1.0.0: Ujednolicony format pakietowania dla umiejętności i serwerów MCP

Agent Plugins 1.0.0 zapewnia umiejętnościom oraz serwerom MCP jeden format pakietowania: foldery, plugin.json i mcp.json, co jednak negatywnie wpływa na bezpieczeństwo oraz nie zawiera przykładu interfejsu wiersza poleceń.

Wydawca: REACTAPP.TOP7 min czytania1571 słów

Źródła: Six Major Tech Companies Jointly Establish the AI Agent Plugin Packaging Standard After MCP and SKILL

Google, Microsoft, OpenAI, Cursor, Vercel i AWS przystąpiły do projektu Agent Plugins 1.0.0, który określa zasady pakowania wtyczek dla agentów AI. Projekt ten poprawia strukturę katalogów, format plików konfiguracyjnych oraz zasady wykrywania dwóch rodzajów komponentów: umiejętności oraz serwerów MCP. Cel jest prosty: napisz wtyczkę raz i uruchom ją w dowolnym kompatybilnym kliencie.

Do tej pory istniały dwa standardowe sposoby nadawania agentom programistycznym nowych możliwości. Umiejętność to zbiór instrukcji w formacie Markdown, które agent odczytuje w momencie potrzeby. Serwer MCP to odrębny proces, który łączy agenta z zewnętrznymi narzędziami, API lub bazami danych. Treść obu typów komponentów była już możliwa do przenoszenia między narzędziami, jednak każde narzędzie miało własne zasady organizacji katalogów, nazw plików konfiguracyjnych oraz miejsc przechowywania plików.

Wersja 1.0.0 dotyczy wyłącznie zewnętrznego opakowania. Nie wpływa na zawartość umiejętności ani na sam protokół MCP.

Dlaczego to ważne

Ta wartość ma znaczenie dla trzech grup:

  • Autorzy pluginów otrzymują jedną strukturę katalogów, która działa we wszystkich kompatybilnych klientach. Nie muszą już przechowywać oddzielnych kopii dla Cursor, Copilot, Codex i innych.
  • Dostawcy narzędzi mają ustalone miejsca dla plików skills/ i mcp.json, dzięki czemu nie muszą tworzyć własnej logiki wyszukiwania ani parsowania konfiguracji. Dostawca może nadal dodawać własne elementy do katalogów z nazwami przestrzeni, nie zakłócając przy tym innych implementacji.
  • Szerzy ekosystem czerpie korzyści z trzech decyzji projektowych: odkrywania plików za pomocą katalogu, braku konieczności dodatkowej konfiguracji poza umieszczeniem plików oraz ograniczania skutków awarii. Dystrybucja staje się łatwiejsza, a autorzy mogą skupić się na tym, co stworzyć, zamiast na wyborze narzędzi.

Ograniczenia są równie oczywiste. Specyfikacja standaryzuje opakowanie pakietu, ale nie mówi nic o bezpieczeństwie zawartego w nim materiału. Brakuje w niej podpisów, modelu uprawnień ani mechanizmów obsługi poufnych danych. Obecnie główną zaletą jest wydajność programistów, natomiast nie oferuje ona gwarancji bezpieczeństwa ani zaufania.

Struktura katalogu

Współgrający z normą plugin to po prostu folder. W przypadku przykładu o nazwie reports-plugin pełna struktura wygląda następująco:

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

Klienci sprawdzają dokładnie trzy miejsca. plugin.json oznacza folder jako ważny plugin. Każdy podfolder pierwszego poziomu w katalogu skills/, który zawiera plik SKILL.md, liczy się jako jedna umiejętność. Natomiast mcp.json jest czytany jako konfiguracja serwera MCP. foldery nazwane w stylu odwrotnego domeny, takie jak com.cursor.tools/, są czytane tylko przez klienta, do którego należą, czyli przez Cursor. Inni klienci, w tym ChatGPT i Codex, po prostu je pomijają.

Manifest plugin.json

plugin.json to jedyny obowiązkowy plik, a jego minimalna wersja jest bardzo mała:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

Schemat jest zamknięty i zawiera dziesięć dozwolonych pól najwyższego poziomu: $schema, name, version, description, author, homepage, repository, license, keywords oraz extensions. Nieznane pole jest zgłaszane, ale ignorowane, a wtyczka nadal się ładuje. Zły name to inna sprawa – jeśli jest brakujący, ma niewłaściwy typ lub zawiera nieprawidłowe znaki (litery wielkie, podwójne myślniki, pustą ścieżkę), cała wtyczka zostaje odrzucona.

Zasady dotyczące name: od 1 do 64 znaków, składających się z małych liter, cyfr, myślników i kropek. Musi zaczynać się i kończyć na literze lub cyfrze, a dwie myślniki lub dwie kropki z rzędu są zabronione.

Jak znajdowane są komponenty

Odkrywanie odbywa się wyłącznie na podstawie katalogów. Plik plugin.json nie może przenosić komponentów w inne miejsce ani włączać ich konfiguracji bezpośrednio w tekście. Istnieją tylko trzy rodzaje lokalizacji:

  • skills/: każdy podkatalog pierwszego poziomu zawierający plik SKILL.md stanowi umiejętność. Głębsze foldery nie są skanowane.
  • mcp.json: konfiguracja serwera MCP.
  • Folderzy rozszerzeń klienta: nazwane w formie odwrotnej domeny, na przykład com.example.client/, i ignorowane przez wszystkie inne klienty.

Brakujący komponent nie stanowi błędu. Jeśli katalog skills nie istnieje lub plik mcp.json nie jest zwykłym plikiem, ten typ komponentu jest oznaczony jako nieważny, podczas gdy pozostałe ładowane są jak zwykle.

Konfiguracja MCP

mcp.json musi zawierać dwa pola najwyższego poziomu: $schema oraz mcpServers. Wersja pola $schema musi być identyczna z tą zadeklarowaną w pliku plugin.json; w przeciwnym razie cała konfiguracja MCP zostanie odrzucona.

Zdefiniowano trzy sposoby transmisji danych:

  • stdio uruchamia lokalny proces potomny. Pole command reprezentuje jeden token wykonywalny – albo prostą nazwę rozwiązującą się przez ścieżkę systemową PATH, albo ścieżkę względną do pliku wtyczki zaczynającą się od ./. Opcjonalne pola to args, env oraz cwd, przy czym wartość domyślna dla cwd to korzeń pliku wtyczki.
  • streamable-http to obecny standard MCP Streamable HTTP.
  • sse to starszy sposób transmisji HTTP+SSE z specyfikacji MCP z dnia 2024-11-05, zachowany ze względu na kompatybilność wsteczną.

Klienci muszą przynajmniej zaimplementować stdio lub streamable-http, a ich wspólne użycie jest lepsze. sse jest opcjonalne.

Zmienne środowiskowe i dane trwałe

Za każdym razem, gdy klient uruchamia proces stdio, musi ustawić dwie zmienne. PLUGIN_ROOT zawiera bezwzględną ścieżkę do katalogu głównego wtyczki. PLUGIN_DATA wskazuje na katalog z danymi trwałymi dostarczony przez klienta, który przetrwa aktualizacje wtyczki i zostanie usunięty podczas jej deinstalacji.

Zmienne ${PLUGIN_ROOT} i ${PLUGIN_DATA} mogą pojawić się w polu args, w wartościach env oraz w cwd. Podstawianie wartości odbywa się w jednej rundzie przetwarzania tekstu prostego. Nie są obsługiwane żadne inne miejsca zastąpienia ani rozszerzanie zmiennych w stylu shella.

Błędy pozostają lokalne

Specyfikacja stosuje zasadę „awaria częściowa nie może prowadzić do kaskadowych problemów” na kilku poziomach:

  • Nieudane uruchomienie jednego serwera MCP nie wpływa na pozostałe serwery ani umiejętności.
  • Umiejętność o błędnym formacie jest pomijana, podczas gdy reszta ładowa się normalnie.
  • Wpis MCP używający transportu, którego klient nie obsługuje, jest pomijany.
  • Jeśli plik mcp.json jest całkowicie nieważny, wyłączane są tylko komponenty MCP, a umiejętności nadal się ładowają.

Co pomija specyfikacja

W wersji 1 brakuje informacji na temat sposobu instalacji wtyczek, kontroli uprawnień w czasie wykonywania, uwierzytelniania autorów oraz bezpiecznego przechowywania sekretów lub kluczy API. W tekście wyraźnie stwierdza się, że wartości nagłówków i wartości środowiskowe to widoczne dane pakietu i nie stanowią skutecznego sposobu na zachowanie poufności informacji. Brakuje również konfiguracji OAuth oraz pola do przechowywania referencji uprawnień, więc autoryzacja musi być obsługiwana przez każdego klienta na własny sposób.

Kto jest włączony, a kto nie

Wsparcie startowe obejmuje sześć klientów: Kiro, VS Code, Cursor, GitHub Copilot, Codex i ChatGPT. Google dołączył jako administrator tego samego dnia, a jego Agents CLI należy do pierwszych produktów, które przyjęły ten format. AWS również jest jednym z wspierających.

Anthropic stworzył zarówno format umiejętności, jak i MCP, a Claude Code od 2025 roku używa niemal identycznego pakietowania wtyczek. Mimo to Anthropic nie brał udziału w grupie roboczej, a Claude Code nie znajduje się na początkowej liście wsparcia.

Przykład end-to-end z Google’s Agents CLI

Agents CLI należy do wczesnych użytkowników tego rozwiązania. Po zainstalowaniu dostarcza agentowi programistycznemu siedem umiejętności obejmujących wzorce ADK, tworzenie szkieletu projektu, ocenę, wdrożenie oraz możliwości monitorowania.

Rozważmy stworzenie asystenta wiedzy typu RAG. Programista opisuje cel prostym językiem, a agent działa samodzielnie:

  1. Tworzy szkielet projektu na podstawie szablonu ADK agentic_rag, używając Vector Search jako magazynu danych.
  2. Zauważa, że szablon nie posiada wsparcia dla cytowań, przepisuje instrukcje agenta tak, aby wymagał cytowań w tekście, i zmienia mechanizm wyszukiwania tak, by zwracał identyfikatory źródeł.
  3. Ustawia magazyn danych, ładowa 12 dokumentów referencyjnych w Pythonie jako korpus i przeprowadza test wstępny.

Przed wdrożeniem przeprowadzana jest ocena: 20 przypadków testowych w czterech grupach – 6 dotyczących dokładności wyszukiwania, 5 odmowy odpowiedzi przy braku kontekstu, 5 rozumowania wieloetapowego oraz 4 dokładności cytowań.

Ocena ujawniła jeden przypadek krawędziowy, który powodował halucynacje. W przypadku pytań poza zakresem korpusu agent czasami odpowiadał na podstawie wiedzy ogólnej zamiast przyznać, że nie wie. Przyczyną było pojedyncze zdanie w instrukcjach systemu, stwierdzające, że proste pytania o znane odpowiedzi można odpowiedzieć bezpośrednio, bez użycia narzędzi. Usunięcie tego zdania całkowicie rozwiązało problem.

Rozwój w Google Cloud trwa od dwóch do trzech minut, przy czym Cloud Trace jest włączony domyślnie. Po zarejestrowaniu się w Gemini Enterprise wszyscy w organizacji mogą znaleźć i używać agenta.

Podobne artykuły

← Wszystkie artykułyWyślij brief