# Home (/)



# IntentCtrl [#intentctrl]

Embedded AI runtime for React applications.

<Cards>
  <Card title="Documentation" href="/docs">
    Learn how to install, configure, and use IntentCtrl in your app.
  </Card>

  <Card title="Cloud Platform" href="http://app.intentctrl.com">
    Get started with no backend setup required.
  </Card>

  <Card title="UI Components" href="/ui">
    Reusable components for building chat interfaces.
  </Card>
</Cards>


# Apps (/changelogs/apps-changelogs)



No releases yet.


# Overview (/changelogs)



<Cards>
  <Card title="Packages" href="/changelogs/packages-changelogs">
    Release history for packages.
  </Card>

  <Card title="Apps" href="/changelogs/apps-changelogs">
    Release history for apps.
  </Card>
</Cards>


# Packages (/changelogs/packages-changelogs)



No releases yet.


# Getting Started (/docs/getting-started)



## Quick Start [#quick-start]

<Steps>
  <Step>
    ### Install [#install]

    {/* prettier-ignore */}

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install @intentctrl/react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add @intentctrl/react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add @intentctrl/react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add @intentctrl/react
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Make sure `react`, `react-dom`, and `zod` are already in your project.
  </Step>

  <Step>
    ### Add the provider [#add-the-provider]

    Wrap your application (or the part that needs AI) in `IntentCtrlProvider`. You need the URL of an AI backend and an API key. Use the [cloud platform](http://app.intentctrl.com) directly, or [self-host the backend](https://github.com/intentctrl) for free.

    ```tsx title="app/layout.tsx"
    import { IntentCtrlProvider } from "@intentctrl/react";

    export default function RootLayout({ children }) {
      return (
        <IntentCtrlProvider apiUrl="http://app.intentctrl.com/api/chat" apiKey={process.env.NEXT_PUBLIC_API_KEY!}>
          {children}
        </IntentCtrlProvider>
      );
    }
    ```
  </Step>

  <Step>
    ### Start a chat [#start-a-chat]

    Inside any child component, use `useIntentCtrl()` to send messages and display responses.

    ```tsx title="components/chat-panel.tsx"
    import { useIntentCtrl } from "@intentctrl/react";

    export function ChatPanel() {
      const { messages, sendMessage, status } = useIntentCtrl();

      return (
        <div>
          {messages.map((msg) => (
            <div key={msg.id}>
              <strong>{msg.role}:</strong> {msg.content}
            </div>
          ))}
          <input
            placeholder="Ask something..."
            onKeyDown={(e) => {
              if (e.key === "Enter" && e.currentTarget.value) {
                sendMessage(e.currentTarget.value);
                e.currentTarget.value = "";
              }
            }}
          />
          {status === "streaming" && <span>Thinking...</span>}
        </div>
      );
    }
    ```

    That's it. The AI sees the current page, knows about any tools you've registered, and can respond with text or take actions.
  </Step>
</Steps>

## What's next [#whats-next]

* [Register custom tools](/docs/tools/custom) so the AI can interact with your app
* [Control permissions](/docs/configuration/permissions) to restrict which actions the AI can take
* [Learn about built-in tools](/docs/tools/built-in) the AI already has


# Overview (/docs)



An embedded AI runtime for React applications. It connects your app to an AI assistant that can understand what's on screen and take action through tools.

## How it works [#how-it-works]

Wrap your application in `<IntentCtrlProvider>`, and every component beneath it gets access to the AI chat via `useIntentCtrl()`. When the user sends a message, the current page is captured as structured content, bundled with your registered tools, and sent to your AI backend. The AI can respond naturally and call tools — both built-in DOM actions and your own custom functions.

## What you get [#what-you-get]

* **Streaming chat** — real-time AI responses with a single hook
* **Page-aware AI** — the assistant sees the page the user is looking at
* **Built-in tools** — navigate, click, type, scroll, highlight, and extract page content
* **Custom tools** — register your own functions with typed inputs
* **Permissions** — control which tools the AI may use, per user
* **Approval workflows** — require user confirmation before sensitive actions
* **Session management** — persistent conversations across page visits

## Requirements [#requirements]

Runs in the browser and requires:

* **React 19** and **React DOM 19**
* **Zod 4** — used to define tool input schemas
* **An AI backend** — use the [cloud platform](http://app.intentctrl.com) with no setup required, or self-host for free with unlimited usage. The cloud platform provides session history, analytics, and memory.

## One package [#one-package]

{/* prettier-ignore */}

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @intentctrl/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @intentctrl/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @intentctrl/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @intentctrl/react
    ```
  </CodeBlockTab>
</CodeBlockTabs>

That's all you need. Everything comes in a single dependency.


# Coming Soon (/ui)



# UI Components [#ui-components]

Coming soon. Reusable UI components for building chat interfaces with IntentCtrl will be documented here.


# Approvals (/docs/chat/approvals)



Some tools should not run without the user's explicit consent. An approval workflow is provided for these cases.

## How it works [#how-it-works]

When the AI calls a tool that has `needsApproval: true`, the execution pauses. The tool call appears in the message parts with state `"approval-requested"`. Your UI can detect this state and prompt the user.

The user either approves or denies the call:

```tsx
const { approveToolCall, denyToolCall } = useIntentCtrl();

await approveToolCall(toolCallId); // tool executes
denyToolCall(toolCallId); // tool is cancelled
```

## Tool state lifecycle [#tool-state-lifecycle]

Each tool invocation goes through a series of states as it progresses:

| state                | Meaning                           |
| -------------------- | --------------------------------- |
| `input-streaming`    | Tool arguments are being streamed |
| `input-available`    | Arguments are fully received      |
| `approval-requested` | Waiting for user approval         |
| `approval-responded` | User has approved or denied       |
| `output-available`   | Tool executed successfully        |
| `output-error`       | Tool execution failed             |
| `output-denied`      | User denied the call              |

## Detecting tool calls [#detecting-tool-calls]

Messages contain a `parts` array. Each part has a `type` field:

| type             | Represents                      |
| ---------------- | ------------------------------- |
| `"text"`         | Text content                    |
| `"reasoning"`    | AI reasoning (chain of thought) |
| `"dynamic-tool"` | A tool call (dynamic name)      |
| `"tool-<name>"`  | A tool call for a specific tool |

Tool parts include `toolCallId`, `toolName`, `state`, `input`, `output`, and `errorText`.

## Usage [#usage]

Call `approveToolCall(toolCallId)` to allow the tool to execute, or `denyToolCall(toolCallId)` to cancel it.

## When to use approvals [#when-to-use-approvals]

Enable approvals for actions that modify data, navigate the user, or perform irreversible operations. Tools that only read or highlight content typically don't need approval.


# Chat Interface (/docs/chat)



The chat interface is the primary way users interact with the AI. All functionality is available through the `useIntentCtrl()` hook.

## Hook reference [#hook-reference]

```tsx
const {
  messages, // Array of messages in the current conversation
  sendMessage, // Send a new user message
  status, // Current state of the chat
  stop, // Abort an in-progress response
  error, // Latest error message, if any
} = useIntentCtrl();
```

### messages [#messages]

An array of `UIMessage` objects. Each message has:

* **id** — unique identifier
* **role** — `"user"` or `"assistant"`
* **content** — text content of the message
* **parts** — structured parts — text, reasoning, tool calls, files, sources

Each part has a `type` field. The types you will encounter:

| type             | Represents                            |
| ---------------- | ------------------------------------- |
| `"text"`         | Text content                          |
| `"reasoning"`    | AI chain-of-thought reasoning         |
| `"dynamic-tool"` | A tool call (dynamic name)            |
| `"tool-<name>"`  | A tool call for a specific known tool |

Tool parts also carry `state` (e.g. `"approval-requested"`, `"output-available"`), `toolCallId`, `input`, `output`, and `errorText`.

Messages update in real-time as the AI streams its response.

### status [#status]

The chat lifecycle has four states:

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `submitted` | Message sent, waiting for the AI to begin responding    |
| `streaming` | AI is responding — content appears in real-time         |
| `ready`     | Response is complete, waiting for the next user message |
| `error`     | Something went wrong — check the `error` field          |

### sendMessage [#sendmessage]

```ts
sendMessage("Show me the sales report");
```

Sends the user's message along with the current page content, registered tools, permissions, and data context. Everything the AI needs is bundled automatically.

### stop [#stop]

Interrupts a response that's currently streaming. The response will be cut off at whatever point it's reached.

## Example [#example]

```tsx title="components/chat-window.tsx"
export function ChatWindow() {
  const { messages, sendMessage, status, stop, error } = useIntentCtrl();

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id} className={`message message-${message.role}`}>
          {message.content}
        </div>
      ))}

      {status === "streaming" && <button onClick={stop}>Stop</button>}

      {error && <div className="error">{error}</div>}

      <form
        onSubmit={(e) => {
          e.preventDefault();
          const data = new FormData(e.currentTarget);
          const text = data.get("input") as string;
          if (text.trim()) sendMessage(text);
        }}
      >
        <input name="input" placeholder="Ask something..." />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}
