@vtex/agentic-ui

A comprehensive React/Next.js library for building AI agent interfaces with chat, canvas, and interactive components integrated with VTEX Raccoon.

Overview

@vtex/agentic-ui provides a complete toolkit for creating an AI agent user interfaces within the VTEX ecosystem. It offers a standardized way to build conversational interfaces, display rich content, manage state, and integrate seamlessly with VTEX Admin applications.

Main Features

• React Components - Pre-built components for chat, canvas, messages, threads, and tools
• UI Protocol - Standardized communication layer between frontend and backend
• SSE Integration - Server-Sent Events with automatic reconnection and backoff
• State Management - Built-in hooks and utilities powered by Jotai
• VTEX Admin Integration - Drop-in solution for admin application development
• Tool Registry - Extensible system for custom tool rendering
• TypeScript Support - Full type safety across the entire library

Installation

pnpm add @vtex/agentic-ui@latest

Peer Dependencies

This package requires the following peer dependencies:

• react >= 18.3
• react-dom >= 18.3
• next >= 14
• @vtex/shoreline (latest)
• @vtex/raccoon-next (latest)
• @vtex/raccoon-analytics (latest)
• @tanstack/react-table ^8.21.3
• typescript >= 5

Documentation

| Guide | Description | |-------|-------------| | Components | Complete reference for all React components, hooks, and utilities | | UI Protocol | Communication protocol specification and data fetching hooks | | Server-Sent Events (SSE) | Real-time communication utilities with automatic reconnection | | Admin Integration | Integration solution for VTEX Admin applications |

Quick Start

This example demonstrates how to set up a Next.js application with Raccoon and agentic-ui.

Step 1: Setup Application Root

Create your _app.tsx file with the necessary providers:

import type { AppProps } from "next/app";
import { connect, bootstrap } from "@vtex/raccoon-next";
import {
  ChatProvider,
  useAgentPlatform,
  AgenticUIProvider,
} from "@vtex/agentic-ui";

// Import required styles
import "@vtex/shoreline/css";
import "@vtex/agentic-ui/css";

// Initialize Raccoon connection
connect();

function AppContent({ Component, pageProps }: AppProps) {
  // Load agent configuration based on current route
  // Pass your dynamic agent if needed: useAgentPlatform({ agent: myAgent })
  const { isLoading, agent, error, agentId, appId } = useAgentPlatform();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Failed to load agent</div>;
  }

  return (
    <AgenticUIProvider>
      <ChatProvider agent={agent} agentId={agentId} appId={appId}>
        <Component {...pageProps} />
      </ChatProvider>
    </AgenticUIProvider>
  );
}

function App(props: AppProps) {
  return <AppContent {...props} />;
}

export default bootstrap(App);

Step 2: Create an Agent Home Page

Create a page component that renders the initial chat interface at pages/app/[app]/index.tsx:

import { useEffect } from "react";
import { ChatLayout, Chat, useResetAtoms } from "@vtex/agentic-ui";

export default function AgenticPage() {
  const { reset } = useResetAtoms();

  // Reset state when component mounts
  useEffect(() => {
    reset();
  }, []);

  return (
    <ChatLayout type="home">
      <Chat />
    </ChatLayout>
  );
}

Step 3: Create a Thread/Conversation Page

Create a page for ongoing conversations at pages/app/[app]/[threadId]/index.tsx:

import { Chat, ChatLayout } from "@vtex/agentic-ui";

export default function ThreadPage() {
  return (
    <ChatLayout type="thread">
      <Chat />
    </ChatLayout>
  );
}

The useAgentPlatform hook automatically detects the agent based on the URL path, and the threadId parameter is used to load the specific conversation.

Step 4: Create a Dynamic Agent Configuration (Optional)

If you need to create a dynamic agent at runtime, define your agent configuration using createAgent. Create a file like lib/agents/my-agent.ts:

import { createAgent } from "@vtex/agentic-ui";

export const myAgent = createAgent({
  slug: "my-agent",
  id: "MY_AGENT_ID",
  apiUrl: process.env.NEXT_PUBLIC_MY_AGENT_URL ?? "",
  routes: {
    frontend: "/app/my-agent",
    stream: "/api/agent/responses",
    tasks: "/api/agent/tasks",
  },
  settings: {
    enableFeedback: true,
    enableImageProcessing: false,
  },
  ui: {
    name: "My Agent",
    title: "My Agent Assistant",
    subtitle: "Help with custom operations",
    promptSuggestions: [
      {
        title: "Get Started",
        description: "Learn what I can do",
        promptText: "What operations can you help me with?",
      },
      {
        title: "Analyze Data",
        description: "Process and analyze your data",
        promptText: "Help me analyze my sales data",
      },
    ],
  },
});

Then pass it to useAgentPlatform in your _app.tsx:

import { myAgent } from "@/lib/agents/my-agent";

function AppContent({ Component, pageProps }: AppProps) {
  // Pass the dynamic agent configuration
  const { isLoading, agent, error, agentId, appId } = useAgentPlatform({ 
    agent: myAgent 
  });
  
  // ... rest of the code
}

The hook will automatically register the agent if it doesn't exist. For static agents, see Admin Integration documentation.

Step 5: Start Development

pnpm dev

Your agent interface is now ready! Users can:

• Start new conversations from the home page
• Continue existing conversations via thread pages
• Interact with tools and view rich content in the canvas
• Navigate between different threads seamlessly

Useful Links

• GitHub Repository
• Report Issues
• Shoreline Design System
• Raccoon Documentation

Development

Local Development

When developing the agentic-ui package, changes will automatically reflect in dependent applications like @ui/. Start the development mode with:

pnpm install
pnpm dev

This enables hot-reload, allowing you to see your changes immediately in any application that depends on this package.

Building

To build the package for production:

pnpm install
pnpm build

This compiles the TypeScript code and generates the distribution files in the dist/ directory.

Publishing

To publish a new version to npm, follow these steps (be sure to be in the root of the repository):

1. Bump the version (choose patch, minor, or major):

   pnpm lerna version patch --force-publish
   # or
   pnpm lerna version minor --force-publish

2. Publish to npm:

   pnpm lerna publish from-git

The version bump will create a git tag and update the package.json. Publishing from git ensures only tagged releases are published.