Ансара

Пакеты автора: цикл, секции, коды

Как собрать пакет агента китом, загрузить его в свою песочницу и проверить в Бот-тесте; из чего он состоит и какими кодами дверь называет ошибку.

Пакет автора — агент, его навыки и знания, шаги-код и сценарии одним архивом. Коннектор описывает связь компании с её системой; пакет описывает, как отвечает клиентам сам агент. Пакет ставится только в песочницу автора: у компании загрузки пакета нет.

Цикл

Команды — те же пакета проверки, что в Быстром старте: скачать его и сверить сумму нужно до первого запуска. Аргументы команд — node dala-connector-kit.mjs --help.

  • `init` — кладёт шаблон пакета: агент, навык, знание, шаг с примером, кейс передачи человеку. Шаблон проходит check как есть: правьте его, а не пишите пакет с нуля.
  • `check` — правила двери локально, без базы; примеры шага-кода выполняются локально дважды. Имя пакета, версии, роли и библиотеки check не судит: их судит дверь при загрузке.
  • `pack` — собирает zip-архив пакета, не больше 2 МБ.
  • Загрузка. В кабинете песочницы (код компании sbx-…), в разделе «Пакеты», владелец нажимает «Загрузить пакет». Дверь проверяет архив теми же правилами, что check, плюс правилами имени и версий, ставит пакет и включает его в этой песочнице одним действием.
  • Бот-тест. Откройте «Бот-тест» песочницы и говорите с агентом пакета: его тон, его навыки и знания, расчёт его шага-кода.

catalog --packages печатает глаголы каталога платформы и чтения шага, на которые пакет может ссылаться.

Новая версия своего пакета — загрузка архива ещё раз: прежняя версия снимается, новая ставится с новым согласием. Версия в package.json — больше всех уже загруженных.

Секции

Пакет в файлах — format: "0.2" (с папками skills/ и knowledge/). Раскладка:

my-package/
  package.json              голова и оглавление секций
  agents/<id>.json          агент пакета
  agents/<id>.md            инструкции агента
  skills/manifest.json      библиотека навыков пакета
  skills/<навык>/SKILL.md
  knowledge/<id>.md         знание: заголовок навыка, свободный текст без сумм с валютой
  code/<ref>.json           шаг-код: схемы, чтения, примеры
  code/<ref>.js             текст шага
  scenarios/<agent_ref>.json
  • package.json — голова: format, id, version, capabilities — список {ref, module_id, start_mode}, steps, needs и оглавление секций: agents, code, scenarios.
  • agents/<id>.json и agents/<id>.md — агент пакета и его инструкции. Агент с ролью «отвечает клиентам» — ровно один: «Включить» ставит его на клиентский канал песочницы. Вместе с ним agent_extension не допускается.
  • skills/manifest.json и skills/<навык>/SKILL.md — собственная библиотека навыков пакета. Её публикует и закрепляет сама загрузка: отдельно публиковать нечего.
  • knowledge/<id>.md — знания агента в той же библиотеке: заголовок навыка (name, description, metadata с разделом «Знания» и required: нет) и свободный текст, кроме сумм с валютой: цену называет каталог или шаг расчёта, а телефон и адрес знанию можно. Знание едет в ход после навыков и первым уходит, если бюджета хода не хватает; поэтому у него только required: нет, иначе — knowledge_required. Раздел «Знания» — только у knowledge/: навык из skills/ с ним и знание с другим разделом — knowledge_section_reserved. Каждое знание названо в оглавлении skills/manifest.json.
  • code/<ref>.json и code/<ref>.js — шаг-код: схемы, чтения, примеры и необязательный start_mode. Исполняется только на отдельном исполнителе авторов, в вашей песочнице; не ответил исполнитель — примеры шага не проверены, версия не публикуется.
  • scenarios/<agent_ref>.json — сценарии агента, ключ файла — адрес агента. Нужен хотя бы один с checks.outcome.status: "escalated" — передача человеку: без него дверь ответит evals_missing.

Режимы. start_mode способности и шага — не выше потолка: меньшего из потолка каталога и потолка установки (запись и выход наружу у автора — не выше approval). После «Включить» режимы из манифеста записывает set-mode, и только в песочнице; режим выше потолка — start_mode_above_ceiling.

Чего пакету автора нельзя. Документы процесса (граф v1) публикует только платформа: дверь ответит process_graph_publisher.

Коды

Кит и дверь называют ошибку одним кодом. Слова ниже печатает код платформы, а не рука: страница с дверью не разойдётся.