```


# Sessions (/docs/chat/sessions)



Conversations are organized into sessions. A session persists the chat history so users can pick up where they left off, even after closing the page.

## Session lifecycle [#session-lifecycle]

Sessions are created lazily. The first time a user sends a message, a new session is created automatically. Subsequent visits restore the most recent active session.

All session data is persisted locally via IndexedDB and synced to your backend through REST API calls.

## Switching sessions [#switching-sessions]

Users can switch between conversations:

```tsx
const { session, switchSession, newSession, refreshSessions } = useIntentCtrl();

// Switch to a past conversation
await switchSession("session-id-123");

// Start a fresh conversation
await newSession();

// Refresh the session list (e.g., after opening a sidebar)
await refreshSessions();
```

## Session state [#session-state]

```tsx
session.activeSessionId; // string | null — the currently active session
session.sessions; // { items, rowCount, pageCount, pageIndex, pageSize }
session.initState; // "idle" | "loading" | "ready" | "error"
```

The session list is paginated. Each item in `items` represents a conversation with its id, timestamps, and associated user information.

## Example: Session sidebar [#example-session-sidebar]

```tsx title="components/session-sidebar.tsx"
export function SessionSidebar() {
  const { session, switchSession, newSession } = useIntentCtrl();

  return (
    <div>
      <button onClick={newSession}>New conversation</button>

      <ul>
        {session.sessions.items.map((s) => (
          <li
            key={s.id}
            onClick={() => switchSession(s.id)}
            className={s.id === session.activeSessionId ? "active" : ""}
          >
            {s.id.slice(0, 8)}...
          </li>
        ))}
      </ul>
    </div>
  );
}
```


# Configuration (/docs/configuration)



Several options are available to control how the AI behaves in your application.

## Permissions [#permissions]

Restrict which built-in tools the AI can use — navigate, click, type, and more. Permissions can be set globally on the provider or updated dynamically per user.

## Router Integration [#router-integration]

For the `navigate` tool to work with client-side routing (Next.js, React Router), register your router so the AI can move between pages without full reloads.


# Permissions (/docs/configuration/permissions)



Permissions let you restrict the AI's ability to use tools on a per-user or per-session basis. This is useful when different users have different levels of access, or when you want to prevent the AI from taking certain actions entirely.

## Setting permissions [#setting-permissions]

Pass permissions to the provider:

```tsx
<IntentCtrlProvider
  apiKey="..."
  permissions={{
    navigate: false,   // AI cannot navigate
    click: true,       // AI can click without approval
    // type: undefined  — allowed, but requires approval (default)
  }}
