Документация

Документация

Каждый пример ниже — реальный файл, типизируемый в CI против настоящих SDK-пакетов, а не переписанный вручную текст. Если типы не сойдутся, сборка упадёт раньше, чем вы это увидите.

Быстрый старт

Три способа подключить Context Assistant — в зависимости от вашего стека:

• React SDK — React-приложение, готовый виджет.
• Встраивание через скрипт — любой сайт, чистый JS.
• JavaScript SDK — без интерфейса, соберите свой UI.

Всем трём нужна одна вещь от вашего бэкенда: эндпоинт токена, который обменивает секретный ключ ca_sk_… на короткоживущий embed token. Сам секретный ключ никогда не попадает в браузер (см. Модель безопасности).

React SDK

Установка:

Copynpm install @context-assistant/react

Оберните приложение (или его часть) в provider, затем добавьте виджет:

Copyimport { ContextAssistantProvider, Assistant } from '@context-assistant/react';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

export function App() {
  return (
    <ContextAssistantProvider apiUrl="https://api.your-domain.example" getToken={getToken}>
      <Assistant agent="store-consultant" title="Store Consultant" greeting="How can I help?" />
    </ContextAssistantProvider>
  );
}

Нужен свой интерфейс вместо встроенного виджета? Используйте useAssistant() напрямую — он даёт messages, status, busy, pendingAction, send() и пару confirm/cancel для схемы preview → Apply.

Встраивание через скрипт

Для любого сайта — без фреймворка. Установите бандл или раздавайте его сами, затем:

Copyimport { mount } from '@context-assistant/embed-sdk';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

const widget = mount({
  apiUrl: 'https://api.your-domain.example',
  getToken,
  agent: 'store-consultant',
  title: 'Store Consultant',
});

widget.setContext({
  page: { type: 'product', id: 184 },
});

Возвращённый виджет даёт open(), close(), send(), setContext(), updateContext(), clearContext() и destroy().

JavaScript SDK

Клиент без интерфейса, на котором построены оба SDK выше, — для полностью своего UI:

Copyimport { ConversationSession } from '@context-assistant/js-sdk';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

const session = new ConversationSession({
  apiUrl: 'https://api.your-domain.example',
  getToken,
  agent: 'store-consultant',
});

await session.send('What pairs well with this processor?', {
  onToken: (delta) => process.stdout.write(delta),
  onDone: (event) => console.log('\n[done]', event.message),
});

Контракт Remote Tools

Любой бэкенд может дать ассистенту типизированные действия и обоснование ответов, реализовав четыре HTTP-эндпоинта. Скоуп передаётся как execution (workspaceId, externalUserId, permissions, requestId); callId сквозно идентифицирует один конкретный вызов инструмента.

Метод и путь	Назначение
GET {baseURL}/tools	Список доступных инструментов для этого execution scope
GET {baseURL}/context	Контекст для обоснования ответов текущего пользователя/сессии
POST {baseURL}/tools/preview	Предпросмотр для человека — без побочных эффектов
POST {baseURL}/tools/execute	Выполнить действие после подтверждения

Ответ GET /tools:

Copy{
  "tools": [
    {
      "name": "create_task",
      "description": "Create a task in the current project",
      "verb": "create",
      "inputSchema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
    }
  ]
}

Запрос POST /tools/preview:

Copy{
  "tool": "create_task",
  "callId": "call_abc123",
  "arguments": { "title": "Ship the release" },
  "execution": {
    "workspaceId": "ws_123",
    "externalUserId": "user_42",
    "permissions": ["tasks:write"],
    "requestId": "req_xyz"
  }
}

Ответ POST /tools/preview:

Copy{ "preview": "Create a task “Ship the release” in Project Apollo" }

Ответ POST /tools/execute (запрос той же формы, что и у preview):

Copy{ "output": { "id": "task_789", "title": "Ship the release", "status": "open" } }

Verb	Подтверждение
get	Нет — выполняется автоматически в рамках хода
create, update	Preview, затем явный Apply
delete	Preview, затем второе явное подтверждение

Живой пример: плагин для WordPress реализует именно этот контракт — 10 инструментов (6 WordPress + 4 WooCommerce), проверяется conformance-тестами против реального хоста при каждом изменении.

Self-hosting

Ядро — open-core: те же Docker-образы, что используем мы сами, разворачиваются одной командой docker compose up, а все данные — диалоги, база знаний, ключи — остаются в вашей инфраструктуре. Полный гайд оператора для этой страницы ещё в планах; до тех пор — напишите нам, если хотите развернуть self-hosting уже сегодня.

Модель безопасности

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