`@teaflask/assistant` is the Teaflask Assistant: the part of Teaflask that runs in your product. It's the interface your users work with, and the code that carries out anything the agent needs done in the page. This page explains how it behaves inside your page, and every other page in this section builds on it. For how it fits into the rest of Teaflask, including what runs where and the trust model, see [Architecture](/architecture). ## What your page has to allow The assistant talks to Teaflask directly from the visitor's browser, so two things have to be true of every page that carries it: - The page's origin must be on the publishable key's list of allowed origins. Requests from any other origin are refused. - If your site sends a Content Security Policy, the policy has to let the browser load the assistant and reach Teaflask. [Install](/install) lists the entries. ## A conversation is live while the assistant is mounted When the first assistant component on a page mounts, it does two things: 1. It exchanges the publishable key for a short-lived visitor token. 2. It opens a live connection to the conversation. Every assistant component on the page shares that connection, provided it uses the same key, API address and signed-in user. A reply streaming into the corner widget also streams into a full-page view. The connection is a view, not the work itself. The agent harness runs on the Teaflask runtime, and the assistant reads the conversation's log as the harness writes it ([Architecture](/architecture) explains this). So when the last assistant component unmounts and the connection closes, the work carries on. The browser remembers which conversation was open, and the next mount gets a fresh token, reconnects and replays it. Users notice the reconnect, though: the transcript reloads and an open command palette closes. There's one kind of work only a mounted assistant can do: anything the agent needs done in the page or as the user, such as running an action or navigating. While no page has the assistant mounted, that work waits, and it runs when the user next opens the conversation. That's why where you mount the assistant matters more than anything else in the install. Mount it in the part of your app that stays on screen while users move between pages, and it connects once. Mount it inside a page, and it reconnects every time the page changes. [Install](/install) shows how to find the right place. ## What only your page can do Most of an agent's work happens on the Teaflask runtime, and that needs nothing from your page. A few things can only happen inside your page, because only your page can do them. For each of these, the assistant takes a piece of your code: | Only your page can… | So you give the assistant | Until you do | | ------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------- | | move the user to another page | `onNavigate`, a function that navigates your app | the agent is told this page can't navigate, and says so | | make a request as the signed-in user | `actionsAdapter`, which calls your API with the user's own session | the agent asks the user to do the step themselves | | vouch for who that user is | `userId` and `getEndUserToken` | the visitor is anonymous | | draw a result with your product's own components | `toolViews`, renderers keyed by tool name | results use the built-in or default view | Your code provides the how; the agent's settings decide the whether: [App access](/app-access) for navigation, [Actions](/actions) for API calls. You need both. Wiring `onNavigate` won't let an agent navigate if its navigation tool is off, and turning the tool on does nothing on a page that can't navigate. ## Two ways to load it The npm package and the script tag deliver the same assistant, packaged differently: | | npm package | Script tag | | ------------ | -------------------------------------------------- | --------------------------------------------------------------------------- | | What you add | React components, `` and others | Custom elements, `` and `` | | Loaded from | Your bundle | `app.teaflask.com` | | React | Uses your copy | Carries its own copy, inside a shadow root | | Version | The one you installed | Always the current release | | Styles | A stylesheet you import | Built in | | Settings | Props | Attributes for text values; JavaScript properties for functions and objects | | Use it for | React apps with a bundler | Any other page, whatever it's built with | The capabilities are the same, apart from a few exceptions listed on [Install](/install). Use one or the other on a given page. Each carries its own copy of the assistant, so a React component and a custom element on the same page don't share a conversation. ## Where exact signatures live The package's type declarations describe every component, prop, hook and type, one sentence each. The custom elements have no manifest of their own: their bundle is served from `app.teaflask.com` rather than shipped on npm, and every setting they take resolves to one of those same props — the attributes `publishable-key`, `base-url`, `mode`, `corner`, `hotkey` and `companion-mark-src` on ``, `publishable-key`, `base-url`, `mode`, `heading` (the page's `title`) and `frameless` on ``, and the function-and-object settings as JavaScript properties under the prop's own name: `onNavigate`, `userId`, `getEndUserToken`, `actionsAdapter`, `onError`, `theme`, `suggestions` and `toolViews`. These guides explain how the pieces fit together. The types are the reference. ## The pages in this section | Page | Covers | | ------------------------------------- | ------------------------------------------------------------- | | [Install](/install) | Getting the assistant onto every page, step by step | | [Publishable keys](/publishable-keys) | Creating keys, allowed origins, live and test, rotating | | [Surfaces](/surfaces) | The corner widget, the command palette and the full-page view | | [Identity](/identity) | Telling the assistant who is signed in | | [Actions adapter](/adapters) | Letting the agent call your API as the user | | [Tool views](/tool-views) | Showing tool and action results as your own components | | [Theming](/appearance) | Colors, dark mode, fonts and your own mark | | [Headless](/headless) | Building your own interface on the same conversation | | [Transcript](/transcript) | History, attachments, delegated work and activity indicators | ## More resources - [Architecture](/architecture) – what runs where, the trust model, and what data goes where - [Getting started](/getting-started) – the whole path, from a connected repository to a live assistant - [Agents](/agents) – the prompt, the model, and what the agent may reach - [Actions](/actions) – registering the API operations the agent may call, and their approval policies - [App access](/app-access) – letting the agent read the page, fill in forms and navigate - [Production checklist](/production-checklist) – what to confirm before real users arrive