Installation Guide: Embedded Agent

The @smartdatahq/embedded-agent package is a powerful tool for integrating AI-driven conversational agents into your web applications. This guide will walk you through the installation and setup process.

Prerequisites

Before using the @smartdatahq/embedded-agent package, ensure the following:

1. You have Node.js (version 14 or higher) and npm installed on your system.
2. You have a valid identifier to connect to the @smartdatahq/embedded-agent service. Make sure you contact us to get your identifier.

Installation

To install the package, use npm or yarn:

Using npm

npm install @smartdatahq/embedded-agent

Using yarn

yarn add @smartdatahq/embedded-agent

Basic Usage

Here is an example of how to integrate the embedded agent into your React application:

Import the Component

import { EmbeddedAgent } from "@smartdatahq/embedded-agent";
import "@smartdatahq/embedded-agent/dist/index.css";

If your application is mostly SSR, you might need to dynamically import the package since it needs to run on the browser. For example, in next.j, you would want to import it like this

const EmbeddedAgent = dynamic(
  () => import("@smartdatahq/embedded-agent").then((mod) => mod.EmbeddedAgent),
  {
    ssr: false,
  },
);

Configure the embedded agent

Use the following example to set up the agent in your application:

const App = () => {
  const [minimized, setMinimized] = useState(true)
  const handleSearchResults = (result: any) => {
    // Search Results
    console.log('Search Results:', result);
  };

  const handleContextUpdate = (schema: any) => {
    // Updated Context Schema to keep track of the filters applied/current state
    console.log('Updated Context Schema:', schema);
  };

  return (
    <div style={{ height: minimized ? 120 : 400 }}>
      <h1>My Embedded Agent Application</h1>
      <EmbeddedAgent
        identifier="YOUR_IDENTIFIER" // Replace with your unique identifier
        onConversationFeedback={handleSearchResults}
        onContextJsonUpdate={handleContextUpdate}
        minimized={minimized}
        onMinimizedChange={() => setMinimized(!minimized)}
        contextSchema={{
            "$schema": "http://json-schema.org/draft-07/schema#",
            "type": "object",
            "properties": {
                 "maximum_price": {
                  "type": ["integer", "null"],
                  "minimum": 0,
                  "description": "Maximum Price for the article. Optional."
                },
                "manufacturer": {
                    "type": "array",
                    "description": "Manufacturer name (e.g., Samsung, Apple).",
                    "items": {
                        "type": "string",
                         "enum": ["Samsung", "Apple", "Nokia", "Philips"],
                    },

                },
                "screen_type": {
                    "type": "string",
                    "enum": ["OLED", "LCD", "AMOLED"],
                    "description": "Type of screen (e.g., OLED, LCD, AMOLED)."
                },
                "color": {
                    "type": "string",
                    "description": "Color of the product (e.g., black, white)."
                },
                "size": {
                    "type": "string",
                    "description": "Size of the product (e.g., 13-inch, 15-inch)."
                },
                "manufacturing_date": {
                  "type": "string",
                  "format": "date",
                "description": "Manufacturing date of this product"
                },
            },
            "required": ["price", "manufacturer", "manufacturing_date", "screen_type", "color", "size"],
        }}
      />
    </div>
  );
};

API

identifier (Required)

type: string
Description: Unique identifier for connecting to the embedded agent server.

contextSchema

type: Record<string, any>
Description: Defines the schema for extracting parameters from the conversation.

Notes: The contextSchema is defined in compliance with JSON Schema draft-07. This ensures the agent uses a well-defined schema for extracting and validating context data. Learn more here: https://tour.json-schema.org/

onContextJsonUpdate

Type: (schema: any) => void
Description: Callback function triggered when the context schema updates.

onConversationFeedback

Type: (result: any) => void
Description: Callback function triggered with a result when the agent resolves the user’s request.

Additionnal API

You can also customize the embedded agent with additional props, including:
className: Custom class for styling the embedded agent container.
minimized: Default minimized state of the embedded agent. If being used, you need to update it to match the value you get from the onMinimizedChange function.
onMinimizedChange: Callback for changes in the minimized state.
conversationId: Unique conversation ID for the session. This is generated internally if not provided. It should preferably be a UUID string.
existingFilters: Existing filters to be applied to the conversation.
isRendered: boolean. You can set this to false if you don't want the agent to show on render. Instead, we will display a message that can be clicked to load the agent
onChatbotRender: This function is called when the agent is rendered. It only runs if you set render to false and manually click the message that displays in place of the agent.
onError: Callback for handling errors.