agent

Agent-компоненты: именованные роли и специализированные subagents внутри сетапа.

agent

agent описывает специализированную роль внутри харнесса: область ответственности, входы, ограничения, инструменты, которыми она может пользоваться, и ожидаемый результат.

Agent отвечает на вопрос: какая именованная роль должна нести этот класс работы?

Он не отвечает «как эта роль должна делать работу?» (skill), «какие постоянные правила относятся ко всем?» (instruction) и «какой пакет расширяет харнесс?» (plugin).

Agent-компонент не является отдельным сетапом. Он входит в сетап одного харнесса и наследует его границы.

!!! warning "Вид agent — не AGENTS.md и не CLI Agent Skill"

Файл с именем `AGENTS.md` — кросс-харнесс соглашение об
**instruction**. Вид `agent` — определение роли, обычно файл под
каталогом `agents/`.

CLI также поставляет один канонический Agent Skill, который учит
агента управлять самим `ai-stp`. Этот объект ставится командой
[`ai-stp skill install`](../cli/skill.md). Это **не** компонент
каталога и **не** этот вид.

| Объект | Вид / семейство команд | Живёт в сетапе? |
| --- | --- | --- |
| Файл роли под `agents/` | вид `agent` (эта страница) | да |
| `AGENTS.md` | [`instruction`](instruction.md) | да |
| CLI Agent Skill | `ai-stp skill install` / `status` / `remove` | нет |

Соседи

Выбирайте agent, когда нужна ограниченная роль с проверяемым результатом. Выбирайте skill, когда нужна процедура, которой эта роль будет следовать. Выбирайте instruction, когда текст применяется без имени роли.

Рекомендуемая структура пакета

agent декларативен. --language — none. Роль обычно — один Markdown-файл. Claude Code авторит agents как файлы в directory-shaped layout; adopt принимает этот одиночный файл без дополнительного манифеста-обёртки.

Переносимый пакет (то, что discover / adopt переносят из source/):

reviewer/
└── reviewer.md                    # {name}.md в корне пакета

Когда вы начинаете из ai_stp, стартуйте intent author. Не набирайте component scaffold plan. Авторский каталог шире опубликованного пакета: discover / adopt переносят source/ для portable и projections/<harness>/ для конкретного харнесса, а не всё дерево. Агенты Codex — TOML под agents/.

reviewer/                          # component-scaffold/6
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    └── reviewer.md

Повседневное авторство:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert recovery (уже есть digest):

ai-stp component scaffold plan \
  --type agent \
  --language none \
  --harness portable \
  --name reviewer \
  --output ./reviewer \
  --json

ai-stp component scaffold apply \
  --type agent \
  --language none \
  --harness portable \
  --name reviewer \
  --output ./reviewer \
  --expected-plan-digest <digest> \
  --json

--language для agent — none. Вид декларативный.

Опишите цель роли, инструменты, которыми она может пользоваться, как выглядит готовый результат и когда её вызывать. Не описывайте глобальную замену всех инструкций, секреты или право менять внешний мир без подтверждения.

Команды ai-stp component agent validate нет. Структурная готовность — component passport validate. Kind-specific проверка по спецификации есть только у skill.

Стандарты и фреймворки

Независимой спецификации роли agent, сравнимой с Agent Skills Specification, нет. Skill — переносимый workflow; agent — роль.

Ссылайтесь на layout_source из конверта intent author, когда классификация неясна. Custom agents Codex документированы только из .codex/agents — не выдумывайте второй каталог.

NVIDIA SkillSpector и Cisco Skill Scanner — сканеры skill. Это не валидатор этого вида.

Нативные layout по харнессам

Discovery сообщает только объявленные layout. Точные пути на машине даёт конверт intent author. У каждой находки есть layout_source. Если классификация неясна, покажите это поле; не угадывайте путь соседа.

Из матрицы discovery:

Внутри доказанного Claude Code plugin discovery читает agents (каждый потомок — один agent). Внутри доказанного Cursor plugin — то же самое. Walker не изобретает файлы agent из соседнего каталога.

Одиночный файл в directory-shaped layout дополнительного манифеста не требует — так авторят agents Claude Code, и adopt их принимает.

Expert recovery — повседневное авторство это intent author:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Не набирайте component discover. Движок сам находит нативное дерево.

Версии — X.Y, не SemVer