>
```

## How it works [#how-it-works]

Each built-in tool has three possible permission states:

| Value       | Behavior                                                                       |
| ----------- | ------------------------------------------------------------------------------ |
| `undefined` | Tool is allowed but requires user approval if it has the approval flag enabled |
| `true`      | Tool is allowed and skips the approval prompt entirely                         |
| `false`     | Tool is denied — the AI cannot call it                                         |

Custom tools are always permitted. Their approval behavior is controlled by the `needsApproval` flag on the tool definition.

## Reactive permissions [#reactive-permissions]

You can update permissions dynamically using `usePermissions()`:

```tsx title="components/permission-panel.tsx"
import { usePermissions } from "@intentctrl/react";

export function PermissionPanel() {
  const { permissions, setPermissions } = usePermissions();

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={permissions.navigate !== false}
          onChange={(e) => setPermissions({ navigate: !e.target.checked ? false : undefined })}
        />
        Allow AI to navigate
      </label>

      <label>
        <input
          type="checkbox"
          checked={permissions.click !== false}
          onChange={(e) => setPermissions({ click: !e.target.checked ? false : undefined })}
        />
        Allow AI to click
      </label>
    </div>
  );
}
```

Changes take effect on the next message sent to the AI.

## Use cases [#use-cases]

* **Read-only mode** — deny `navigate`, `click`, and `type` so the AI can only read and highlight
* **Guest users** — deny all built-in tools, allow only custom tools
* **Admin mode** — set everything to `true` to bypass approval prompts
* **Feature gates** — tie permissions to user roles or subscription tiers


# Router Integration (/docs/configuration/router-integration)



For the `navigate` tool to work with client-side routing (rather than full page reloads), IntentCtrl needs to know about your router.

## Next.js App Router [#nextjs-app-router]

```tsx title="components/router-bridge.tsx"
"use client";

