Agent Plugins 1.0.0: агульны фармат пакавання для навыкаў і MCP-сервераў
Agent Plugins 1.0.0 дае навыкам і MCP-серверам адзін фармат пакавання: тэчкі, plugin.json і mcp.json, што застаецца па-за ім у плане бяспекі і прыклад з CLI.
Google, Microsoft, OpenAI, Cursor, Vercel і AWS падтрымліваюць праект Agent Plugins 1.0.0 – спецыфікацыю, якая адгукваеся да таго, як пакаваць плагіны для AI-агентаў. Яна усталявала структуру дырэктарыяў, фармат файлаў налашчэння і правілы аднаходжэння двух тыпаў компанент: навыкаў і сервераў MCP. Мета простая: напісаць плагін аднойчы і запусціць яго ў будзь-ям сумесным кліенце.
Да гэтага часу існавалі два звычных спосабы надаць кодавальнаму агенту новых можлівасцей. Навык – гэта набор інструкцыяў у фармаце Markdown, якія агент чытае, калі іх патрэбуе. Сервер MCP – гэта околачны працэс, які паў’язвае агента з зовнішнімі інструментамі, API-мі або базамі дадзеных. Контэнты обох тыпаў ужо моглі быць перанесены між інструментамі, але кожны інструмент меў свае правілы ў структуры дырэктарыяў, назвах файлаў налашчэння і месцах ўтрымання файлаў.
Версія 1.0.0 адаптаваеся толькі да зовнішньага пакета. Яна не вплывае на внутрэшню структуру навыку і сам протакол MCP.
Чаму гэта важліва
Гэтае рашыненне стосуецца трох прыгруп:
- Автары плагінаў атрымліваюць адну структуру каталога, якая працуе ў кожным падтрымліваным кліенце. Не трэба больш трываць окалічныя копіі для Cursor, Copilot, Codex і іншых.
- Продавцы інструментаў атрымліваюць фіксаваныя месцы для
skills/іmcp.json, таму ім не трэба ствараць логіку пошуку чы аналізу налашчэнняў. Продавець все ўсё можа дадаць свае дадатковыя элементы ў каталог з іменам пространства, не парадзейчы іншым рэалізацыям.
Меры обмежэння таксама ўсё такія ж ясныя. Стандарт стандартызуе пакетны абгортак і нічога не гаворыць пра безпеку таго, што ўнутры. У яго няма падпісаў, няма модэлі прав і няма механізмаў адрабаткі секрэтных дадзеных. Наразе прынцыпавая перавага — гэта эфектываасць распрацоўшчыкаў, а ён не дае гарантый безпекі чы сапраўднай доверлівасці.
Структура каталога
Плагін, які адпавядае стандартам, — гэта проста папка. Для прыклада пад назвай reports-plugin цэлыя структура выглядае так:
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
Кліянты пераглядаюць толькі тры месцы. Файл plugin.json пазначае папку як дыявальны плагін. Кожная падпапка першага рэвэлю катэгорыі skills/, якая мае файл SKILL.md, лічыцца як адна навык. А файл mcp.json чытаецца як канфігурацыя сервера MCP. Папкі, названые у стылі зворачанага домэна, напрыклад com.cursor.tools/, чытаюцца толькі кліянтом, да якога яны належаць, тут — Cursor. Іншыя кліянты, у тымчасце ChatGPT і Codex, проста іх ігнаруюць.
Маніфест plugin.json
plugin.json — ўжо ўсё, што ўмовна неабходна, і мінімальны варыянт гэтага файла ўжо дужа маленькі:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "hello-plugin"
}
Шымат гэтакі, што дазволены дзесяць поля вышэйшага рангу: $schema, name, version, description, author, homepage, repository, license, keywords і extensions. Нявядома польна фіксуецца і ігнаруецца, і плагін усё рава завантажваецца. Аднак, калі name некарэктны, гэта стварае іншыя проблемы. Калі ён неяўны, мае неправы тып або містыць незаконныя сімвалы (верхнія літэры, подвойныя гільдзіні, порожняя строчка), то весь плагін адхоўваецца.
Правілы для name: ад 1 да 64 сімволаў, складаецца з малых літэр, цыфр, гільдзініў і калонкаў. Ён павінен пачынацца і заканчывацца літэрай або цыфрой, а падрад два гільдзініяў або два калонкі ўзятыя пад заборону.
Як знаходзяцца компаненты
Адккрыцце адбываецца выключна на адміністрацыі каталогаў. Файл plugin.json не можа пераместыць компаненты в інша месца чы прыемкнуць іх настройкі безпосерэдна. Існуе толькі тры відмены месца размешчэння:
skills/: любы падкаталог першага рэвэлю, які мае файлSKILL.md, ўважаецца навыкам. Глыбэйшыя каталогі скануюцца не атрымліваюцца.mcp.json: настройкі сервера MCP.- Каталогі расшырэння кліента: іменуецца ў фармаце зворачанага домэна, напрыклад
com.example.client/, і ігнаруецца всімі іншымі кліентамі.
Абсэнцыя компаненты не ўзначае адказку. Калі каталог skills не існуе, чы файл mcp.json не ў фармаце звычайнага файла, тады такі тып компаненты пазначаецца як нэвалідны, тады калі іншыя компаненты завантажуюцца як звычайна.
Настройкі MCP
mcp.json патрабуе два поля вышэйшага рэвэля — $schema і mcpServers. Версія $schema павінна быць такой жа, як і тая, якая зазначана ў plugin.json; інакша вся конфігурацыя MCP будзе адхоўвана.
Заўважаны трохі спосабы перадачы дадзенняў:
stdioзапускае локальны дзеціны працэс.command— гэта адны экзекуямы токен: або простае імя, якое аднаходзіцца праз сістэмны PATH, або шлях, які адносіцца да плагіна і пачынаецца з./. Апшыякаваныя поля —args,envіcwd; значэннеcwdза замовчаннем — корань плагіна.streamable-http— гэта чынны стандарт MCP Streamable HTTP.sse— гэта старэйшы спосаб перадачы дадзенняў HTTP+SSE з спецыфікацыі MCP з 2024-11-05, які застаўся для адваротнай сумеснасці.
Кліенты должны іспользоваць прынеймна stdio або streamable-http, прытаму stdio і streamable-http адночасна — гэта лепша апштанка. sse ўжо не ўмовна.
Зменныя сяродавішча і стойкія даны
Калі кліент запускае процэс stdio, ён павінен задаць две зменныя. PLUGIN_ROOT храніць абсалютны шлях да корневага каталогу плагіна. PLUGIN_DATA вядома да каталога стойкіх даных, які надае кліент; гэты каталог застаецца пасля апдэйтаў плагіна і удаляецца пасля яго адключэння.
Зменныя ${PLUGIN_ROOT} і ${PLUGIN_DATA} могу з’являцца ў параметрах args, у значэннях env і ў cwd. Замена адбываецца за адну процедуру працэсавання звычайнага тэксту. Не падтрымваюцца іншыя местападставы і расшырэння змянных у стылі шэлу.
Адказы за абыяканні застаюцца локальнымі
У спефікацыі прыменяецца правіло „частыя неудачы не павінны каскадавацца“ на кальколькох рэвэлях:
- Неудача аднаго сервера MCP у запуску не паўтараецца на іншыя серверы чыста на навыкі.
- Навык з несправным фарматаваннем працягваецца, а рэшта завантажаецца нормальна.
- Энтры MCP, якія вікорыстоўваюць спосаб перадачы дадзеных, які кліент не падтрымлівае, працягваюцца.
- Калі
mcp.jsonў цэлым неякісны, выключаюцца толькі компаненты MCP, а навыкі все равно завантажаюцца.
Што не ўключае спефікацыя
У версіі 1 не ўключаныя элементы: спосаб установкі плагінаў, кантроль прав на час выканання, аўтэнтыфікацыя автараў і безпечная зберогчыца секрэтных даных чыста API-клучоў. У тэксце чытальна зазначаецца, што значэнні заголовкаў і значэнні сераўніка ўважаюцца відкрытымі данымі пакета і не ўтвараюць надзеянага спосабу для зберагчыцы інфармацыі у таёмніце. Таксама няма налаштавання OAuth і поля для кантролю аўтэнтыфікацыйных даных, таму автарызацыю кожны кліент павінен рэгулюваць самастойна.
Хто ўключаны, а хто — ні
Падтрымка запуску распрастраняецца на шасць кліентаў: Kiro, VS Code, Cursor, GitHub Copilot, Codex і ChatGPT. Google таго ж дня стаў адпаведальным за падтрымку, а яго Agents CLI ўваходзіць у чысло першых продуктов, якія адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж адразу ж
Компанія Anthropic створыла як фармат навыкаў, так і MCP, а Claude Code з 2025 года выкарыстоўвае практычна ідэнтычную структуру пакетавання плагінамі. Усё ж такі Anthropic не была часткай рабочай групы, і Claude Code не ўключаны ў пачатковы спіс падтрымкі.
Прыклад «з галавы до галавы» з Google's Agents CLI
Agents CLI ўваходзіць у чысло першых, якія ўзялі ўжоць гэтыя тэхналогіі. Пасля установкі ён надае кодаваючаму агенту семь навыкаў, якія павінны падтрымаць шаблоны ADK, стварэнне структуры праекта, ацэнку, розгортанне і можлівасці аналізу.
Разглядзім возможнасць стварэння асістэнта з базай знанняў у фармаце RAG. Распрацоўшчык опісвае цель простым языком, а агент працюе самастойна:
- Ён стварае структуру праекта на адной з шаблонаў ADK
agentic_rag, выкарыстоўваючы Vector Search як сховішча дадзеных. - Ён з’являе, што шаблон не падтрымлівае цітатаў, перапісвае інструкцыі агента, каб той выкарыстоўваў цітатаўы ў тэксце, і змінюе механізм пошуку, каб той вяртаў ідэнтыфікатары выканаўых джэральнаў.
- Ён стварае базу дадзенаў, завантажвае 12 даследчых дакументаў на Python як корпус і адрабоўвае тэст на працэсаванне.
Перад развертаннем адбываецца ацэнка: 20 тэстовых кейсаў у чатырох групах — 6 на точнасць пошуку, 5 на адмову калі не хапяе кантэксту, 5 на мнагапрыступовае разумаванне і 4 на точнасць цітатаў.
Ацэнка выявіла адзін крайні кейс, які спрычыніў галюцынаціі. Для запытанняў, якія не ўключаныя ў корпус, агент іноды адпавядаў на аднойчыныя ведамасці замест таго, каб з’явіць, што ён не ведае. Прычыной была адна фраза ў інструкцыях сістэмы, якая гаварыла, што простыя запытанні з вядомай адпаведзю можна адпаведзець безпосерэдна без адпаведных інструментаў. Выдаленне гэтай фразы пачало ўсё абдзяцела.
Размешчэнне на Google Cloud займае два-трыя хвіліны, пры чым Cloud Trace ўвімкнуты за замовчанням. Пасля рэўістраціі ў Gemini Enterprise кожны член арганізацыі можа знайсці і выкарыстоўваць агента.
Супаўзвязаныя матэрыялы
- MCP, A2A і ACP у практыцы: як банк сумелівае інструменты і агенты — як MCP, A2A і ACP дзеляць задачы па з’яўленню модэляў з інструментамі і агентамі адно з аднам, показана на прыкладзе працавніка банку, які керуе праносамі і крэдытамі.