›_ плюс цветная точка статуса. Нажмите на полосу (или нажмите ⌘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/<id> (существующий) | POST /api/agent/chat (полный цикл ассистента), по умолчанию для страницы | Вольные сообщения должны позволить пользователю спросить что угодно (“объясни это”, “что это делает?”); чипсы рефакторинга возвращаются к compose-sql через явный kind |
| каждая другая страница | POST /api/agent/chat (полный цикл ассистента) | Инструменты чтения + инструменты записи с одобрением |
/queries/<id> несут явный kind, поэтому одна страница может беспрепятственно смешивать оба потока. Набор чипсов по умолчанию включает два чипса chat (объясни запрос на экране, что делает этот запрос?) плюс пять чипсов compose-sql (параметризируй по диапазону дат, добавить фильтр status='error' и т.д.). Вольно введенные сообщения переходят к значению по умолчанию для страницы (chat), поэтому вопрос типа “почему это так медленно?” получает ответ в прозе, тогда как клик на чип параметризируй по диапазону дат маршрутизируется через конечную точку compose и редактирует SQL.
Когда композитор работает в режиме редактирования (он видит непустой currentSql, потому что пользователь находится на /queries/<id> или /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/<id> кнопка всегда читала 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 напрямую
@<slug>/<model>, и слаг содержит маршрутизацию провайдера + учетные данные, поэтому виртуальный ключ не требуется, только ваш API ключ Portkey. Агент отправляет только x-portkey-api-key и указывает на шлюз Portkey; Portkey разрешает остальное. (Простое имя модели не работает с “x-portkey-config или x-portkey-provider header is required”; префикс @slug/ — это то, что делает работу с ключом только). Для самостоятельного хостинга шлюза установите PORTKEY_BASE_URL.
Предпочитаете маршрутизацию для каждого запроса вместо слага? Установите PORTKEY_VIRTUAL_KEY=<vk> (или PORTKEY_CONFIG=<id>) с простым AGENTEYE_AGENT_MODEL.
c) Любой другой Anthropic-совместимый шлюз (LiteLLM, самостоятельно размещённый, …)
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 ключей; ротируйте его, изменив значение и перезапустив сервер. Не переиспользуйте административный/ключ панели управления.
AGENTEYE_API_KEY в секрет agenteye-agent, и Deployment сервера уже читает то же значение как AGENT_API_KEY.
3. Установите общий токен панель↔agent
Установите одинаковыйAGENTEYE_AGENT_TOKEN на обоих сервисах dashboard и agent. Панель представляет его при вызове внутреннего сервиса агента; агент отклоняет вызовы без него.
4. Предоставьте пользователям доступ
Дайте соответствующим операторам панели управления разрешениеagent:use (см. enterprise-docs/api-keys.md). Пользователи без него никогда не видят ассистента.
После установки 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 остается в ваших собственных системах по умолчанию. Три слоя:- Хранилище разговоров: каждый prompt и ответ сохраняются в вашей базе данных AgentEye (для каждого пользователя, приватно) и перезагружаются из переключателя истории ассистента. Это долговечный записи того, о чем спрашивают пользователи.
- Аналитика продукта: панель управления записывает только метаданные (как часто используется ассистент, количество инструментов, задержка) в вашу аналитику. Текст prompt никогда не включается на этот путь.
- Самоинструментация (опционально): установите
AGENTEYE_AGENT_SELF_TELEMETRY=1(плюсevents:add-onlyAGENTEYE_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; внешние ссылки обезопасены.