import { setRouter } from "@intentctrl/react";
import { useRouter } from "next/navigation";
import { useEffect } from "react";

export function RouterBridge() {
  const router = useRouter();

  useEffect(() => {
    setRouter({ push: (path) => router.push(path) });
  }, [router]);

  return null;
}
```

Place this component somewhere inside your `IntentCtrlProvider`.

## React Router [#react-router]

```tsx title="components/router-bridge.tsx"
import { setRouter } from "@intentctrl/react";
import { useNavigate } from "react-router-dom";
import { useEffect } from "react";

export function RouterBridge() {
  const navigate = useNavigate();

  useEffect(() => {
    setRouter({ push: (path) => navigate(path) });
  }, [navigate]);

  return null;
}
```

React Router DOM v6+ is also auto-detected via a global variable, but explicit setup is more reliable.

## Other frameworks [#other-frameworks]

Any router with a `push` method works:

```ts
setRouter({
  push: (path: string) => {
    // Your custom navigation logic
  },
});
```

## What happens without a router [#what-happens-without-a-router]

If no router is configured, the `navigate` tool falls back to `window.location.href`, which causes a full page reload. This works but loses client-side state.


# API Reference (/docs/reference)



## Components [#components]

### IntentCtrlProvider [#intentctrlprovider]

The root provider component. Must wrap any component that uses IntentCtrl hooks.

<TypeTable
  type="{
  apiUrl: {
    description: &#x22;Your AI backend chat endpoint URL&#x22;,
    type: &#x22;string&#x22;,
    default: '&#x22;http://localhost:4000/api/chat&#x22;',
  },
  apiKey: {
    description: &#x22;API key sent as the `x-api-key` header to your backend&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  permissions: {
    description: &#x22;Initial permission overrides per tool&#x22;,
    type: &#x22;RuntimePermissions&#x22;,
  },
  dataContext: {
    description: &#x22;Initial key-value context sent with every message&#x22;,
    type: &#x22;Record<string, unknown>&#x22;,
  },
  children: {
    description: &#x22;React children&#x22;,
    type: &#x22;ReactNode&#x22;,
    required: true,
  },
}"
/>

***

## Hooks [#hooks]

### useIntentCtrl [#useintentctrl]

Returns the full chat interface. Throws if used outside `IntentCtrlProvider`.

<TypeTable
  type="{
  messages: {
    description: &#x22;Array of messages in the current conversation&#x22;,
    type: &#x22;UIMessage[]&#x22;,
  },
  sendMessage: {
    description: &#x22;Send a new user message. Bundles page content, tools, permissions, and data context automatically.&#x22;,
    type: &#x22;(text: string) => Promise<void>&#x22;,
  },
  status: {
    description: &#x22;Current state of the chat lifecycle&#x22;,
    type: '&#x22;submitted&#x22; | &#x22;streaming&#x22; | &#x22;ready&#x22; | &#x22;error&#x22;',
  },
  stop: {
    description: &#x22;Abort an in-progress streaming response&#x22;,
    type: &#x22;() => void&#x22;,
  },
  error: {
    description: &#x22;Latest error message, if any&#x22;,
    type: &#x22;string | undefined&#x22;,
  },
  approveToolCall: {
    description: &#x22;Approve a pending tool call&#x22;,
    type: &#x22;(toolCallId: string) => Promise<void>&#x22;,
  },
  denyToolCall: {
    description: &#x22;Deny a pending tool call&#x22;,
    type: &#x22;(toolCallId: string) => void&#x22;,
  },
  switchSession: {
    description: &#x22;Switch to a different conversation session&#x22;,
    type: &#x22;(sessionId: string) => Promise<void>&#x22;,
  },
  newSession: {
    description: &#x22;Create a new conversation session&#x22;,
    type: &#x22;() => Promise<void>&#x22;,
  },
  refreshSessions: {
    description: &#x22;Refresh the session list from the backend&#x22;,
    type: &#x22;() => Promise<void>&#x22;,
  },
  session: {
    description: &#x22;Current session state — active session ID, session list, and initialisation status&#x22;,
    type: &#x22;SessionState&#x22;,
  },
}"
/>

### useTool [#usetool]

Registers a custom tool for the AI to call. The tool is available while the component is mounted.

<TypeTable
  type="{
  id: {
    description: &#x22;Unique tool identifier sent to the AI&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  description: {
    description: &#x22;Tells the AI what the tool does and when to call it. Write this for the AI.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  inputSchema: {
    description: &#x22;Zod schema defining the tool's expected input. Validated before execution.&#x22;,
    type: &#x22;ZodType&#x22;,
    required: true,
  },
  needsApproval: {
    description: &#x22;If `true`, execution pauses for user confirmation via `approveToolCall` / `denyToolCall`&#x22;,
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
  },
  handler: {
    description:
      &#x22;The function that runs when the AI calls the tool. Receives validated input, returns a value sent back to the AI.&#x22;,
    type: &#x22;(input) => Promise<unknown>&#x22;,
    required: true,
  },
}"
/>

### usePermissions [#usepermissions]

Reads and updates the current permission state reactively.

<TypeTable
  type="{
  permissions: {
    description: &#x22;Current permission state — controls which built-in tools are available&#x22;,
    type: &#x22;RuntimePermissions&#x22;,
  },
  setPermissions: {
    description: &#x22;Update permissions. Changes take effect on the next message.&#x22;,
    type: &#x22;(p: RuntimePermissions) => void&#x22;,
  },
}"
/>

### useDataContext [#usedatacontext]

Injects contextual data that is sent with every chat request. Data is cleaned up when the component unmounts.

<TypeTable
  type="{
  data: {
    description: &#x22;Key-value pairs injected into the runtime context. Keys are cleaned up on unmount.&#x22;,
    type: &#x22;Record<string, unknown>&#x22;,
    required: true,
  },
}"
/>

***

## Functions [#functions]

### setRouter [#setrouter]

Registers a client-side router for the `navigate` tool.

<TypeTable
  type="{
  router: {
    description: &#x22;An object with a `push` method for client-side navigation&#x22;,
    type: &#x22;{ push: (path: string) => void }&#x22;,
    required: true,
  },
}"
/>

***

## Types [#types]

### RuntimePermissions [#runtimepermissions]

Controls which built-in tools are available to the AI.

<TypeTable
  type="{
  navigate: {
    description: &#x22;Route navigation&#x22;,
    type: &#x22;boolean&#x22;,
  },
  click: {
    description: &#x22;Click interactive elements&#x22;,
    type: &#x22;boolean&#x22;,
  },
  type: {
    description: &#x22;Type into text fields&#x22;,
    type: &#x22;boolean&#x22;,
  },
  highlight: {
    description: &#x22;Flash a region to draw attention&#x22;,
    type: &#x22;boolean&#x22;,
  },
  scroll: {
    description: &#x22;Scroll an element into view&#x22;,
    type: &#x22;boolean&#x22;,
  },
  extract: {
    description: &#x22;Read a field's value or text&#x22;,
    type: &#x22;boolean&#x22;,
  },
}"
/>

* `undefined` — allowed, approval may be required
* `true` — allowed, bypasses approval
* `false` — denied

### SerializedTool [#serializedtool]

A tool definition serialized for transport.

<TypeTable
  type="{
  id: {
    description: &#x22;Unique tool identifier&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  description: {
    description: &#x22;Tool description sent to the AI&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  inputSchema: {
    description: &#x22;JSON Schema representation of the tool's input&#x22;,
    type: &#x22;JsonSchema&#x22;,
    required: true,
  },
  needsApproval: {
    description: &#x22;Whether the tool requires user confirmation&#x22;,
    type: &#x22;boolean&#x22;,
    required: true,
  },
}"
/>

### ChatRequest [#chatrequest]

The payload sent to your backend with every user message.

<TypeTable
  type="{
  message: {
    description: &#x22;The latest user message&#x22;,
    type: &#x22;UIMessage&#x22;,
    required: true,
  },
  pageContent: {
    description: &#x22;Current page rendered as annotated Markdown with CSS/XPath selectors&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  tools: {
    description: &#x22;All registered tools serialized for transport&#x22;,
    type: &#x22;SerializedTool[]&#x22;,
    required: true,
  },
  dataContext: {
    description: &#x22;Runtime context data (page info, user info, feature flags, etc.)&#x22;,
    type: &#x22;Record<string, unknown>&#x22;,
  },
  permissions: {
    description: &#x22;Permission overrides per tool&#x22;,
    type: &#x22;Record<string, boolean | undefined>&#x22;,
  },
}"
/>

### SessionState [#sessionstate]

<TypeTable
  type="{
  activeSessionId: {
    description: &#x22;The currently active session ID, or `null` if none&#x22;,
    type: &#x22;string | null&#x22;,
    required: true,
  },
  sessions: {
    description: &#x22;Paginated list of all sessions for the current visitor&#x22;,
    type: &#x22;PaginatedChatSessionsResponse&#x22;,
    required: true,
  },
  initState: {
    description: &#x22;Initialization state of the session manager&#x22;,
    type: '&#x22;idle&#x22; | &#x22;loading&#x22; | &#x22;ready&#x22; | &#x22;error&#x22;',
    required: true,
  },
}"
/>

### PaginatedChatSessionsResponse [#paginatedchatsessionsresponse]

<TypeTable
  type="{
  items: {
    description: &#x22;Array of session records&#x22;,
    type: &#x22;ChatSessionResponse[]&#x22;,
    required: true,
  },
  rowCount: {
    description: &#x22;Total number of matching records&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
  pageCount: {
    description: &#x22;Total number of pages&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
  pageIndex: {
    description: &#x22;Current page index (zero-based)&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
  pageSize: {
    description: &#x22;Number of items per page&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
}"
/>

### ChatSessionResponse [#chatsessionresponse]

<TypeTable
  type="{
  id: {
    description: &#x22;Unique session identifier&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  projectId: {
    description: &#x22;Project this session belongs to&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  projectSlug: {
    description: &#x22;Project slug&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  externalUserId: {
    description: &#x22;Optional external user ID linked to this session&#x22;,
    type: &#x22;string | null&#x22;,
    required: true,
  },
  visitorId: {
    description: &#x22;Visitor identifier&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  active: {
    description: &#x22;Whether the session is currently active&#x22;,
    type: &#x22;boolean&#x22;,
    required: true,
  },
  createdAt: {
    description: &#x22;ISO timestamp of session creation&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  updatedAt: {
    description: &#x22;ISO timestamp of last session update&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
}"
/>

### ApiResponse [#apiresponse]

<TypeTable
  type="{
  status: {
    description: &#x22;HTTP status code&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
  success: {
    description: &#x22;Whether the request succeeded&#x22;,
    type: &#x22;boolean&#x22;,
    required: true,
  },
  data: {
    description: &#x22;The response payload&#x22;,
    type: &#x22;T&#x22;,
    required: true,
  },
  message: {
    description: &#x22;Human-readable status or error message&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
}"
/>

### UIMessage [#uimessage]

Re-exported from the Vercel AI SDK. Represents a chat message with structured parts.

<TypeTable
  type="{
  id: {
    description: &#x22;Unique message identifier&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  role: {
    description: &#x22;Message sender role&#x22;,
    type: '&#x22;user&#x22; | &#x22;assistant&#x22;',
    required: true,
  },
  content: {
    description: &#x22;Text content of the message&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  parts: {
    description: &#x22;Structured parts — text, reasoning, tool calls, files, sources&#x22;,
    type: &#x22;MessagePart[]&#x22;,
    required: true,
  },
}"
/>


# Built-in Tools (/docs/tools/built-in)



Built-in tools give the AI the ability to interact with the page the same way a user would — clicking buttons, filling forms, navigating routes, and reading content.

## How the AI targets elements [#how-the-ai-targets-elements]

When the AI receives the page content, every interactive element is annotated with selector information. The annotations let the AI reference specific elements by their location on the page.

You can help the AI identify important elements by adding data attributes:

| Attribute           | Used by           | Purpose                                                         |
| ------------------- | ----------------- | --------------------------------------------------------------- |
| `data-ai-field`     | type, extract     | Marks input fields, textareas, and selects                      |
| `data-ai-action`    | click             | Marks clickable elements                                        |
| `data-ai-region`    | highlight, scroll | Marks areas or containers                                       |
| `data-ai-highlight` | —                 | Set automatically by the highlight tool on the targeted element |

Adding these attributes is optional but makes targeting more reliable.

You can style highlighted elements with CSS:

```css title="app/globals.css"
[data-ai-highlight] {
  outline: 3px solid #3b82f6;
  outline-offset: 2px;
  border-radius: 4px;
  transition: outline-color 0.2s;
}
```

The attribute is present for three seconds while the flash animation plays, then removed automatically.

## Tool reference [#tool-reference]

### navigate [#navigate]

Navigates the user to a different route.

```json
{ "target": "/dashboard/reports" }
```

Works with client-side routers (Next.js, React Router) and falls back to standard browser navigation. External URLs, `javascript:` links, and `data:` URIs are rejected for security.

### click [#click]

Clicks an interactive element.

```json
{ "label": "Submit" }
```

Matches by `data-ai-action`, `aria-label`, placeholder, or visible text. Triggers the element's native click handler.

### type [#type]

Types a value into a text field.

```json
{ "field": "Email", "value": "user@example.com" }
```

Supports all input types, textareas, and contenteditable elements. Works with framework-controlled inputs by triggering the appropriate change events.

### highlight [#highlight]

Briefly flashes an element to draw the user's attention.

```json
{ "region": "Error summary" }
```

The element is highlighted for three seconds. No approval needed — purely visual feedback.

### scroll [#scroll]

Scrolls an element into the viewport.

```json
{ "target": "Pricing section" }
```

Smooth scrolls to the element and centers it on screen.

### extract [#extract]

Reads the current value or text content of an element.

```json
{ "field": "Search input" }
```

Returns the element's value (for inputs), text content (for general elements), or inner text (for contenteditable regions).

## Controlling availability [#controlling-availability]

See [Permissions](/docs/configuration/permissions) to learn how to restrict which built-in tools the AI can use.


# Custom Tools (/docs/tools/custom)



Custom tools let you expose any function in your application to the AI. If your app can do it — search a database, fetch from an API, trigger a workflow — you can make it a tool.

## The useTool hook [#the-usetool-hook]

```tsx title="components/search-widget.tsx"
import { useTool } from "@intentctrl/react";
import { z } from "zod";

