Системные агенты и runner-agent

Системный агент — версионируемая программа AI Router, которая выполняется внешним runner-agent. Это отдельная сущность: ассистенты остаются карточками интерактивного AI-чата и не требуют runner.

Компоненты

flowchart LR
  Client[Web или API] --> Router[AI Router]
  Router --> Commands[Command Manager]
  Commands --> Runner[runner-agent]
  Runner --> Runtime[Runtime API AI Router]
  Runtime --> Provider[LLM и tools]
  Runner --> Commands
  Commands --> Router
  Router --> Storage[Storage]

• AI Router хранит определения и версии, проверяет политики, выдаёт краткоживущий job token, проксирует LLM/tools/RAG и сохраняет результат.
• Command Manager назначает job совместимому online runner, передаёт progress и управляет отменой.
• runner-agent выполняет agent loop без подключения к PostgreSQL и без постоянных ключей провайдеров.
• Storage хранит итоговые артефакты.

Если совместимого online runner нет, агент недоступен. AI Router не выполняет его внутри своего процесса и не создаёт job, который останется в pending.

Определение агента

AgentDefinition задаёт стабильную идентичность агента. Каждая публикация создаёт неизменяемую AgentVersion. Запуск всегда ссылается на конкретную версию и resolved snapshot:

• system prompt, rules и skills;
• input/output JSON Schema;
• pipeline steps;
• allowlist tools, MCP и scopes;
• требуемые capabilities runner;
• лимиты шагов, времени, токенов и вызовов tools.

Состояния версии: draft, quarantined, published, superseded, rejected. Опубликованная версия не редактируется; изменение создаёт следующую версию. Переключение active version и rollback выполняет администратор.

Пакет .usagent

.usagent — ZIP-контейнер со следующей структурой. Готовые пакеты, включая встроенные artifact-агенты, лежат в каталоге unishift.ru/agents:

manifest.json
signature.json

manifest.json содержит:

• schema_version: "1", slug, name, system_prompt;
• runtime, pipeline и input/output schemas;
• tools, skills, scopes, MCP и runner capabilities;
• budgets и artifact finalizer.

signature.json содержит Ed25519 key_id, algorithm и подпись канонического manifest. Пакет с неизвестной или отозванной подписью помещается в quarantined и не может активироваться автоматически.

Импорт отклоняет:

• абсолютные пути, .., symlink и повторяющиеся пути;
• archive bombs и превышение лимитов;
• неизвестные поля manifest и некорректные schemas.

Исполняемая логика добавляется через зарегистрированный tool, MCP или новую capability runner; package-код не исполняется.

Создание через интерфейс

1. Открыть Настройки → AI Router → Агенты и нажать Добавить.
2. Указать slug, название и источник. Для локального выполнения выбрать Native / runner.
3. В редакторе заполнить системный промпт, tools, требуемые capabilities, лимиты и JSON-конфигурацию.
4. Нажать Опубликовать, затем Экспорт .usagent.

При изменении опубликованного агента создаётся новая immutable-версия. Экспорт можно использовать для переноса определения между установками Unishift.

Создание вручную

Минимальный manifest.json:

{
  "schema_version": "1",
  "slug": "my-agent",
  "name": "My agent",
  "runtime": "native",
  "system_prompt": "Выполни задачу и верни структурированный результат.",
  "tools": ["web_search"],
  "requires": ["agent.run.v1"],
  "max_steps": 8,
  "max_tool_calls": 6,
  "token_budget": 32000,
  "timeout_seconds": 600,
  "input_schema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" }
    }
  }
}

Упаковать manifest в ZIP с расширением .usagent:

zip -X my-agent.usagent manifest.json

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

{
  "key_id": "release-key",
  "algorithm": "ed25519",
  "value": "<base64 Ed25519 signature>"
}

Подпись вычисляется над канонизированным содержимым manifest, а публичный ключ заранее регистрируется в trust store AI Router. Неизвестный или отозванный key_id не позволяет автоматически активировать пакет.

Runtime security

Runner получает только immutable snapshot и краткоживущий token со claims:

