Overview

The Client-side API provides a browser (or front-end) interface to embed and control AI Agents within your web applications. Using the profound.ai.startAgent() call (and subsequent client-side methods) developers can load agents, show or hide them, send messages, and manage their lifecycle entirely from the front end.

This API enables seamless interaction between your UI and server-hosted agents, offering customization of chat interface behavior, dynamic variable injection, theming, and embedding strategies.

Starting an AI Agent

Starting an agent within your Web application involves calling the profound.ai.startAgent() API and passing a configuration object parameter. For example:

profound.ai.startAgent({
  agent: "HR.agent.json",
  embed: true
});

After an agent is started, you can use various methods of profound.ai.agent to control it:

profound.ai.agent.hide(); // Hide the agent
profound.ai.agent.show(); // Show the agent

It is also possible to manage multiple instances of an agent by using the profound.ai.Chat class:

// Show the Sales Assistant initially
const salesAgent = new profound.ai.Chat();
salesAgent.init({
  agent: "sales.agent.json",
  heading: "Sales Assistant"
});
salesAgent.show();

// Now, hide the Sales Assistant and show the Support Assistant
salesAgent.hide();
const supportAgent = new profound.ai.Chat();
supportAgent.init({
  agent: "support.agent.json",
  heading: "Support Assistant"
});
supportAgent.show();

Configuration Properties

These configuration properties are parameters you pass when calling profound.ai.startAgent(). They control how the agent is embedded, authenticated, themed, and supplied with runtime data. Use them to tailor the chat interface, domain setup, and variable injection.

Property	Description

Property	Description
agent	Specifies the server-side definition file for the AI Agent. The file should end in `.agent.json`.
embed	When set to `true`, instead of starting the agent interface immediately, a chat icon is rendered in the bottom right corner of the application.
heading	Overrides the heading text for the chat interface.
greeting	Overrides the greeting message to show at the top of the chat interface.
server	Optional URL of the Profound AI server. This property should be specified if the application is running on a server is that is separate from Profound AI.
jwt	Provides a JSON Web Token to facilitate authentication into Profound AI. The token can be supplied either as a static value to be used at the start of an agent conversation or as a function. When provided as a function, the token will be re-evaluated with every agent interaction.
theme	Sets the theme of the chat interface (e.g., "light" or "dark").
brandColor	Overrides the brand color used in the chat interface. If a brand color is not specified, the default CSS rules are used.
container	The DOM element where the agent user interface will be created. If not specified, the document body is used.
closeButton	Boolean indicating if the close button should be present.
closeTitle	The tool tip text for the close button.
sendTitle	The tool tip text for the send button.
embedIconTitle	The tool tip text for the embed icon.
promptPlaceHolder	Placeholder text for the prompt box.
pollInterval	Time interval for polling in milliseconds.
loaderMessage	Default message displayed by the loader.
data	See Application Variables under Agent Guidance for details on how utilize variable data. Variable instruction data that is specified as an object of key/value pairs or a function that returns an object of key/value pairs. The values can either be simple values (such as strings or numbers), or more complex values (such as a list of records). `// Static value(s) initialized once when the agent is started data: { "customerName": "ABC Company" } // Dynamic value(s) provided with an arrow function and evaluated with every interaction data: () => ({ "customerName": getCustomerName() })`

Methods

These client-side methods allow you to control the agent instance after initialization. You can show or hide the UI, send messages programmatically, switch themes, clear the conversation, or destroy the agent to free resources.

Method	Description

Method	Description
init(config)	Initializes the agent with the given configuration.
show()	Displays the agent interface.
hide()	Hides the agent interface.
add(info)	Adds a message to the chat UI. The info object should contain these properties: message (string) type (string) - The type controls both the functionality and the look and feel. It corresponds to the equivalent CSS class. Values can include “user-message”, “agent-response”, “greeting”.
clear()	Clears the chat messages and starts a new thread with the agent.
setTheme(newTheme)	Sets the theme of the chat interface (e.g., "light" or "dark").
setBrandColor(newBrandColor)	Sets the brand color of the chat interface. If a brand color is not specified or a null value is passed, the default CSS rules are used for the brand color.
send()	Sends the message from the prompt box to the Profound AI server.
poll()	Polls the server for responses.
showLoader(loaderMessage)	Displays the loading animation. If a loader message is not provided as a parameter, the default loader message is used.
hideLoader()	Hides the loading animation.
isLoading()	Checks if the loader is currently displayed, which indicates that the server is currently processing the user’s request.
removeEmbedIcon()	Removes the embedded chat icon in the corner of the screen. You can use this method when navigating away from a screen in a single page application. The method is accessible both from the `profound.ai.agent` and the `profound.ai` client-side objects. The following 2 method calls are equivalent: `// This method call is preferred and will work even when an agent is not started profound.ai.removeEmbedIcon(); // This method call will only work if an agent is already started profound.ai.agent.removeEmbedIcon();`
destroy()	Destroys the chat user interface and cleans up resources.