Skip to main content

AI Agent

Overview​

The AI Agent module is LoyJoy's new component for building AI-driven conversational experiences. It allows an AI to understand user intent and use a set of tools to respond to requests and complete tasks. The agent can operate iteratively, meaning it can call multiple tools in sequence (e.g., search a knowledge base, then search the web) before formulating a final answer for the user.

This module replaces the older GPT Gateway, GPT Knowledge, GPT Prompt, GPT Smalltalk and GPT Recommender modules. It combines the functionality of all those modules into a single, more capable module. If your existing chats use the old modules, we recommend migrating them to the new AI Agent module.

Key Concepts​

The AI Agent module is built on two core components:

  1. Instructions (Prompts): This is where you define the AI's rules and persona. You configure its behavior and provide it with the necessary context to do its job.
  2. Tools: These are the actions the AI agent can perform. You give the agent a set of capabilities (like searching knowledge or running a process), and it will intelligently decide which one to use—or which combination of tools to use—based on the user's query.

How to Set Up Your AI Agent​

Configuring your agent is a step-by-step process.

1. Add the Module​

Start by adding the "AI Agent" module to your process. This single module will handle the conversational experience.

2. Select an AI Model​

Choose the underlying Large Language Model (LLM) that will power your agent. LoyJoy offers a wide selection, including models from Azure, OpenAI, Anthropic, Mistral, and more.

A good starting point is Azure GPT-4.1 Mini, which offers an excellent balance of speed and power.

3. Configure Instructions (Prompts)​

You define your agent's behavior using two types of instructions:

  • Pre-defined Instructions: These are system-provided settings like Role, Personality, Language Handling, and Guard Rails. You can pick and choose from the available options (e.g., select "Joyful" for Personality), but you cannot edit the text of the instructions themselves.

  • Custom Instructions: To add your own free-text rules, you must add the "Custom" instruction type. This will give you a text field where you can provide any specific information the AI needs, such as:

    • A description of your company.
    • Specific rules on how to answer certain questions.
    • Logic for iterative tool use (e.g., "First, try to find the answer using the 'Internal Knowledge' tool. If the information is not present, then use the 'Web Search' tool.").

Note: While there is no character limit for custom instructions, they should be as short and concise as possible for the best performance.

4. Add and Configure Tools​

This is where you give your agent its capabilities. When adding a tool, keep these critical points in mind:

  1. Unique Name: Each tool you add must have a unique name. You cannot have two tools with the exact same name. You can leave the default name when adding a tool, but if you add multiple tools of the same type (e.g., two Knowledge Search tools), you must change at least one name to be unique.
  2. Name and Description: The AI only sees the tool's Name and Description to understand what it does. Make these as clear and descriptive as possible. For example, instead of just "Knowledge Search," use a name like "Car Insurance Knowledge" and a description like "Searches the car insurance knowledge base for terms, conditions, and prices."
  3. Usage Logic: The AI can use multiple tools to answer a single query. If a tool requires complex logic (e.g., "Only use the 'Discount' tool if the user is a registered customer and mentions 'coupon'") or you want to define a specific order of operations (e.g., "Always try Tool A first, and only use Tool B if Tool A finds no results"), this logic must be defined in a Custom Instruction.

You can add multiple instances of the same type of tool, as long as each has a unique name. For example:

  • Tool 1 Name: car_insurance_knowledge
  • Tool 2 Name: liability_insurance_knowledge

Note: You can add as many tools as you need, but for optimal performance, we recommend keeping the number below 30.

Available Tools​

Here is a list of the tools you can add to your AI Agent:

Run Process​

This tool gives the AI the ability to start another LoyJoy process.

  • How it works: You link the tool to a specific process and give it a clear name and description (e.g., live_chat_handoff, begin_insurance_application). The AI will trigger this process when it deems it appropriate based on the user's request.
  • Capabilities: The Run Process tool can start a process within the same chat agent or perform a "return jump" to another agent.

This tool connects your agent to your LoyJoy Knowledge Database.

  • How it works: Add the tool and select the specific knowledge folder or sources it should search. Remember to give it a descriptive name that clarifies what knowledge it contains.

This tool connects the agent to your LoyJoy Product Database, allowing it to find products that match a user's request.

  • How it works: The agent will search the database for relevant products. By default, it will present its findings as text.
  • Important: To show products as rich, interactive cards in the chat, you must use this tool in conjunction with the Product Display tool.

Product Display​

This tool works with Product Search to display products as graphical cards in the chat.

  • How it works: Simply add this tool to your agent alongside a Product Search tool. When the agent finds and decides to recommend products, it will automatically use this tool to display them in a user-friendly, visual format.

Product Variants​

Allows the agent to query the product database for different variants given a set of restrictions. To be used for complex cases where products have multiple attributes (e.g., color, size, material) and you want the agent to offer specific variants based on user preferences. Only to be used in combination with the Product Search tool.

Rich Message​

Allows the agent to display rich messages, such as images, product cards, or lists in the chat. Without this tool, the agent can only respond with plain text. The difference to the Product Display tool is that this tool can be used for any rich content, not just products - especially if you are not using the product database which is required for the product tools.

  • How to use: Simply add this tool to your agent and select which rich message types it can use. The agent will then decide when to use rich messages in its responses. You should adjust the tool's name and description to explain what types of rich messages it can use (e.g., "display_image: This tool allows the agent to display an image with an optional caption.").

Note: To use images with this tool, you must host the images somewhere accessible (e.g., your company website or an image hosting service) and provide the agent with the URLs.

This tool allows the agent to search the internet to answer questions outside of its knowledge base.

  • How it works:
    • For most models (Azure, Mistral, etc.), you have to use the DuckDuckGo version of this tool, which performs web searches via the DuckDuckGo search engine.
    • For models hosted directly by OpenAI and Anthropic, use the native search tool.
  • Configuration: You can optionally restrict the web search to specific domains (e.g., your-company.com; DuckDuckGo only).

Create Memory & List Memories​

These tools allow the agent to create and retrieve memories during a conversation, enabling it to remember important details and context. The memories are stored as LoyJoy variables in the user's browser.

To be used for long-running conversations where the agent needs to retain context over multiple interactions (e.g., remembering user preferences, past interactions, or important details).

Leave AI Agent​

This tool allows to leave the AI Agent module and proceed with the next step of the process. This is useful when placing the AI Agent process module on the main part of the process, i.e. not behind the Message Start Event, and activating that the process should wait in the AI Agent process module for further customer questions. In this scenario such a tool call to leave the AI Agent is needed to proceed in the process flow.

Typically the tool could be configured with a tool description Call if the customer wants to leave the AI agent, maybe with the extension ... and wants to rate if the customer problem is solved.

MCP Connection (Advanced)​

This advanced functionality is fully available and allows your agent to connect directly to any external system that supports the Model Context Protocol (MCP).

  • What it is: MCP is a native API standard for AI agents. If your external software (like a CRM) provides an MCP endpoint, you can connect it directly to your agent.
  • How it works: Simply enter the MCP Server URL and API Key for the external service. The service will then explain its own capabilities to the AI, and the agent will decide when and how to use it.

Getting Started: Templates​

To see the AI Agent in action, check out these templates in the LoyJoy Template Store:

  • AI agent insurance demo: A pre-built example demonstrating Knowledge Search (for two different products) and Run Process.
  • Product Finder Agentic AI: A template focused on using the Product Search and Product Display tools to create a product recommender.