Create AI Agents
You can create an AI Agent from scratch or hire an AI Agent from the Job Market, designed for your industry, such as airlines, food services, or sales, and customize it to fit your business needs. To create an AI Agent, select one of the following options:Create from Scratch
- GUI
- API
- In the left-side menu of the Project page, select Build > AI Agents.
- Click Create AI Agent if you are creating an AI Agent for the first time, or click + New AI Agent on the AI Agents page if you have created at least one AI Agent before. Configure the following settings:
1. General Settings
1. General Settings
- In the General Settings step, fill in the following fields:
- Name โ enter a name for your AI Agent. This name will be visible to end users when the AI Agent greets them in the chat or when one AI Agent transfers the conversation to another AI Agent. For example,
Hello, my name is Sara. How can I help you?
orOur support specialist Alex will help with this question, transferring the conversation now
. - Description โ enter a description of the AI Agent that shapes its behavior and enhances its ability to understand the desired communication style. For example, describe the AI Agent as follows:
Anna works at ACME and is highly skilled at making customers feel comfortable.
- Name โ enter a name for your AI Agent. This name will be visible to end users when the AI Agent greets them in the chat or when one AI Agent transfers the conversation to another AI Agent. For example,
- In the Avatar section, select avatar of your choice or upload your custom one by clicking + next to avatars.
You can use any image as an avatar for your AI Agent, or create a Cognigy-style avatar using the Cognigy.AI PSD template. To open and customize the template, you will need Adobe Photoshop or Paint.net with the PSD plugin installed. The requirements for the avatar are as follows:
- Use an alpha channel for a transparent background.
- Set the recommended width to 136px.
- Set the recommended height to 184px.
- Save the file as
.png
. - Include
_optimized
in the file name.
2. Speaking Style
2. Speaking Style
- In the Speaking Style step, configure the following settings:
- Set up Style โ configure how the AI Agentโs choice of wording is influenced by the selected speaking style, which can affect the tone and clarity of its responses:
- Concise/Comprehensive โ adjust the slider to the left for brief responses and to the right for detailed responses.
- Formal/Informal โ adjust the slider to the left for more casual and conversational responses, and to the right for professional and structured responses.
- Voice Configuration โ assign a specific voice to your AI Agent if you want to use your AI Agent as a voice-based assistant. To configure this setting, ensure you have installed Voice Gateway and set up the Voice Preview provider. Then, fill in the fields following the same process you used for Set Session Config Node:
- TTS Vendor โ select the text-to-speech provider for your AI Agent. This setting determines which service will convert the AI Agentโs text responses into speech.
- TTS Language โ select the language that your AI Agent will use for speech output. Ensure this language aligns with the preferred language of the end user.
- TTS Voice โ select the voice from the selected TTS vendor. This setting allows you to customize the tone, gender, and style of your AI Agentโs voice.
- TTS Label โ select the alternative name of the TTS vendor, as specified in the Voice Gateway Self-Service Portal. If you have multiple speech services from the same vendor, use the label to specify which service to use.
- Disable TTS Audio Caching โ by default, this setting is deactivated. With caching enabled, previously requested TTS audio is stored in the AI Agent cache, and repeated requests for the same audio text will use the cached result instead of sending another request. With caching disabled, the AI Agent stores the TTS audio but doesnโt use it; each request is sent directly to the speech provider. Note that disabling caching can increase TTS costs. For detailed information, contact your speech provider.
- Set up Style โ configure how the AI Agentโs choice of wording is influenced by the selected speaking style, which can affect the tone and clarity of its responses:
3. Instructions
3. Instructions
- In the Instructions step, configure the following setting:
- Instructions โ provide special instructions to your AI Agent in bullet-point form. For example:
- Instructions โ provide special instructions to your AI Agent in bullet-point form. For example:
4. Knowledge Store
4. Knowledge Store
- In the Knowledge Store step, configure the following settings:
- Knowledge Store Type โ select or upload a knowledge source that the AI Agent will use to access information from the documents you provide. By accessing and understanding these knowledge bases, the AI Agent can deliver more accurate, context-aware, and helpful responses to user queries. You need to configure an embedding model to use Knowledge AI. Select one of the following options:
- Choose existing Knowledge Store โ select the Knowledge Store that the AI Agent will use to access information from the documents you provide.
- Upload Knowledge Source โ upload documents with supported formats, such as PDF, text, DOCX, PPTX, or CTXT file formats. The CTXT file format has restrictions. For more information, refer to the CTXT article.
- Upload URL Knowledge Source โ enter the URL of the web page to be used as a Knowledge Source. This type of Knowledge Source has restrictions. For more information, refer to the Web Page article.
- Knowledge Store Type โ select or upload a knowledge source that the AI Agent will use to access information from the documents you provide. By accessing and understanding these knowledge bases, the AI Agent can deliver more accurate, context-aware, and helpful responses to user queries. You need to configure an embedding model to use Knowledge AI. Select one of the following options:
5. Data Privacy & Security
5. Data Privacy & Security
- In the Data Privacy & Security step, configure the following fields:
- Contact Profile Information โ select which information the AI Agent should use from the Cognigy Contact Profile:
- None โ no data will be used from the Contact Profile. This option is selected by default.
- Selected Profile Fields โ enter specific fields from the Contact Profile for targeted data use. Specify the field using the Profile keys format and press Enter to apply it.
- Complete Profile โ use all fields from the Contact Profile to provide comprehensive user details.
- Profile Memories โ use the Memories field from the Contact Profile.
- Safety Instructions โ adjust the AI Agentโs safety settings to guide content generation, interactions, and responses, ensuring compliance with ethical, legal, and operational standards. Although these settings reduce risks, occasional unexpected outputs may still occur. The selected safety instructions are included in the prompt to enhance safety, which may increase token usage. Select the safety instructions you want to apply:
- Avoid harmful content โ prevent generating content that could be harmful, offensive, or abusive to end users.
- Avoid ungrounded content โ prevent generating content that is based on speculation or unsupported claims, ensuring it is reliable and verifiable.
- Avoid copyright infringements โ prevent generating content that violates intellectual property rights or uses copyrighted material without authorization.
- Prevent jailbreak and manipulations โ prevent attempts to bypass security measures or manipulate the AI Agent into producing unauthorized or unsafe content.
- Contact Profile Information โ select which information the AI Agent should use from the Cognigy Contact Profile:
6. Job Selection
6. Job Selection
- In the Job Selection step, select one of the following options:
- Default โ create an AI Agent with a predefined Flow, then click Create & Configure LLM to save changes and open the Flow with the created AI Agent. If you havenโt added an LLM before, the system will prompt you to configure a model to ensure your AI-driven Flow works.
- Personality Only โ create an AI Agent without a predefined Flow, then click Create to save changes.
- Job โ select one of the available jobs you want to assign to the AI Agent, then click Create to save changes.
Hire from the Job Market
- GUI
- API
- In the left-side menu on the Project page, select Build > AI Agents.
- On the AI Agents page, click Hire AI Agent. The Job Market page displays a list of available AI Agents to hire.
- Hover your cursor over the desired AI Agent template and click Hire. This action will trigger the Hire AI Agent task in the Task Manager.
- Check the status of the Hire AI Agent task by clicking
in the upper-right corner.
- Once the task is complete, go to Build > Flows and find the Flow with the AI Agent name from the template you installed.
Combine Custom and Hired AI Agents
You can reassign your custom AI Agent to take on the responsibilities of the hired AI Agent. To do this, hire an AI Agent from the Job Market and configure their interaction by defining which functions and personality traits should be combined. This approach lets you combine the strengths of both AI Agents: ready-made job functions from the hired AI Agent and your brandโs AI Agent persona from your custom AI Agent. To combine custom and hired AI Agents, follow these steps:- On the AI Agents page, select + Hire AI Agent. The Job Market page displays a list of available AI Agents to hire.
- Hover your cursor over the desired AI Agent template and click
> Hire & Configure.
- In the Select an AI Agent to Combine window, use the search field to find an AI Agent by name, then select the AI Agent from the list.
- Click Combine. This action will trigger the Hire AI Agent and Merge Package tasks in the Task Manager.
- In the left-side menu of the Project page, select Build > Flows.
- Select the Flow that belongs to the hired AI Agent. In the Flow, you will see an AI Agent Node with your custom AI Agent persona.
Configure Jobs and Tools for AI Agents
When you create an AI Agent from scratch or add one from the Job Market, you can add or change jobs and tools in the AI Agent configuration.- Open the created AI Agent and go to the Jobs tab.
- Fill in the following fields:
- Job Name โ enter a title for the job you want to assign to the AI Agent. For example,
Customer Support Specialist
. - Job Description โ enter a description of the job that outlines the responsibilities and tasks associated with the role. For example,
Handle customer inquiries, provide product information, and resolve issues efficiently
. - Instructions and Context โ provide specific instructions or guidelines that the AI Agent should follow while performing its job. For example,
Always respond politely, escalate complex issues to a human agent, and ensure customer satisfaction
.
- Job Name โ enter a title for the job you want to assign to the AI Agent. For example,
Configure Tools for AI Agents
In the Tools section, click Add Tool to add tools that the AI Agent can use to perform its job. Select one of the following options:- Regular Tools
- MCP Tools
Tool
Tool
Parameter | Type | Description |
---|---|---|
Tool ID | CognigyScript | Provide a meaningful name as a Tool ID. This ID can contain only letters, numbers, underscores (_ ), or dashes (- ). For example, update_user-1 . |
Description | CognigyScript | Provide a detailed description of what the tool does, when it should be used, and its parameters. |
Parameters
Parameters
Parameter | Type | Description |
---|---|---|
Use Parameters | Toggle | Activate this toggle to add parameters in addition to the tool name and description. The AI Agent will collect all data it needs and call a Tool with these parameters filled as arguments. These values can be accessed directly in the input.aiAgent.toolArgs object. |
Name | Text | Specify the name of the parameter. The name should be clear and concise, and describe the purpose of the parameter. |
Type | Selector | Select a type of the parameter:
|
Description | CognigyScript | Explain what parameter means by providing a brief description of the parameterโs usage. |
Enum (optional) | Enum | Define a set of values that the parameter can accept. The enum restricts the input to one of the specified values, ensuring only valid options are chosen. The enum is only available for string-type parameters in the Graphical editor. For other types, use the JSON editor. May not be supported by all LLM providers. |
Add Parameter | Button | Add a new parameter. |
Debug Settings
Debug Settings
Parameter | Type | Description |
---|---|---|
Debug Message when called | Toggle | Enable the output of a debug message when the tool is called to provide detailed information about the tool call. |
Advanced
Advanced
Parameter | Type | Description |
---|---|---|
Condition | CognigyScript | The tool will be enabled only if the condition is evaluated as true. If false, the tool isnโt part of the AI Agentโs Tools within this execution. For example, when using the unlock_account tool, you can specify a condition like context.accountStatus === "locked" . This checks the value in the context, and if it is missing or different, the tool will not be enabled. |
Configure AI Agent Settings for Each Job
Configure more settings for managing AI Agents:Memory Handling
Memory Handling
Parameter | Type | Description |
---|---|---|
Long-Term Memory Injection | Selector | Allow the AI Agent to access Contact Profile information for the current user. Select one of the following options:
|
Selected Profile Fields | Text | This parameter appears when the Inject selected Profile fields option is enabled. Enter specific fields from the Contact Profile for targeted data use. Specify the field using the Profile keys format and press Enter to apply it. |
Short-Term Memory Injection | CognigyScript | Specify a static string or a dynamic value via CognigyScript to make available to the AI Agent in the current turn. |
Grounding Knowledge
Grounding Knowledge
Parameter | Type | Description |
---|---|---|
Knowledge Injection | Selector | Use the Knowledge AI feature for the AI Agent. Select one of the following options:
|
Use AI Agent Knowledge | Toggle | The parameter appears when you select either When Required or Once for Each User Input. Enable to use the Knowledge Store configured in the AI Agent. The Knowledge Store configured within the AI Agent creation settings will be used. |
Use Job Knowledge | Toggle | The parameter appears when you select either When Required or Once for Each User Input. Enable this option to configure a specific Knowledge Store for this particular job, allowing the AI Agent to access job-specific data or resources. |
Job Knowledge Store | Selector | The parameter appears when you select either When Required or Once for Each User Input. The parameter appears when the Use Job Knowledge option is enabled. Select a specific Knowledge Store for this AI Agentโs job. |
Top K | Slider | The parameter appears when you select either When Required or Once for Each User Input. Specify how many knowledge chunks to return. Providing more results gives the AI Agent additional context, but it also increases noise and token usage. |
Source Tags | CognigyScript | The parameter appears when you select either When Required or Once for Each User Input. The tags serve to refine the scope of your knowledge search, allowing you to include only the most pertinent sections of the knowledge base and, as a result, improve the accuracy of search outputs.Before specifying tags, ensure that they were provided during the creation of the Knowledge Sources. Add Tags by specifying each Tag separately and pressing ++enter++. The maximum number of tags is 5.When you specify multiple Source Tags, the Search Extract Output Node defaults to an AND operator, meaning it only considers Sources that have all the specified Tags. This approach ensures the search results are precise and highly relevant to the end userโs query. To change this behavior, go to the Match Types for Source Tags parameter. |
Match type for Source Tags | Select | The parameter appears when you select either When Required or Once for Each User Input. The operator to filter Knowledge Sources by Source Tags. Select one of the following options:
|
Generate Search Prompt | Toggle | The parameter appears when you select Once for Each User Input. This parameter is enabled by default and allows you to generate a context-aware search prompt before executing the knowledge search. Note that enabling this parameter may lead to increased cost and latency. |
Storage and Streaming Options
Storage and Streaming Options
Parameter | Type | Description |
---|---|---|
How to handle the result | Select | Determine how to handle the prompt result:
|
Input Key to store Result | CognigyScript | The parameter appears when you select either Store in Input or Stream to Output. The result is stored in the input.aiAgentOutput object by default. You can specify another value, but the AI Agent Output Token will not work if the value is changed. |
Context Key to store Result | CognigyScript | The parameter appears when Store in Context is selected. The result is stored in the context.aiAgentOutput object by default. You can specify another key. |
Stream Buffer Flush Tokens | Text Array | The parameter appears when Stream to Output is selected. It defines tokens that trigger the stream buffer to flush to the output. The tokens can be punctuation marks or symbols, such as \n . |
Output result immediately | Toggle | The parameter appears when you select either Store in Input or Store in Context. This parameter allows you to output results immediately without using the Say Node and AI Agent Output token. |
Store Copy in Input | Toggle | The parameter appears when Stream to Output is selected. In addition to streaming the result to the output, store a copy in the Input object by specifying a value in the Input Key to store Result field. |
Voice
Voice
Parameter | Type | Description |
---|---|---|
Voice Setting | Select | Configure the voice settings for the AI Agent Job. This parameter determines how the AI Agent selects the voice for text-to-speech (TTS) output. Select one of the following options:
|
TTS Vendor | Dropdown | Select a TTS vendor from the list or add a custom one. Note that the AI Agent Node doesnโt support TTS Labels to distinguish configurations from the same TTS vendor. To use TTS Labels, add a Set Session Config Node before the AI Agent Node in the Flow editor. |
Custom (Vendor) | CognigyScript | The Custom parameter appears when you select Custom from the TTS Vendor list. Specify the custom TTS Vendor. For preinstalled providers, use all lowercase letters, for example, microsoft , google , aws . For custom providers, use the name that you specified on the Speech Service page in the Voice Gateway Self-Service Portal. |
TTS Language | Dropdown | Define the language of the voice AI Agent output. Ensure this language aligns with the preferred language of the end user. |
Custom (Language) | CognigyScript | The Custom parameter appears when you select Custom from the TTS Language list. Specify the language of the AI Agent output. The format depends on the option selected in the TTS vendor; check your TTS vendor documentation. The typical format is as follows: de-DE , fr-FR , en-US . |
TTS Voice | Dropdown | Define the voice that should be used for the voice AI Agent output. This parameter allows you to customize the AI Agentโs voice by defining its tone, gender, style, and regional specifics, making conversations more personalized and aligned with your brand and target audience. |
Custom (Voice) | CognigyScript | The Custom parameter appears when you select Custom from the TTS Voice list. Use this parameter to specify a custom voice, which is often required for region-specific voices. The format depends on the option selected in TTS Vendor and typically follows the pattern language-region-VoiceName . For example, de-DE-ConradNeural for German (Germany) male voice or en-US-JennyNeural for English (US) female voice. |
TTS Label | CognigyScript | The alternative name of the TTS vendor is the one you specify in the Voice Gateway Self-Service Portal. If you have created multiple speech services from the same vendor, use the label to specify which service to use. |
Disable TTS Audio Caching | Toggle | Disables TTS audio caching. By default, the setting is deactivated. In this case, previously requested TTS audio results are stored in the AI Agent cache. When a new TTS request is made and the audio text has been previously requested, the AI Agent retrieves the cached result instead of sending another request to the TTS provider. When the setting is activated, the AI Agent caches TTS results but doesnโt use them. In this case, each request is directly sent to your speech provider. Note that disabling caching can increase TTS costs. For detailed information, contact your speech provider. |
Tool Settings
Tool Settings
Parameter | Type | Description |
---|---|---|
Tool Choice | Selector | If supported by your LLM Model, this will determine how tools should be selected by the AI Agent:
|
Use Strict mode | Toggle | When the parameter is enabled, strict mode (if supported by the LLM provider) ensures that the arguments passed to a tool call precisely match the expected parameters. Enabling this feature can help prevent errors. However, it may cause a slight delay in the response, especially during the first call after making changes. |
Image Handling
Image Handling
Parameter | Type | Description |
---|---|---|
Process Images | Toggle | Enable the AI Agent to read and understand images attachments. Make sure that your LLM provider supports image processing; refer to your providerโs documentation. In addition, make sure that attachments are supported by and activated in your Endpoint, for example, Webchat. |
Images in Transcript | Selector | Configure how images older than the last turn are handled to reduce token usage:
|
Advanced
Advanced
Parameter | Type | Description |
---|---|---|
LLM | Selector | Select a model that supports the AI Agent Node feature. The selected Default model is the model that you specified in Settings > Generative AI Settings of your Project. Select the model that you added earlier while configuring Agentic AI feature. This model will manage your AI Agent. |
AI Agent Base Version | Selector | Select the base version of the AI Agent to use:
|
Timeout | Number | Define the maximum number of milliseconds to wait for a response from the LLM provider. |
Maximum Completion Tokens | Slider | Define the maximum number of tokens that can be used during a process to manage costs. However, if the limit is set too low, the output may be incomplete, as the process could be cut off before it finishes. For example, if you set the maximum tokens to 100, the model will stop generating content once it reaches 100 tokens. This number would be roughly equal to 100 words, depending on the language and tokenization method. |
Temperature | Slider | Define the sampling temperature, which ranges between 0 and 1. Higher values, such as 0.8, make the output more random, while lower values, such as 0.2, make it more focused and deterministic. |
Include Rich Media Context | Toggle | Controls whether context is added to the prompt. In this case, context refers to text extracted from rich media (Text with Buttons and Quick Replies). This text provides AI Agents with additional information, improving their responses.If the Textual Description parameter in the Say, Question, or Optional Question Node is filled, the context is taken only from this parameter. If the Textual Description parameter is empty, the context is taken from the button titles and alt text in Text with Buttons and Quick Replies. By default, the Include Rich Media Context parameter is active. When this parameter is inactive, no context is added.Examples:
|
Error Handling
Error Handling
Parameter | Type | Description |
---|---|---|
Log to System Logs | Toggle | Log errors to the system logs. They can be viewed on the Logs page of your Project. The parameter is inactive by default. |
Store in Input | Toggle | Store errors in the Input object. |
Select Error Handling Approach | Select | You can select one of the Error Handling options:
|
Select Flow | Select | The parameter appears when Go to Node is selected. Select a Flow from the available options. |
Select Node | Select | The parameter appears when Go to Node is selected. Select a Node from the available options. |
Error Message (optional) | CognigyScript | Add the optional message to the output if the AI Agent Node fails. |
Debug Settings
Debug Settings
Parameter | Type | Description |
---|---|---|
Log Job Execution | Toggle | Send a debug message with the current AI Agent Job configuration. The message appears in the Interaction Panel when debug mode is enabled. The parameter is active by default. |
Log Knowledge Results | Toggle | Send a debug message containing the result from a knowledge search. The message appears in the Interaction Panel when debug mode is enabled. The parameter is inactive by default. |
Show Token Count | Toggle | Send a debug message containing the input, output, and total token count. The message appears in the Interaction Panel when debug mode is enabled. Cognigy.AI uses the GPT-3 tokenizer algorithm, so actual token usage may vary depending on the model used. The parameter is inactive by default. |
Log System Prompt | Toggle | Send a debug message containing the system prompt. The message appears in the Interaction Panel when debug mode is enabled. The parameter is inactive by default. |
Log LLM Latency | Toggle | Send a debug message containing key latency metrics for the request to the model, including the time taken for the first output and the total time to complete the request. The message appears in the Interaction Panel when debug mode is enabled. The parameter is inactive by default. |
Log Tool Definitions | Toggle | Send a debug message containing information about the configured AI Agent tools. The message appears in the Interaction Panel when debug mode is enabled. The parameter is inactive by default. |
Other Operations
- GUI
- API
- CLI