Context Assistant documentation

React SDK

Install:

Copynpm install @context-assistant/react

Wrap your app (or a subtree) in the provider, then drop in the widget:

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>
  );
}

Need custom UI instead of the built-in widget? Use useAssistant() directly — it exposes messages, status, busy, pendingAction, send(), and the confirm/cancel pair for the preview → Apply flow.

Script embed

For any site — no framework required. Install the bundle or serve it yourself, then:

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 },
});

The returned widget exposes open(), close(), send(), setContext(), updateContext(), clearContext(), and destroy().

JavaScript SDK

The headless client underneath both SDKs above — for building your own UI from scratch:

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 contract

Any backend can give the assistant typed actions and grounding by implementing four HTTP endpoints. Scope is passed as execution (workspaceId, externalUserId, permissions, requestId); callId identifies one specific tool call end-to-end.

GET /tools response:

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 request:

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 response:

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

POST /tools/execute response (request is the same shape as preview):

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

Live reference: the WordPress plugin implements this exact contract with 10 tools (6 WordPress + 4 WooCommerce), conformance-tested against a real host on every change.

Self-hosting

The core is open-core: the same Docker images we run ourselves deploy with one docker compose up, and all data — conversations, knowledge base, keys — stays in your own infrastructure. A full operator runbook is on the roadmap for this page; until then, get in touch if you want to self-host today.

Security model

The full model is on the homepage. In short: the browser only ever holds a short-lived token, every request is scoped to one tenant and workspace, the host re-checks real permissions before any action, and deletes require double confirmation with a recovery path.