Правила проверки пакета

  • schema_invalid — манифест не той формы
  • capability_unknown — глагол не из каталога платформы — запросить глагол: /developers/packages#request-verb
  • handover_missing — процесс с клиентом без исхода «к человеку» (escalated)
  • evals_missing — процесс без сценария
  • role_unknown — роль своего агента пакета ни из реестра ролей, ни из roles манифеста
  • role_conflict — роль уже в реестре с другой подписью, описанием или признаком: реестр только дописывается, ключ не переименовывается
  • agent_unknown — ведущий процесса или запуска — не свой агент пакета
  • skill_unknown — набор навыков или навык не опубликован в каталоге платформы
  • module_unknown — модуль не из каталога платформы или не объявлен нуждой пакета
  • ref_immutable — адрес процесса уже в реестре с другим документом: адрес неизменяем — правленый документ публикуется новым адресом
  • ref_stale — новый адрес процесса не старше всех адресов его ключа в реестре
  • process_ref_taken — ключ процесса занят другим пакетом реестра
  • start_mode_above_ceiling — режим способности или шага выше потолка: каталог ∩ потолок установки (запись автора — не выше approval)
  • process_graph_publisher — документ процесса (граф v1) публикует только платформа: процесс автора — делом (PW-S1)
  • client_facing_conflict — агент «отвечает клиентам» у пакета автора — один и без agent_extension: «Включить» ставит его на канал песочницы
  • code_module — код шага — один скрипт без import, require, import(), перехвата исключений и async
  • code_examples — пример шага не сошёлся с ожидаемым итогом (или примеров нет)
  • code_impure — два прогона примера дали разный итог: шаг не чист
  • code_ref — адрес шага — не адрес своего пакета <пакет>.<существительное>.<глагол>@<ревизия>
  • code_publisher — код автора исполняется только в его песочнице, на отдельном исполнителе: у компании и из /admin секция code автора не публикуется
  • code_ref_immutable — адрес шага уже в реестре с другим кодом: один адрес — один код, правленый шаг публикуется новой ревизией

Файлы и архив

  • archive_invalid — архив не наш или повреждён: zip без сжатия, только файлы пакета, не больше 2 МБ
  • format_unsupported — формат файлов пакета не поддерживается (нужен format 0.1 или 0.2; skills/ — только у 0.2)
  • secret_in_file — в файле — значение формы ключа: секреты в пакет не кладут
  • tenant_authored — часть помечена «правлено компанией»: в чужую компанию она не ставится
  • knowledge_section_reserved — раздел «Знания» — только у файлов knowledge/<id>.md: навык из skills/ его не берёт, у знания другого раздела нет
  • knowledge_required — знание — только «required: нет»: «всегда» вытеснило бы навыки из бюджета хода — знание едет после них
  • version_stale — версия не старше опубликованных: новая версия пакета — старше всех
  • version_conflict — эта версия уже опубликована с другим содержимым: версия неизменяема

Отказы загрузки

  • not_owner — Загружает пакет только владелец песочницы.
  • package_upload_sandbox_only — Пакет автора загружается только в песочницу (sbx-…): у компании загрузки нет.
  • package_id_taken — Имя пакета занято другой песочницей или платформой: выберите другое имя в package.json.
  • package_tenant_inactive — Песочница не активна — загружать в неё нельзя.
  • package_quota_names — У песочницы исчерпан предел имён пакетов: новое имя не заводится — загружайте новые версии своих пакетов.
  • package_quota_versions — У имени пакета исчерпан предел версий: новая версия не публикуется.
  • package_upload_rate — Слишком много загрузок за час — повторите позже.
  • actor_missing — Нет учётки сессии: загрузка без подписи того, кто её нажал, не идёт.
  • uninstall_failed — Прежнюю версию пакета не удалось снять — новая не поставлена. Снимите её на вкладке и повторите.
  • author_failed — Не удалось записать установку пакета — повторите позже.
  • window_missing — Окна автора в базе нет (Docs/sql/op-s1e-author-sandbox.sql) — это окно владельца платформы.
  • check_failed — проверка архива не прошла — не записано ничего
  • archive_too_large — архив больше 2097152 байт — пакет текст, а не медиа; тело не дочитано
  • executor_unavailable — Исполнителя шагов-кода нет или он не ответил — примеры шага не проверены, версия не опубликована.
  • package_installed — У компании уже стоит другая версия этого пакета — обновление версии отдельным актом.
  • package_name_taken — У компании уже есть агент, фоновый запуск или процесс с этим именем не от этой установки — пакет не поставлен.
  • package_library_foreign — Библиотека чужого пакета: её закрепляет только песочница — владелец имени пакета.
  • package_awaiting_connection — Пакету нужно подключение, которого у компании ещё нет или оно не готово.

Запросить глагол

Дверь ответила capability_unknown: глагола нет в каталоге платформы. Пакет ссылается на действие, которого платформа пока не умеет. Возьмите подходящий глагол из catalog --packages или запросите новый — его добавляет платформа, а не пакет; пока его нет, шаг, которому он нужен, в пакет не кладите.

Что отправить платформе:

  • Глагол словами — что он делает, одной строкой.
  • Вид — query (читает и отвечает), command (меняет данные платформы) или egress (доставляет наружу).
  • Зачем он агенту — какой вопрос клиента или шаг сценария без него не закрыть.

Эта страница в Markdown