export function SearchWidget() {
  useTool({
    id: "search_knowledge_base",
    description: "Search the knowledge base for relevant articles",
    inputSchema: z.object({
      query: z.string(),
      maxResults: z.number().min(1).max(20).optional(),
    }),
    handler: async ({ query, maxResults }) => {
      const results = await searchApi(query, maxResults ?? 5);
      return results;
    },
  });

  return <div>Search widget</div>;
}
```

Every time the user sends a message, all registered tools are sent to the AI as available functions.

## Tool contract [#tool-contract]

<TypeTable
  type="{
  id: {
    description: &#x22;Unique name for the tool. The AI uses this to call it.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  description: {
    description: &#x22;Explains to the AI what the tool does and when to use it. Write this for the AI, not for humans.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  inputSchema: {
    description:
      &#x22;A Zod schema defining the tool's expected input. The AI only sees the JSON Schema representation, but inputs are validated with the full Zod schema before execution.&#x22;,
    type: &#x22;ZodType&#x22;,
    required: true,
  },
  handler: {
    description:
      &#x22;The function that runs when the AI calls the tool. Receives validated input, returns a value that's sent back to the AI.&#x22;,
    type: &#x22;(input) => Promise<unknown>&#x22;,
    required: true,
  },
  needsApproval: {
    description: &#x22;If `true`, the tool requires user confirmation before executing.&#x22;,
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
  },
}"
/>

## Writing good descriptions [#writing-good-descriptions]

The description is the most important part of a custom tool. It's how the AI decides whether to use it and how to fill in the parameters.

Bad: `"Search function"`\
Good: `"Search the product catalog by name or SKU. Returns matching products with their price, stock level, and category."`

Bad: `"Get user data"`\
Good: `"Retrieve user profile information by user ID. Use this when the user asks about their account details, settings, or personal information."`

## Lifecycle [#lifecycle]

Tools registered with `useTool()` are scoped to the component that registers them:

* **Mounted** — tool is available to the AI
* **Unmounted** — tool is removed automatically
* **Multiple instances** — if two components register the same tool ID, it stays active until both are unmounted

This means a tool for a settings panel only exists while the settings panel is open. A tool for a dashboard widget only exists while that widget is visible.

## Example: Fetching data [#example-fetching-data]

```tsx title="components/order-lookup.tsx"
import { useTool } from "@intentctrl/react";
import { z } from "zod";