• run_id, пользователь и tenant;
• версия определения;
• allowlist tools, scopes и MCP;
• budgets и срок действия.

AI Router повторно проверяет claims, ACL, quota и статус run при каждом runtime-вызове. Ключи LLM/MCP, credentials Storage и долгоживущие пользовательские токены runner не получает.

Внешние агенты

Поддерживаются два способа:

1. Импорт Cursor rules, AGENTS.md, skills и custom agents в draft AgentVersion с отчётом о несовместимых возможностях.
2. Регистрация remote A2A endpoint. Framework-код LangGraph, CrewAI или OpenAI Agents остаётся во внешней системе.

A2A endpoint вызывается через защищённый egress AI Router: HTTPS, allowlist, проверка DNS и redirects, блок private/link-local/metadata адресов, лимиты размера/времени. Credential задаётся ссылкой на env secret и не хранится в Agent Card или manifest.

Встроенные artifact agents

artifact-pptx, artifact-drawio и artifact-bpmn возвращают типизированный IR. Runner выполняет исследование, построение, QA и repair. AI Router валидирует IR, детерминированно формирует файл и загружает его с пользовательским ACL.

Эти агенты доступны только при наличии runner с соответствующей capability. Стандартные режимы chat, plan, obs и spec продолжают работать без runner-agent.

Исследование таблиц

data-table-analysis (packs/usagent/data-table-analysis) читает Data Tables текущего пространства через search_tables, get_table и list_table_rows. Агент считает агрегаты только по возвращённым строкам. list_table_rows отдаёт не больше 200 строк за вызов; если таблица прочитана не целиком, coverage.complete равен false. Запись, вставка и удаление строк этому агенту не разрешены.

Веб-исследование

web-research (packs/usagent/web-research) по теме строит план из нескольких запросов, ищет через web_search и читает страницы через fetch_url. Отчёт приходит как JSON: заголовок, краткое содержание, оглавление, текст Markdown, факты и список URL. Каждый факт ссылается на адрес из результата инструмента. Если поиск пустой, агент так и пишет и не добавляет источники.

Извлечение со страницы

page-extract (packs/usagent/page-extract) получает http(s)-адрес и список полей. Страница читается одним вызовом fetch_url, значения копируются из текста. Ответ — JSON: адрес, краткое содержание, элементы с парами name/value и массив missing для полей, которых на странице не было. Другие адреса агент не открывает.

Глубокое исследование

deep-research (packs/usagent/deep-research) строит 6–8 запросов, отбирает до десяти страниц и читает каждую через fetch_url с max_chars 8000. Отчёт длиннее, чем у web-research: заголовок, краткое содержание, оглавление, Markdown, выводы с URL и массив gaps. Второй проход только разворачивает уже прочитанный текст. Углы, которых не было на страницах, попадают в gaps.

Разбор запуска

launch-intelligence (packs/usagent/launch-intelligence) получает компанию или продукт и один вид отчёта: competitor, sentiment или metrics. Если вид не назван, готовится конкурентный разбор. Агент ищет через web_search и читает до восьми страниц через fetch_url. Строки отчёта ссылаются на URL. Неопубликованные KPI и отсутствующие темы попадают в gaps. За один запуск готовится один вид отчёта.

Новостная статья

news-article (packs/usagent/news-article) по теме составляет три запроса, ищет через web_search и читает до восьми страниц через fetch_url. Ответ — JSON: заголовок, лид, текст статьи в Markdown, список URL и gaps. Последний шаг выкидывает повторы и фразы, которых не было в источниках. Если материала мало, статья короче, а недостающие углы попадают в gaps.

Canary rollout

1. Применить миграции AI Router и Command Manager.
2. Установить один runner-agent, проверить /runners/availability?type=agent&capability=agent.run.v1.
3. Запустить тестовую AgentVersion; проверить progress, cancel, budgets и отсутствие соединений runner с PostgreSQL.
4. Активировать artifact agents по одному и проверить typed IR/finalizer.
5. После canary опубликовать бинарники для остальных OS/arch и развернуть дополнительные runner instances. При откате остановить runner и переключить active version; стандартные chat modes не затрагиваются.