Агенты и профили — AiHummer Документация

Агент — это единица, которую AiHummer ставит перед разговором. У каждого агента есть профиль (технический профиль агента; «характер» — только про тон общения), своя модель, структурированный промпт и набор навыков, и любое изменение агента версионируется. Агенты управляются из веб-интерфейса и через админ-API по пути /v1/admin/agents/*.

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

На этой странице — из чего состоит агент, как собирается структурированный промпт «G3» и как агент может безопасно редактировать свой собственный профиль.

Реестр агентов

Реестр — это полноценный CRUD-каталог агентов. Для каждого агента вы задаёте идентичность, профиль, модель, на которой он работает, и навыки, которыми он может пользоваться. Поскольку шлюз мультиарендный, агенты живут внутри рабочего пространства (workspace) и изолированы, как и любые другие данные арендатора.

Профиль — голос и поведение агента, отрисовываемые в стабильный, дружелюбный к кэшу слой системного промпта.
Своя модель на агента — каждый агент может закрепить собственную модель и провайдера, так что дешёвый и флагманский агенты уживаются в одном рабочем пространстве.
Навыки — персональные и общие навыки отрисовывают блок «Навыки» в промпт; они описывают возможности, а не веса модели.

[!NOTE] Своя модель агента не зависит от маршрутизации. Маршрутизация по уровню модели (simple / standard / complex) выбирает класс модели для обработки запроса, а своя модель агента — это его собственное значение по умолчанию. См. Маршрутизацию.

Версии, откат и клонирование

Каждое значимое изменение агента фиксируется как версия. Это делает конфигурацию агента аудируемой и обратимой: можно посмотреть, что изменилось, откатиться к более ранней версии или клонировать агента, чтобы использовать его как заготовку для нового. Ресурсы версий и профиля находятся под /v1/admin/agents/* (профиль, секции, навыки, версии).

[!TIP] Клонируйте рабочего агента перед большой переработкой профиля или промпта. Если новое направление не оправдается, оригинал в одном откате от вас.

Структурированный промпт «G3»

Вместо одного свободного системного промпта AiHummer использует структурированный профиль агента (внутреннее имя — «G3»). Профиль разложен на поля, а не зашита в прозу, а остальная часть промпта строится из именованных секций плюс блока первоначальной настройки. Оркестратор отрисовывает это в слоистый системный промпт, удерживая стабильные части (идентичность, профиль, секции) в кэшируемом префиксе и добавляя изменчивые данные в конце.

Такая структура упрощает правку профиля поле за полем, упрощает дифф между версиями и делает отрисовку предсказуемой — никакого скрытого «промпт-супа».

Профиль G3
├── поля идентичности  (разложены: имя, роль, ...)
├── секции             (именованные, упорядоченные блоки промпта)
└── первоначальная настройка (подсказки для первого запуска)

Самоправка с обязательным одобрением

Агенту можно разрешить редактировать собственный профиль с помощью инструментов самоправки — например, чтобы уточнить секцию или обновить блок первоначальной настройки. Это намеренно ограничено:

Самоправки требуют обязательного одобрения: предложенное изменение фиксируется и должно быть одобрено человеком, прежде чем вступит в силу. Отклонённое изменение никогда не применяется.
Изменение фиксируется как новая версия, поэтому самоправка так же аудируема и обратима, как любая ручная правка.

[!WARNING] Что произойдёт: агент сможет переписать собственную идентичность без контроля. При каком условии: если разрешить самоправку без обязательного одобрения. Как исправить: держите самоправку под обязательным одобрением и просматривайте предложенные изменения так же, как любое привилегированное изменение.

Пароли почты уходят в хранилище секретов

Если в конфигурации агента есть почтовые учётные данные (для инструмента mail), пароль записывается в зашифрованное хранилище секретов, а не хранится в профиле и не отрисовывается в промпт. Секреты не передаются в контекст модели.

Политика выполнения: контекст, сессии и дочерние агенты

С версии 1.3 у агента есть политика выполнения — поле runtime_policy в админ-API (/v1/admin/agents при создании и обновлении). Это строго проверяемый JSON-объект с "version": 1: пустой объект {} возвращает умолчания, пропуск поля при обновлении сохраняет прежнюю политику, а неизвестные поля и значения вне допустимых границ отклоняются. Политика не выдаёт инструментов и не расширяет права — она задаёт только бюджеты и сроки. Клон агента и передача ему хода наследуют её.

context — бюджет истории: max_tokens, reserve_tokens и history_share определяют, сколько истории попадает в запрос; max_history_messages ограничивает окно сообщений, bootstrap_max_chars — размер блока профиля. Когда контекст задан явно, старые сообщения сжимаются в резюме порциями до того, как собирается текущий запрос.
- pruning — очистка устаревших результатов инструментов: по сроку (ttl_seconds), с защитой последних ответов (keep_last_assistants), мягкая обрезка (soft_trim_ratio, head_chars, tail_chars) и полная замена на текст placeholder при превышении hard_clear_ratio. Текст пользователя, изображения и полная история в базе не затрагиваются.
- memory_flush — перед сжатием агент без инструментов записывает короткую заметку о целях, решениях и незавершённых делах (soft_threshold_tokens); последние три заметки того же диалога подмешиваются в контекст как непроверенная справка.
session — жизнь диалога: idle_reset_minutes начинает новый контекст после паузы (сырая история сохраняется), index_prune_after_days и index_max_entries убирают старые диалоги из списка по умолчанию, не удаляя их. scope = per-peer (один диалог на подтверждённого пользователя во всех каналах) или per-channel-peer (отдельный диалог на канал).
children — дочерние агенты: max_depth (до 4), max_concurrent (до 8 на дерево запуска), max_per_parent (до 5), timeout_seconds (до 48 часов, но не дольше родителя) и archive_after_minutes — когда завершённые запуски уходят из списка по умолчанию. Значения переопределяют глобальные AIHUMMER_SUBAGENT_MAX_DEPTH и AIHUMMER_SUBAGENT_TIMEOUT_SEC для этого агента.
max_iterations (1–256) — предел шагов цикла вызова функций для проверенных сценариев с многими делегированиями.
app — только для приложения AiHummer: reasoning_effort, service_tier и режим короткого ответа direct_completion (auto или always с max_tokens до 4096 и timeout_ms до 60 000).
interaction — явные разрешения на работу с сессиями: user_ids, session_agent_ids, spawn_agent_ids, видимость session_visibility (self, agent или granted), session_send, запреты инструментов для дочерних вызовов (child_tool_deny, child_leaf_tool_deny) и elevated_telegram_user_ids — подмножество user_ids, которому разрешён явно повышенный запуск code_exec (одобрения при этом не обходятся). Подстановочных знаков и разрешений на весь арендатор нет.

Админ-API

Агенты и их структурированные профили управляются через админ-API, который закрыт OIDC и аудируется:

Ресурс	Назначение
`/v1/admin/agents`	Список, создание, изменение, удаление агентов (CRUD)
`/v1/admin/agents/.../profile`	Структурированный профиль G3 (поля идентичности)
`/v1/admin/agents/.../sections`	Именованные секции промпта
`/v1/admin/agents/.../skills`	Навыки конкретного агента
`/v1/admin/agents/.../versions`	История версий, откат и клонирование

Куда дальше

Как агент обрабатывает запрос и порождает помощников — в разделе Оркестрация и суб-агенты.
Как входящее сообщение доходит до конкретного агента — в разделе Маршрутизация.
Дайте агентам долговременную память — Память (Einstein).