Skip to main content

Quickstart (JavaScript / TypeScript)

This guide gets you from zero to a working agent chat using only @kapaai/agent-core and plain JavaScript. No framework required.

Prerequisites​

  • An Agent integration set up in your Kapa dashboard (Integrations → Agent)
  • A customer API key (from your Kapa dashboard → API Keys)

1. Install the package​

npm install @kapaai/agent-core

2. Create a session endpoint​

Same as the React quickstart — create a server-side endpoint that proxies session creation. See Authentication for full details.

3. Build the chat​

index.html
<div id="messages"></div>
<div id="streaming-indicator" style="display: none">Agent is thinking...</div>
<input id="input" type="text" placeholder="Ask a question..." />
<button id="send-btn">Send</button>
<button id="stop-btn" style="display: none">Stop</button>
<button id="new-chat-btn">New Chat</button>
main.js
import { Agent } from '@kapaai/agent-core';

const agent = new Agent({
  projectId: 'your-project-id',
  integrationId: 'your-integration-id',
  tools: [],
  context: {},
  getSessionToken: async () => {
    const res = await fetch('/api/session', { method: 'POST' });
    if (!res.ok) throw new Error('Session failed');
    return res.json();
  },
  onMessagesChange: (messages) => {
    const container = document.getElementById('messages');
    container.innerHTML = '';

    for (const msg of messages) {
      const el = document.createElement('div');

      if (msg.role === 'user') {
        el.textContent = msg.content;
        el.className = 'user-message';
      } else {
        // Render each block (text or tool calls)
        for (const block of msg.blocks) {
          if (block.type === 'text' && block.content) {
            const textEl = document.createElement('div');
            textEl.textContent = block.content;
            el.appendChild(textEl);
          }
          if (block.type === 'tool_calls') {
            for (const tc of block.toolCalls) {
              const toolEl = document.createElement('div');
              toolEl.className = 'tool-card';
              toolEl.textContent = `${tc.displayName || tc.name}: ${tc.status}`;
              if (tc.result) {
                toolEl.textContent += ` — ${JSON.stringify(tc.result)}`;
              }
              el.appendChild(toolEl);
            }
          }
        }
      }

      container.appendChild(el);
    }

    container.scrollTop = container.scrollHeight;
  },
  onStreamingChange: (streaming) => {
    document.getElementById('streaming-indicator').style.display =
      streaming ? 'block' : 'none';
    document.getElementById('send-btn').style.display =
      streaming ? 'none' : 'block';
    document.getElementById('stop-btn').style.display =
      streaming ? 'block' : 'none';
  },
});

// Wire up buttons
document.getElementById('send-btn').onclick = () => {
  const input = document.getElementById('input');
  const text = input.value.trim();
  if (text) {
    input.value = '';
    agent.sendMessage(text);
  }
};

document.getElementById('stop-btn').onclick = () => agent.stopGeneration();
document.getElementById('new-chat-btn').onclick = () => agent.resetConversation();

document.getElementById('input').onkeydown = (e) => {
  if (e.key === 'Enter') document.getElementById('send-btn').click();
};

That's it — a working agent chat with plain JavaScript and DOM manipulation.

Next steps​

For a complete runnable example with tools, markdown rendering, and approval flow, see the vanilla JS example in the examples repo.