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

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"
        appearance={{
          variant: 'refined',
          theme: 'system',
          welcomeMessage: 'How can I help with this product?',
          starterPrompts: ['Is it in stock?', 'Compare the available options'],
          privacyUrl: '/privacy/',
        }}
      />
    </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',
  appearance: {
    variant: 'refined',
    theme: 'system',
    welcomeMessage: 'How can I help with this product?',
    starterPrompts: ['Is it in stock?', 'Compare the available options'],
    privacyUrl: '/privacy/',
  },
});

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 /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" } }

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

Self-hosting

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

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

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