# Getting started

Agentak is a complete AI chat widget. Its UI and included Pi agent run in the browser. You
can use an on-device model, call a supported provider directly, or connect the UI to your
own backend.

## Install

```sh
npx nypm i agentak
```

Agentak has separate entries for the UI and the included agent. Your application loads Pi
only when it imports `agentak/pi`.

## Add a chat without a framework

```html
<div id="chat" style="height: 600px"></div>

<script type="module">
  import { mountChat } from "https://esm.sh/agentak";
  import { createPiSession } from "https://esm.sh/agentak/pi";

  const session = createPiSession();
  const chat = mountChat("#chat", { session });

  // When the page no longer needs the chat:
  // chat.unmount();
  // session.dispose();
</script>
```

The chat fills its container, so give that container a height. `mountChat()` injects the
Agentak design tokens by default and returns `update()` and `unmount()`. It never disposes
the session because it did not create it.

A fresh Pi session has no selected provider. The first message is held while the settings
page opens. The user can select a free provider, a local model, or a keyed provider, then
the waiting message is sent.

## Add persistence and page tools

```ts
import { browserStorage, createPiSession } from "agentak/pi";

const session = createPiSession({
  history: true,
  page: true,
  storage: browserStorage(),
  systemPrompt: "Answer questions about this page. Keep answers short.",
});
```

- `browserStorage()` keeps provider, model, thinking level, and API keys in
  `localStorage`. API keys are encrypted with a non-extractable WebCrypto key; the other
  choices are stored as they are.
- `history: true` adds the conversation history page and keeps up to 20 conversations in
  the same store. A new session still opens on a new conversation.
- `page: true` offers the model the WebMCP tools published on
  `document.modelContext`. Browsers without WebMCP simply provide no page tools.

Storage and page tools are off by default.

## Choose an integration

| App              | Import           | Component     |
| ---------------- | ---------------- | ------------- |
| React            | `agentak/react`  | `ChatPanel`   |
| Vue              | `agentak/vue`    | `ChatPanel`   |
| Preact           | `agentak/preact` | `ChatPanel`   |
| Plain JavaScript | `agentak`        | `mountChat()` |

Every framework entry also exports `ChatView`, the controlled form of the surface. Read
[Chat widget](/widget) for complete examples and props.

## Browser and key safety

Agentak supplies no server proxy. A keyed Pi provider receives the key directly from the
browser. Do not put a private server key in public client code. Let each user enter their
own key, use an on-device or anonymous provider, or connect a custom `ChatSession` to your
backend.

The default storage is memory shared by sessions on the page. It disappears when the page
closes. `browserStorage()` is explicit because browser storage is readable by scripts on
the same origin. Use it only when that is acceptable.

Provider availability depends on the environment. Regular pages only list network
providers that accept browser CORS requests. The Chrome extension can reach more network
providers through host permissions, and bundles wllama so the local row is listed there
too. Chrome Built-in AI and On Device (wllama) appear only when their runtime requirements are
met.

## Next steps

::card-group
:::card{title="Build the widget" icon="i-lucide-message-square" to="/widget"}
Use React, Vue, Preact, plain JavaScript, or a controlled transcript.
:::
:::card{title="Configure Pi" icon="i-lucide-bot" to="/agents/pi"}
Choose providers, on-device models, tools, approvals, storage, and lower-level APIs.
:::
:::card{title="Save conversations" icon="i-lucide-archive" to="/agents/pi/conversations"}
Use built-in history or store versioned Pi snapshots yourself.
:::
:::card{title="Connect another agent" icon="i-lucide-plug" to="/agents/custom"}
Implement the five required `ChatSession` methods and add only the optional UI you need.
:::
::