Вбудовування: агент на вашому сайті

Чат з агентом 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 — у ваш сайт.

Чого він не робитиме і чому

Зовнішня розмова навмисно вужча за розмову власника. За замовчуванням агент, що відповідає вашим відвідувачам, не має рук, нічого не пише у свою довгу пам'ять і не може перепланувати власну роботу. Будь-яку з цих заборон власник може зняти поштучно — і кожна варта того, щоб розуміти, чим це загрожує.

Це Межі та права, і її варто прочитати раніше, ніж щось відкривати.