> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Assistant > Документация AI Assistant AgentEye. Панель управления включает опциональный **AI Assistant** — чат-панель, прикрепленную к правому краю, которая отвечает на вопросы на естественном языке об ваших агентах ("как меняется качество в prod на этой неделе?", "какие сессии упали сегодня?", "суммаризируй эту сессию") и при наличии разрешения пользователя создает и сохраняет SQL-запросы и панели управления от их имени. Ассистент приводит кликабельные ссылки прямо на соответствующие сессии, запросы и панели, и он **осведомлен о странице**: спросите о "этой сессии" во время просмотра — и он поймет, что вы имеете в виду. Панель показывается как тонкая **вертикальная полоса размером 44px** по умолчанию: глиф приглашения `›_` плюс цветная точка статуса. Нажмите на полосу (или нажмите `⌘J` / `Ctrl+J`), чтобы развернуть её в полную панель чата. Развернутая панель **изменяемого размера** между 320 и 640 пиксели путем перетягивания левого края; ваша предпочтительная ширина запоминается после перезагрузки. Работает как маленький внутренний контейнер **`agent`** (на Claude Agent SDK), который может вызывать только панель управления. По умолчанию **отключен** и остается скрытым до конфигурации LLM endpoint. *** ## Что он может и не может делать * **Читает операционные данные, видимые запрашивающему пользователю.** События, оценки, сессии, очередь задач оценки, сохраненные запросы и панели, ограниченные по запросу правами доступа пользователя. Инструменты чтения выполняются немедленно. * **Записи управляются поэтапным одобрением.** Может создавать сохраненные запросы (`create_saved_query`, `update_saved_query`), запускать черновик SQL против роли только для чтения для проверки (`run_query`) и собирать панели из этих запросов (`create_dashboard`, `update_dashboard`, `add_query_to_dashboard`). Каждая запись переходит в режим ожидания для приглашения **Одобрить / Отклонить / задать вопрос** в чате; SDK не вызывает инструмент до нажатия оператором кнопки Одобрить. **Удаление никогда не доступно ассистенту**; деструктивные операции остаются на стороне операторов. * **Черновик SQL проходит ту же валидацию `sql_guard` и роли только для чтения, что и SQL, написанный пользователем** (SELECT/WITH только, без многоинструкционности). Выполнение маршрутизируется в зависимости от таблиц, к которым обращается запрос: запросы, ссылающиеся на таблицы аналитики (события, оценки, сессии), выполняются как пользователь организации только для чтения ClickHouse (ограничиваемый организацией политикой строк, с ограничением выполнения 10s и ограничением строк 100k), тогда как запросы, затрагивающие только реляционные таблицы, запускаются на роли только для чтения Postgres (10s, 10k строк). Ассистент не может расширить поверхность данных; он может только создавать запросы над поверхностью, к которой оператор уже имеет доступ. * Использует **выделенный ключ ассистента** (см. ниже) с фиксированным набором разрешений; даже если модель ведет себя неправильно, она не может выходить за пределы этих областей. * Каждому пользователю панели управления нужно разрешение **`agent:use`** для просмотра и использования ассистента. Инструменты фильтруются по запросу в соответствии с правами доступа пользователя, поэтому пользователь с `events:read` получает инструменты событий, но не инструменты `dashboards:write`. *** ## Осведомленная о странице AI панель: композитор на `/queries`, чат в других местах Ассистент с правой стороны **осведомлен о странице**. Выбор модели, история разговора, точка статуса модели и ввод чата остаются неизменными, но **чипсы пустого состояния, текст-заполнитель и на какой бэкенд-endpoint попадает сообщение пользователя** автоматически переключаются на основе текущего маршрута. Панель становится "AI помощником для любой страницы, на которой вы находитесь". **Два бэкенда, выбранные для каждой страницы (с переопределением по чипу).** | Маршрут | Бэкенд по умолчанию для страницы | Причина | | ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/queries`, `/queries/new` | `POST /api/agent/compose-sql` (без цикла инструментов) | Пользователь начинает с нуля; ≤1s первый токен SQL потоком прямо в редактор | | `/queries/` (существующий) | `POST /api/agent/chat` (полный цикл ассистента), по умолчанию для страницы | Вольные сообщения должны позволить пользователю спросить что угодно ("объясни это", "что это делает?"); чипсы рефакторинга возвращаются к compose-sql через явный `kind` | | каждая другая страница | `POST /api/agent/chat` (полный цикл ассистента) | Инструменты чтения + инструменты записи с одобрением | Чипсы на `/queries/` несут явный `kind`, поэтому одна страница может беспрепятственно смешивать оба потока. Набор чипсов по умолчанию включает два чипса **chat** (`объясни запрос на экране`, `что делает этот запрос?`) плюс пять чипсов **compose-sql** (`параметризируй по диапазону дат`, `добавить фильтр status='error'` и т.д.). Вольно введенные сообщения переходят к значению по умолчанию для страницы (chat), поэтому вопрос типа "почему это так медленно?" получает ответ в прозе, тогда как клик на чип `параметризируй по диапазону дат` маршрутизируется через конечную точку compose и редактирует SQL. Когда композитор работает в **режиме редактирования** (он видит непустой `currentSql`, потому что пользователь находится на `/queries/` или `/queries/new` с предложенным SQL уже загруженным), его системный prompt переходит от "составить новый запрос" к "минимально изменить предоставленный SQL: сохранить выбор таблицы, имена столбцов, структуру соединения, псевдонимы, отступ". Модели показан отдельный набор примеров до/после (параметризация, добавление фильтра, преобразование в почасовые сегменты), поэтому рефакторинг по клику на чип создает минимальный diff против SQL редактора, а не переписывание с нуля. Щелкните чип compose (или введите свободно на `/queries/new`) → SQL потоком в сообщение ассистента как экранированный блок ` ```sql `. **В момент завершения потока, если Monaco смонтирован на текущем маршруте, редактор автоматически включает вид diff** (исходный слева, предложенный справа, подсказка `▾ AI предложил правку` вверху и таблетки **Принять / Отклонить** внизу). Пользователю не нужно искать или нажимать кнопку `Вставить в редактор` для просмотра diff. Кнопка Insert по-прежнему отображается под блоком SQL как ручной триггер повтора (полезна после Отклонения или когда пользователь ушел и вернулся), и это остается единственным путем, когда пользователь находится на странице без редактора (например, список сохраненных запросов); там он сохраняет SQL в `sessionStorage` и переходит к `/queries/new`, где свежемонтированный редактор читает запас при монтировании и открывает тот же вид diff. Если предложенный SQL байт-идентичен тому, что уже есть в редакторе (правка no-op), автооткрытие пропускается; мы не открываем пустой diff. Кнопка `Вставить в редактор` в этом случае также является no-op. Когда пользователь принимает предложение на `/queries/new`, основное действие панели инструментов читает **`save`** вместо `create`; SQL был передан им ассистентом; модель мышления — "завершить это", а не "писать с нуля". Метка переключается один раз, когда док вставляет SQL, и остается `save` до навигации по странице. На `/queries/` кнопка всегда читала `save`; там ничего не меняется. Вне `/queries` док работает как прежде: полный чат с карточками одобрения инструментов, осведомленность о контексте страницы, ссылки. **Разрешения / управление.** Конечная точка compose управляется разрешением `queries:run` для каждого пользователя (читайте-эквивалент; пользователь все еще должен нажать Принять и Запустить, и Запустить проходит через существующую маршрутизацию `sql_guard` + `references_ch_tables` на сервере Rust). Конечная точка chat управляется `agent:use`. Обе по-прежнему требуют конфигурации LLM-соединения на контейнере `agent`; если оно не сконфигурировано, док отображает баннер "ассистент не сконфигурирован на этом развертывании" на любом пути. **Отказы.** Композитор отказывается от любого запроса, который он не может удовлетворить с помощью запроса только для чтения аналитики, и выдает `-- REFUSE: <одноразовая причина>` вместо SQL. Отказывает запросы, которые будут писать данные или достигать таблиц вне представлений аналитики (`api_keys`, `users`, `dashboards`, `saved_queries`, `evaluation_jobs`), и отказывает чистые запросы в прозе ("объясни это", "что это делает?") на пути compose; они принадлежат пути chat и создают там ответ в прозе. Док отображает строку отказа как встроенный красный чип ошибки в сообщение ассистента; ничего не вставляется. **Выбор модели.** Общий с путем chat. Выбор модели в заголовке дока применяется к обоим конечным точкам (вызов compose передает выбранную модель через `resolveModel()` на сервис агента). Когда `AGENTEYE_AGENT_MODELS` указывает несколько моделей, операторы могут смешивать опцию Haiku-класса для композитора с опцией Sonnet-класса для чата; пользователь выбирает на разговор. **Шаблоны для каждой страницы.** Каждая страница имеет свой шаблон (заголовок, основной текст, текст-заполнитель и чипсы предложений), поэтому док адаптируется к странице, на которой вы находитесь. Предложенные чипсы на данном маршруте отображаются на те же намерения, на которые настроен композитор, поэтому клик на предложение создает ожидаемую правку. **Отключение.** Так же, как путь chat: док + композитор оба управляются контейнером `agent` и его LLM-соединением. Если вы хотите поведение только chat для конкретного пользователя, удалите разрешение `queries:run` (которое также отключает кнопку **Run** редактора); если вы хотите поведение только composer, удалите `agent:use` из ролей этого пользователя, затем повторно добавьте `queries:run` отдельно, чтобы они все еще могли выполнять авторский SQL. *** ## Включение Сервис `agent` поставляется в файле Docker Compose и манифестах Kubernetes. Чтобы включить ассистента, предоставьте **(1)** LLM endpoint и **(2)** выделенный ключ данных ассистента. ### 1. Выберите LLM-соединение Выберите одно из этих и установите соответствующие переменные на сервис `agent`: **a) Anthropic напрямую** ``` ANTHROPIC_API_KEY=sk-ant-... ``` **b) Через Portkey (рекомендуется; слаг каталога моделей, только ключ)** ``` PORTKEY_API_KEY= AGENTEYE_AGENT_MODEL=@/claude-sonnet-4-6 ``` Это самый простой путь: в Portkey установите **Anthropic integration** (Model Catalog); она получит **слаг**. Назовите модель как `@/`, и слаг содержит маршрутизацию провайдера + учетные данные, поэтому **виртуальный ключ не требуется**, только ваш API ключ Portkey. Агент отправляет только `x-portkey-api-key` и указывает на шлюз Portkey; Portkey разрешает остальное. (Простое имя модели не работает с "x-portkey-config или x-portkey-provider header is required"; префикс `@slug/` — это то, что делает работу с ключом только). Для самостоятельного хостинга шлюза установите `PORTKEY_BASE_URL`. Предпочитаете маршрутизацию для каждого запроса вместо слага? Установите `PORTKEY_VIRTUAL_KEY=` (или `PORTKEY_CONFIG=`) с простым `AGENTEYE_AGENT_MODEL`. **c) Любой другой Anthropic-совместимый шлюз (LiteLLM, самостоятельно размещённый, …)** ``` ANTHROPIC_BASE_URL=https://your-gateway # Разделённые новой строкой "Name: Value" строки заголовков (НЕ JSON): ANTHROPIC_CUSTOM_HEADERS=x-my-header: value ``` **d) Amazon Bedrock / Google Vertex** ``` CLAUDE_CODE_USE_BEDROCK=1 # + стандартные учетные данные AWS в окружении # или CLAUDE_CODE_USE_VERTEX=1 # + стандартные учетные данные GCP в окружении ``` Опционально привязывайте модель по умолчанию с помощью `AGENTEYE_AGENT_MODEL` (по умолчанию `claude-sonnet-4-6`). Чтобы позволить пользователям **выбирать** среди нескольких моделей, установите `AGENTEYE_AGENT_MODELS` на список разрешенных через запятую (например, `@anthropic-prod/claude-opus-4-7,@anthropic-prod/claude-sonnet-4-6`); тогда в заголовке чата появляется выбор модели, и выбор каждого пользователя запоминается. Агент только когда-либо вызывает модель из этого списка разрешенных. ### 2. Предоставьте ключ ассистента Выберите любой случайный секрет и дайте его **agent** как `AGENTEYE_API_KEY` и **server** как `AGENT_API_KEY` (то же значение). При запуске сервер заполняет его как выделенный ключ с именем `dashboard-assistant` с этим фиксированным набором разрешений: `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`. Разрешения на запись выполняются только через инструменты с управлением одобрением (см. "Что он может и не может делать" выше). **Нет ручного шага создания ключа и нет затронутого административного ключа**. Набор разрешений фиксирован в сервере, и заполненный ключ **защищен**: он не может быть отключен или переоформлен через API ключей; ротируйте его, изменив значение и перезапустив сервер. **Не** переиспользуйте административный/ключ панели управления. ```bash theme={null} SECRET="$(openssl rand -base64 32)" # на сервисе agent: AGENTEYE_API_KEY="$SECRET" # на сервисе server: AGENT_API_KEY="$SECRET" ``` На Kubernetes это подготовлено для вас: поместите `AGENTEYE_API_KEY` в секрет `agenteye-agent`, и Deployment сервера уже читает то же значение как `AGENT_API_KEY`. ### 3. Установите общий токен панель↔agent Установите одинаковый `AGENTEYE_AGENT_TOKEN` на **обоих** сервисах `dashboard` и `agent`. Панель представляет его при вызове внутреннего сервиса агента; агент отклоняет вызовы без него. ### 4. Предоставьте пользователям доступ Дайте соответствующим операторам панели управления разрешение `agent:use` (см. [enterprise-docs/api-keys.md](/ru/agenteye/api-keys)). Пользователи без него никогда не видят ассистента. После установки LLM endpoint и ключа только для чтения перезапустите **server** (для заполнения ключа только для чтения) и сервис **agent**. Док ассистента появляется с правой стороны для любого пользователя `agent:use`, свернутый по умолчанию; щелкните полосу или нажмите `⌘J` / `Ctrl+J` для развертывания. *** ## Справочник переменных окружения Установить на сервис **`agent`**: | Переменная | Цель | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PORTKEY_API_KEY` | Маршрут через Portkey (агент строит соединение шлюза из этого) | | `PORTKEY_VIRTUAL_KEY` | Виртуальный ключ Portkey для ваших учетных данных Anthropic (опционально, если ключ имеет конфигурацию по умолчанию) | | `PORTKEY_CONFIG` / `PORTKEY_BASE_URL` | Именованная конфигурация Portkey / URL самостоятельного хостинга шлюза Portkey (опционально) | | `PORTKEY_PROVIDER` | Слаг провайдера Portkey — третий вариант маршрутизации наряду с `PORTKEY_VIRTUAL_KEY` / `PORTKEY_CONFIG` (используется только когда ни один из них не установлен) | | `ANTHROPIC_API_KEY` | Прямой доступ Anthropic (альтернатива шлюзу / Bedrock / Vertex) | | `ANTHROPIC_AUTH_TOKEN` | Токен Bearer для шлюза, который аутентифицируется через `Authorization: Bearer` вместо `x-api-key` (опционально) | | `ANTHROPIC_BASE_URL` | Endpoint для шлюза без Portkey | | `ANTHROPIC_CUSTOM_HEADERS` | Дополнительные заголовки для шлюза без Portkey: разделённые новой строкой линии `Name: Value` (не JSON) | | `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` | Маршрут через Bedrock / Vertex | | `AGENTEYE_AGENT_MODEL` | Id модели по умолчанию (по умолчанию `claude-sonnet-4-6`) | | `AGENTEYE_AGENT_MODELS` | Список разрешенных через запятую моделей, которые пользователь может выбрать в заголовке чата. Оставьте неустановленным для одной фиксированной модели. Значение по умолчанию выше должно быть одним из этих (иначе оно добавляется). | | `AGENTEYE_AGENT_MAX_CONCURRENCY` | Максимум одновременных чатов на pod (по умолчанию 4); избыточные запросы получают 429 | | `AGENTEYE_API_KEY` | Ключ данных ассистента. Установите **то же самое** значение, что и `AGENT_API_KEY` сервера, который заполняет его фиксированным набором разрешений области при запуске (см. шаг 2). | | `AGENTEYE_AGENT_TOKEN` | Общий секрет с панелью управления | | `AGENTEYE_SERVER_URL` | URL сервера AgentEye (по умолчанию `http://server:8080`) | | `AGENTEYE_AGENT_ALLOW_NO_ORG` | **Мультитенантность.** По умолчанию отключена (fail-closed): ассистент отклоняет запрос `/chat`, который не содержит контекста организации, с `400`, потому что каждый инструмент, который он запускает, ограничивается одной организацией. Панель управления всегда отправляет этот контекст один раз, когда она осведомлена об организации, поэтому вы обычно оставляете это неустановленным. Установите на `1` **только** во время переходного развертывания, когда еще не осведомленная об организации панель управления разговаривает с осведомленным об организации агентом, поэтому ассистент переходит на организацию `default` вместо отказа. Очистите это после приземления обновления панели управления. | | `AGENTEYE_AGENT_MAX_STEPS` | Максимум шагов инструмента на ответ (по умолчанию 8) | | `AGENTEYE_AGENT_TIMEOUT_MS` | Общее время ожидания запроса `/chat` (все обороты модели + шаги инструмента), в миллисекундах (по умолчанию 90000); инструмент SQL имеет собственную крышку 10s | | `AGENTEYE_AGENT_SELF_TELEMETRY` | `1` для записи собственных прогонов ассистента в AgentEye | | `AGENTEYE_TELEMETRY_API_KEY` | Отдельный ключ `events:add`-only для самоинструментации | | `AGENTEYE_AGENT_ENV` | Тег окружения, применяемый к собственной телеметрии ассистента (по умолчанию `prod`) | Установить на сервис **`dashboard`**: | Переменная | Цель | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AGENTEYE_AGENT_URL` | Где панель управления достигает сервис агента. Поставляемые манифесты Kubernetes и файл Compose установили это на `http://agent:9100`. Оставьте неустановленным, чтобы полностью скрыть ассистента. | | `AGENTEYE_AGENT_TOKEN` | Должен соответствовать токену агента | *** ## Телеметрия и просмотр того, о чем спрашивают пользователи Содержимое prompt **остается в ваших собственных системах** по умолчанию. Три слоя: 1. **Хранилище разговоров**: каждый prompt и ответ сохраняются в вашей базе данных AgentEye (для каждого пользователя, приватно) и перезагружаются из переключателя истории ассистента. Это долговечный записи того, о чем спрашивают пользователи. 2. **Аналитика продукта**: панель управления записывает **только метаданные** (как часто используется ассистент, количество инструментов, задержка) в вашу аналитику. Текст **prompt** никогда не включается на этот путь. 3. **Самоинструментация (опционально)**: установите `AGENTEYE_AGENT_SELF_TELEMETRY=1` (плюс `events:add`-only `AGENTEYE_TELEMETRY_API_KEY`) и ассистент записывает свои прогоны в AgentEye как агент `dashboard-assistant`. Затем вы можете просмотреть prompts пользователя и рассуждения ассистента в этих же представлениях сессий/событий, которые вы используете для всего остального. Примечание: эти события видны всем с `events:read`; если это слишком широко, оставьте это отключенным. *** ## Отключение Любое из этих отключит ассистента (полоса дока исчезает): * Отмените установку `AGENTEYE_AGENT_URL` на панели управления, **или** * Оставьте LLM endpoint несконфигурированным на агенте (без `ANTHROPIC_API_KEY` / шлюза / Bedrock / Vertex), **или** * Не развертывайте сервис `agent` вообще. *** ## Резюме безопасности * **Нет молчаливых записей**: инструменты записи ассистента (`create_saved_query`, `update_saved_query`, `create_dashboard`, `update_dashboard`, `add_query_to_dashboard`) не могут выполняться без явного нажатия оператором кнопки Одобрить в чате; шлюз предварительного вызова SDK блокирует инструмент до получения одобрения агентом через обратный канал. Нет настройки, которая отключит этот шлюз. * **Фиксированная, узкая область данных**: ассистент аутентифицируется на сервере с выделенным ключом, набор разрешений которого фиксирован в сервере (`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`). Единственные записи, которые он может создавать, — это сохраненные запросы и панели; сервер отклоняет что угодно за пределами этой области независимо от того, что пытается сделать модель. * **Нет поверхности удаления**: ключ не содержит разрешение на удаление и нет инструмента удаления. Операторы удаляют через пользовательский интерфейс панели управления, никогда через ассистента. * **Только внутренний**: агент не имеет публичного маршрута; только панель управления может вызвать его, и только с общим токеном. (На Kubernetes NetworkPolicy ограничивает агента только достижением сервера AgentEye и endpoint LLM.) * **Каждого пользователя область**: только пользователи `agent:use` получают ассистента, и ему даны только инструменты, соответствующие разрешениям чтения каждого пользователя. * **Нет сырого HTML / нет утечки ссылок**: ответы отображаются как санитизированный markdown; внешние ссылки обезопасены. См. [enterprise-docs/troubleshooting.md](/ru/agenteye/troubleshooting) для общих проблем.