export function OrderLookup() {
  useTool({
    id: "get_order_status",
    description:
      "Get the current status of an order by order ID. Returns delivery date, tracking number, and current status.",
    inputSchema: z.object({
      orderId: z.string(),
    }),
    handler: async ({ orderId }) => {
      const response = await fetch(`/api/orders/${orderId}`);
      return response.json();
    },
  });

  return null;
}
```


# Tools Overview (/docs/tools)



Tools are the mechanism through which the AI takes action. When the AI decides it needs to do something — navigate to a page, fill in a form, call an API — it invokes a tool.

There are two categories of tools:

## Built-in tools [#built-in-tools]

Six tools that let the AI interact with the DOM directly:

* **navigate** — change the current route
* **click** — click an interactive element
* **type** — enter text into a field
* **highlight** — flash a region to draw attention
* **scroll** — scroll an element into view
* **extract** — read a field's value or text

These tools are always available unless explicitly restricted. They work by using CSS and XPath selectors derived from the page's annotated content.

## Custom tools [#custom-tools]

Tools you define yourself. Any function your app can perform can be exposed as a tool — searching a database, fetching data from an API, submitting a form, or triggering a workflow.

Custom tools are registered using `useTool()` and are scoped to the component's lifecycle: they exist while the component is mounted and are cleaned up automatically.

## Tool execution flow [#tool-execution-flow]

1. The user sends a message
2. The AI receives the message along with the page content and tool definitions
3. The AI may request to call one or more tools
4. Each tool call is validated — input is checked against its schema
5. If the tool requires approval, execution pauses for user confirmation
6. The tool runs and its result is sent back to the AI
7. The AI continues its response with the tool result in context