Intents

Intents are actions that the AI agent can perform on the user's behalf inside your React app. You define what actions are available, what parameters they accept, and what state is currently relevant — the AI agent decides when and how to invoke them based on the user's input.

Overview

There are two building blocks:

Concept	Purpose
Intent	Declares an action: its `name`, `description`, expected `parameters`, and handler
IntentState	A named piece of app state the AI agent can read (e.g. analytics, current items in view)

Defining Intents

Use the useIntent hook to register an intent. It tells the AI what action exists, what parameters it needs, and what to call when the user triggers it.

import { useIntent, IntentParameter } from "@vableai/react";

useIntent({
  name: "addToCart",
  description: "Add a product to the shopping cart",
  parameters: {
    productId: IntentParameter.string({
      description: "The ID of the product to add",
      required: true,
    }),
    quantity: IntentParameter.number({
      description: "How many units to add",
    }),
  },
  onIntent: (parameters) => {
    const { productId, quantity } = parameters;
    CartService.add(productId, quantity ?? 1);
  },
});

Parameter types

Type	TypeScript type
`string`	`string`
`number`	`number`
`boolean`	`boolean`
`date`	`Date`

Use the IntentParameter helper to create parameters:

IntentParameter.string({ description: "...", required: true })
IntentParameter.number({ description: "..." })
IntentParameter.boolean({ description: "..." })
IntentParameter.date({ description: "..." })

Parameters can also define options to constrain the AI to a fixed set of values:

status: IntentParameter.string({
  description: "Filter by order status",
  options: ["pending", "shipped", "delivered"],
}),

Registering Intents

Call useIntent inside any component where the action is relevant. The intent is automatically registered on mount and unregistered on unmount.

import { useIntent, IntentParameter } from "@vableai/react";

function ProductPage({ productId }: { productId: string }) {
  useIntent({
    name: "addToCart",
    description: "Add this product to the shopping cart",
    parameters: {
      quantity: IntentParameter.number({
        description: "How many units to add",
      }),
    },
    onIntent: ({ quantity }) => {
      CartService.add(productId, quantity ?? 1);
    },
  });

  return <div>...</div>;
}

Intents are scoped to the component that registers them. When the component unmounts, the intent is automatically unregistered so the AI agent doesn't attempt to invoke actions that are no longer available.

Intent States

Intent states are named pieces of app state that the AI agent can read as context. They are not tied to a specific intent — they describe what is currently happening in the app.

import { useIntentState } from "@vableai/react";

useIntentState({
  name: "conversationAnalytics",
  description: "Contains analytics about conversations",
  value: data,
});

Any data relevant to the current screen or session can be exposed this way:

// Products currently in view
useIntentState({
  name: "productListing",
  description: "List of products currently displayed to the user",
  value: products.map((p) => ({ id: p.id, name: p.name, price: p.price })),
});

// Current user session
useIntentState({
  name: "currentUser",
  description: "The currently logged-in user",
  value: { id: user.id, name: user.name, plan: user.plan },
});

// Cart contents
useIntentState({
  name: "cart",
  description: "Items currently in the shopping cart",
  value: cart.items.map((i) => ({ productId: i.id, quantity: i.qty })),
});

Intent states don't need to match your intent names. They're free-form context — name them to describe what the data represents, not what action it's for.

Prompts

Use usePrompt to provide contextual instructions to the AI agent for the current page.

import { usePrompt } from "@vableai/react";

usePrompt({
  prompt: "The user is on the product listing page. Help them find and add products to their cart.",
});

The prompt is automatically scoped to the current URL and updates when the component re-renders with a new value.

Full Example

import { useIntent, useIntentState, IntentParameter } from "@vableai/react";

function ProductListPage({ products }: { products: Product[] }) {
  // Expose the add-to-cart action
  useIntent({
    name: "addToCart",
    description: "Add a product to the shopping cart",
    parameters: {
      productId: IntentParameter.string({
        description: "The ID of the product to add",
        required: true,
      }),
      quantity: IntentParameter.number({
        description: "How many units to add",
      }),
    },
    onIntent: ({ productId, quantity }) => {
      CartService.add(productId, quantity ?? 1);
    },
  });

  // Give the AI context about what's currently on screen
  useIntentState({
    name: "productListing",
    description: "List of products currently displayed to the user",
    value: products.map((p) => ({ id: p.id, name: p.name, price: p.price })),
  });

  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

React

Routing