Опубликованная версия agent неизменяема и имеет вид X.Y. Патч-номера нет. Изменение текста роли, её инструментов или ограничений — новая версия. Обновление agent внутри сетапа — новая версия сетапа.

ai-stp component version list --id <stable_id> --json
ai-stp component version release --id <stable_id> --json

--major открывает следующую мажорную линию. Мажорная линия — отдельная граница доступа.

Что проверяет ai_stp

Процент карточки каталога и разделение обязательных и необязательных проверок объяснены на странице Проверки безопасности. Для agent ожидайте как минимум:

• структуру, digest, лицензию, tags, исходный репозиторий;
• ограниченную распаковку и path denylist;
• сканирование секретов (secrets_heuristic и Gitleaks, если включён);
• правила prompt-injection и скрытого содержимого;
• языковой SAST и SCA, когда есть scripts и lockfiles.

Пройденное сканирование снижает известный риск. Это не гарантия, что роль безвредна. Обязательные проверки, которые провалились или не смогли запуститься, блокируют публикацию.

Перед установкой также смотрите:

author_verified и component_verified независимы. Ни одно не является гарантией безопасности.

Связанные команды CLI

Только команды, которые существуют. Флаги всегда со страниц CLI и всегда --json. Исполняемый файл — ai-stp (пакет ai-stp-cli). Команд component inspect и setup show нет. Единственный kind-specific validate — ai-stp component skill validate.

Именно этот вид: команды component agent validate нет. Используйте проверку паспорта.

ai-stp component passport validate --id <stable_id> --json

Не этот вид — CLI Agent Skill (см. Agent Skill CLI):

ai-stp skill status --json

Автор, adopt, публикация:

ai-stp task start --intent author --idempotency-key author-session-01 --json
ai-stp task start --intent publish --idempotency-key publish-session-01 --json

Установить:

ai-stp task start --intent install --idempotency-key install-session-01 --json

Expert-просмотр каталога:

ai-stp registry search --kind component --query <name> --json

Agent может быть embedded-членом compose-манифеста. См. Сетапы.

Как agent проходит через ai_stp

=== "Автор" Автор публикует роль из публичного GitHub-источника или импортирует её локально. Версия закрепляет точный commit и подпуть.

=== "Каталог" Каталог показывает роль, поддерживаемые харнессы, ограничения, trusted status автора и независимый status самого компонента.

=== "Сборщик" Сборщик проверяет, поддерживает ли харнесс такую agent surface и что файловая структура подходит проекции provider.

=== "Provider" Provider создаёт нативное описание роли только после плана, digest и подтверждения. Status показывает, какие роли активны и откуда они пришли.

Красные флаги

• Обращение с AGENTS.md как с видом agent.
• Обращение с ai-stp skill install так, будто оно опубликовало этот компонент.
• Роль без ограничений, без ожидаемого результата и с каждым tool включённым.
• Codex agents откуда угодно, кроме .codex/agents.
• Живые токены, закрытые ключи или тела .env в пакете.
• Инструкции игнорировать предыдущие инструкции или расширять права во время выполнения.
• Линия доверия experimental без consent allow.
• Харнесс не в списке совместимости компонента.
• «Latest» или имя ветки вместо точных X.Y и commit.
• Обращение с author_verified как с component_verified.
• Subagent, которому разрешено менять внешний мир без пути подтверждения.

??? question "Можно ли agent использовать без публикации" Да. Собственную, импортированную или точно закреплённую роль можно использовать после локальных проверок. Она от этого не становится platform-verified и должна быть показана именно как локальный или закреплённый объект (local_owner_or_pinned).

Чеклист автора

1. Сделайте scaffold с --type agent --language none и держите Markdown в корне пакета (в авторском дереве — под source/).
2. Назовите роль, её ограничения, её tools и как выглядит «готово». Постоянные правила положите в instruction, процедуры — в skill.
3. Объявите потребности в авторизации в паспорте. Секретов нет.
4. Зарегистрируйте каталог через ai-stp task start --intent author --idempotency-key author-session-01 --json. Expert component discover / component adopt остаются для recovery.
5. Закрепите точный публичный GitHub commit и подпуть.
6. component passport validate → component version release, чтобы выпустить неизменяемый X.Y.
7. Публикуйте через путь публикации.
8. В сетапе закрепите этот X.Y. Позднее обновление — новая версия сетапа.

Связанное: Авторство, Компоненты, instruction, skill, CLI Agent Skill.