Встраивание: агент на вашем сайте

Чат с агентом Agentfy на вашей собственной странице. Посетителю не нужна у нас учётная запись, он ничего не устанавливает и никуда не уходит с вашего сайта.

Этот раздел написан для того, кто ставит агента себе, а не для того, у кого открыт этот репозиторий.

Что такое встраивание

Трое участников, и новый из них только средний:

браузер посетителя  ──►   хаб    ──►   агент
   ваша страница        один порт      делает ход
   один <script>        WebSocket      и отвечает

• Браузер посетителя подгружает небольшой виджет по тегу <script> с вашей страницы.
• Хаб — единственный адрес, с которым этот браузер разговаривает. По умолчанию хабом работает сам api Agentfy, на отдельном порту, — то есть обычной установке второй сервис не нужен. См. Что нужно на сервере.
• Агент — ваш: тот же самый, с которым вы говорите в кабинете, с теми же инструкциями и теми же знаниями.

Соединение — WebSocket, и ответ приходит по кусочкам: посетитель смотрит, как ответ появляется, а не ждёт его целиком.

Три способа

Все три обращаются к одному хабу и одному агенту. Отличаются они только тем, какая часть интерфейса ваша.

1. Тег <script> и плавающий пузырь

Одна вставка в шаблон сайта. В правом нижнем углу появляется кнопка, по нажатию открывается чат. Ничего собирать и устанавливать не нужно — подойдёт и теме WordPress, и странице, написанной руками.

<script>
  (function () {
    var sdk = document.createElement('script')
    sdk.src = 'https://bridle.cleanslice.org/sdk/latest.js'
    sdk.onload = function () {
      window.Bridle.init({
        apiUrl: 'https://хаб.вашей.установки',
        agentId: 'agent-…',
        token: '<билет из кабинета>',
        mode: 'floating',
        title: 'Поддержка',
      })
    }
    document.head.appendChild(sdk)
  })()
</script>

Копируйте из кабинета, а не отсюда

Кабинет собирает эту вставку сам — экран агента «Сайт», кнопка «Скопировать». То, что он выдаёт, чуть длиннее: туда добавлена функция, которая меняет общий билет страницы на билет конкретного посетителя, чтобы двое открывших ваш сайт не оказались в одном разговоре. Это важное отличие, и оно разобрано в Два вида билета.

2. Пакет в вашей сборке

Если у сайта есть сборка — Vite, Next, Nuxt, Webpack — виджет ставится пакетом и вызывается из кода. Это даёт две вещи, которых тег дать не может: чат можно вмонтировать в конкретное место страницы, а не только повесить в угол, и токен можно передать функцией, которую спросят заново при каждом переподключении.

npm i @cleanslice/bridle

import { init } from '@cleanslice/bridle'

init({
  apiUrl: import.meta.env.VITE_HUB_URL,
  agentId: 'agent-…',
  token: () => fetch('/api/agent-token').then((r) => r.json()).then((t) => t.token),
  mount: '#chat',
  mode: 'inline',
  title: 'Поддержка',
})

3. Свой интерфейс поверх клиента

Готовый виджет можно не брать вовсе. Клиент даёт соединение и события — «печатает», «пришёл кусок ответа», «ответ закончился», — а как всё это выглядит, решает ваша вёрстка. Так чат встраивают в уже нарисованный интерфейс: в панель поддержки, в карточку товара, в мобильное приложение.

import { BridleClient } from '@cleanslice/bridle'

const client = new BridleClient({ apiUrl, agentId, token })

client.on('typing', () => showTypingIndicator())
client.on('stream', (m) => renderPartial(m.text))
client.on('stream_end', (m) => commit(m.text))
client.on('message', (m) => commit(m.text))
client.on('error', (e) => showError(e.code))

await client.connect()
client.send('Здравствуйте')

Все три работают рядом на одной странице в демо.

Что видит посетитель

Окно чата с именем вашего агента. Он пишет, появляется индикатор «печатает», ответ приходит потоком. Ничто не опознаёт его у нас, и ничего о себе он не сообщает.

Чего он не видит — решено так же намеренно, как и то, что видит:

• не рассуждения и не шаги, которые агент предпринял;
• не инструменты, которые тот вызвал, и не то, что они вернули;
• не другие разговоры агента — у посетителя своя отдельная ветка.

Виджет живёт внутри теневого дерева, поэтому CSS вашего сайта не протекает в него, а его CSS — в ваш сайт.

Чего он не будет делать и почему

Внешний разговор намеренно уже, чем разговор владельца. По умолчанию агент, отвечающий вашим посетителям, не имеет рук, ничего не пишет в свою долгую память и не может перепланировать собственную работу. Любой из этих запретов владелец может снять поштучно — и каждый стоит того, чтобы понимать, чем это грозит.

Это Границы и права, и её стоит прочитать раньше, чем что-то открывать.