# AssistedProvider

> Wraps the app in the runtime and lends what every page shares, with the cards that show its tools. With useAssisted.

`AssistedProvider` lends what every page shares: the universal instructions, `offer_choices`, the show tools `show_table`, `show_spec` and `show_comparison`, and `go_to_page` and `show_links` when it has destinations. It holds the cards those tools render. `useAssisted` reads and drives the panel's open state.

![The floating panel, headed On Orders. The user asked to go to the orders, and the expanded go_to_page call answers with Opened /orders and the Orders page's note.](https://superassist.app/_astro/provider-light.87KslKZ5.webp)

## Usage

Give it the runtime from `useAssistedRuntime` and wrap the app. From `examples/app/app/assistant.tsx`:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  host: process.env.NEXT_PUBLIC_SUPER_ASSIST_HOST,
});

<AssistedProvider
  runtime={runtime}
  destinations={destinations}
  starters={["What can you do on this page?"]}
  navigate={(path) => router.push(withMode(path))}
>
  <Layout>{children}</Layout>
</AssistedProvider>;
```

`destinations` names the pages `go_to_page` opens. From the same file:

```ts
const destinations = {
  home: "/",
  orders: "/orders",
  order: "/orders/:id",
  customers: "/customers",
  settings: "/settings",
};
```

## What the model sees

Every request's system text holds the universal instructions, quoted in [Model context](https://superassist.app/reference/model-context.md#universal-instructions). With the example's destinations, `go_to_page` is described as:

```txt wrap
Open a page of the app for the user and answer, once it has loaded, with the page section of the page it opened. The pages and their paths: home /, orders /orders, order /orders/:id, customers /customers, settings /settings.
```

The call in the screenshot answered with the path it opened and the note of the page there:

```md wrap
Opened /orders.

## The page the user has open: Orders

Every order of the shop, as filtered by status with filter_orders, and charted by status with chart_orders. Ship or cancel an order that is waiting to ship by its id. New order opens a dialog that introduces itself. Each order has a page of its own with its note and refund.

Its tools: filter_orders, chart_orders, get_page_content.

Its actions: cancel_order, new_order, ship_order.
```

`show_links`, `offer_choices` and the show tools render cards, each on its own page under [Cards](https://superassist.app/components.md#cards).

## Props

| Prop                      | Type                        | Required | Description                                                         |
| ------------------------- | --------------------------- | -------- | ------------------------------------------------------------------- |
| `runtime`                 | `AssistantRuntime`          | Yes      | The runtime from `useAssistedRuntime`.                              |
| `destinations`            | `Record<string, string>`    | No       | Page names to paths. `:id` in a path takes an id.                   |
| `destinationsDescription` | `string`                    | No       | Replaces the pages and their paths in `go_to_page`'s description.   |
| `navigate`                | `(path: string) => unknown` | No       | Opens a path. `go_to_page` awaits it.                               |
| `starters`                | `string[]`                  | No       | First messages the empty state suggests on a page without its own.  |
| `cards`                   | `AssistedCards`             | No       | Cards that replace the package's, by tool. See below.               |
| `trace`                   | `boolean`                   | No       | Shows every press and fill on the page with a ring. Off by default. |
| `children`                | `ReactNode`                 | Yes      | The app.                                                            |

- Renders `AssistantRuntimeProvider` with `runtime`.
- Lends the universal instructions, `offer_choices`, `show_table`, `show_spec` and `show_comparison`.
- Lends `go_to_page` and `show_links` only when both `destinations` and `navigate` are given.
- Renders the agent's `search_knowledge` calls as the sources card under the answer, without lending a tool.
- Answers calls to tools and actions that have left with `{ error }` and the open page's note.
- Stamps each user message with the id of the tab that sent it, in `metadata.custom.tab`, and runs a call only in that tab. Other tabs wait for its result.
- Holds the panel's open state, closed at first.
- With `trace`, a press or fill flashes a ring on its element for a second, and a `"confirm"` action keeps the ring on its element while the panel asks. An action or field sets its own `trace` to differ.
- `AssistedPage`, `AssistedAction`, `AssistedInput`, `AssistedField`, `useAssistedTool`, `useAssisted`, the panel and the devtools render inside it.

## AssistedCards

`cards` maps a card to the component that replaces it. Each is optional, and each takes the default card's props: the tool call's `args`, `result`, `isError`, and while it waits, `interrupt` and `resume`.

| Key          | Replaces                                                                                   | `args`                                              |
| ------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `confirm`    | The [confirm card](https://superassist.app/components/cards/confirm-card.md) of every consequential action and tool | Any. `interrupt.payload` is `{ name, label, id? }`. |
| `choices`    | The [choices card](https://superassist.app/components/cards/choices-card.md)                                        | `{ question, options }`                             |
| `links`      | The [links card](https://superassist.app/components/cards/links-card.md)                                            | `{ items }`                                         |
| `table`      | The [table card](https://superassist.app/components/cards/table-card.md)                                            | `{ title?, columns, rows }`                         |
| `spec`       | The [spec card](https://superassist.app/components/cards/spec-card.md)                                              | `{ title, rows }`                                   |
| `comparison` | The [comparison card](https://superassist.app/components/cards/comparison-card.md)                                  | `{ traits, options, recommended, reason }`          |
| `sources`    | The [sources card](https://superassist.app/components/cards/sources-card.md) under an answer                        | `{ query, knowledgeBase? }`                         |

A `confirm` card answers with `resume({ approved: boolean })`, and a `choices` card with `resume(option)`.

## useAssisted

```ts
useAssisted(): {
  isOpen: boolean;
  open: (message?: string) => void;
  close: () => void;
  page: string | undefined;
}
```

| Field            | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `isOpen`         | Whether the floating or sheet panel is open.                             |
| `open(message?)` | Opens the panel. With a message, appends it to the thread as the user's. |
| `close()`        | Closes the panel.                                                        |
| `page`           | The open assisted page's name, or `undefined`.                           |

Throws `Render this inside an AssistedProvider` outside the provider. The panel's header reads `page`, and [`AssistedPanel.Trigger`](https://superassist.app/components/panel/roots-and-window.md#leaf-props) toggles `isOpen`.

## See also

- [Use the hosted runtime](https://superassist.app/how-to/use-the-hosted-runtime.md) for the options of the runtime it takes.
- [Swap a card](https://superassist.app/how-to/swap-a-card.md) sets `cards`.
- [Add `go_to_page`](https://superassist.app/how-to/add-go-to-page.md) sets `destinations` and `navigate`.
- [How model context composes](https://superassist.app/explanation/model-context.md) explains what it lends and when.