
Description
The AI Agent Node assigns a job to an AI Agent, provides instructions and tools for that job, and access to the knowledge the AI Agent can use when holding a conversation with a user. To configure this Node, follow these steps:AI Agent Settings
This configuration assigns a job to an AI Agent, defines its role and responsibilities, and provides additional instructions or context to guide its actions.AI Agent
AI Agent
Parameter | Type | Description |
---|---|---|
AI Agent | Selector | Select the AI Agent. |
Job Name | CognigyScript | Specify the name of the job. For example, Customer Support Specialist . |
Job Description | CognigyScript | Provide a description of the job responsibilities to guide the AI Agent’s interactions. For example, Assist customers with product issues, escalate complex cases, and provide guidance on best practices . |
Instructions and Context | Toggle | Add specific instructions or context as a system message to help the AI Agent better fulfill the job requirements. For example, Stay professional and friendly; focus on problem-solving and clarity . These instructions are considered in addition to those specified in the AI Agent creation settings. |
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 | Appears when you select 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 | Appears when you select 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 | Appears when you select When Required or Once for Each User Input and Use Job Knowledge is enabled. Select a specific Knowledge Store for this AI Agent’s job. |
Top K | Slider | Appears when you select 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 may increase noise and token usage. |
Source Tags | CognigyScript | Appears when you select When Required or Once for Each User Input. Tags refine the scope of your knowledge search, including only the most relevant sections of the knowledge base to improve accuracy. Before specifying tags, ensure they were provided during the creation of the Knowledge Sources. Add tags by entering each separately and pressing Enter. Max 5 tags. When multiple Source Tags are specified, the Search Extract Output Node defaults to the AND operator, meaning it only considers Sources that have all specified tags. To change this behavior, adjust the Match Type for Source Tags parameter. |
Match Type for Source Tags | Select | Appears when you select When Required or Once for Each User Input. Defines the operator for filtering Knowledge Sources by tags:
|
Generate Search Prompt | Toggle | Appears when you select Once for Each User Input. Enabled by default. Generates a context-aware search prompt before executing the knowledge search. May increase 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 | Appears when Store in Input or Stream to Output is selected. The result is stored in input.aiAgentOutput 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 | Appears when Store in Context is selected. The result is stored in context.aiAgentOutput by default. You can specify another key. |
Stream Buffer Flush Tokens | Text Array | Appears when Stream to Output is selected. Defines tokens that trigger the stream buffer to flush to the output. Tokens can be punctuation marks or symbols, such as \n . |
Output result immediately | Toggle | Appears when Store in Input or Store in Context is selected. Allows immediate output of results without using the Say Node and AI Agent Output token. |
Store Copy in Input | Toggle | Appears when Stream to Output is selected. In addition to streaming the result, stores 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: The AI Agent Node doesn’t support TTS Labels to distinguish configurations from the same vendor. To use TTS Labels, add a Set Session Config Node before the AI Agent Node in the Flow editor. |
Custom (Vendor) | CognigyScript | Appears when Custom is selected in TTS Vendor. Specify the custom TTS Vendor. For preinstalled providers, use lowercase, for example, microsoft , google , aws . For custom providers, use the name defined on the Speech Service page in the Voice Gateway Self-Service Portal. |
TTS Language | Dropdown | Define the language of the AI Agent output. Ensure it aligns with the preferred language of the end user. |
Custom (Language) | CognigyScript | Appears when Custom is selected in TTS Language. Specify the output language. Format depends on the TTS vendor; check vendor documentation. Typical format: de-DE , fr-FR , en-US . |
TTS Voice | Dropdown | Define the voice for AI Agent output. Customize tone, gender, style, and regional specifics to align conversations with your brand and audience. |
Custom (Voice) | CognigyScript | Appears when Custom is selected in TTS Voice. Specify a custom voice, often required for region-specific voices. Format depends on TTS Vendor and typically follows language-region-VoiceName , for example, de-DE-ConradNeural , en-US-JennyNeural ). |
TTS Label | CognigyScript | Alternative name for the TTS vendor, as specified in the Voice Gateway Self-Service Portal. Use this when multiple speech services from the same vendor exist. |
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, determines how tools should be selected by the AI Agent:
|
Use Strict Mode | Toggle | When enabled, strict mode (if supported by the LLM provider) ensures that arguments passed to a tool call precisely match the expected parameters. This helps prevent errors but may slightly delay responses, especially during the first call after making changes. |
Image Handling
Image Handling
Parameter | Type | Description |
---|---|---|
Process Images | Toggle | Enables the AI Agent to read and understand image attachments. Ensure that your LLM provider supports image processing (refer to your provider’s documentation). Also verify that attachments are supported and activated in your Endpoint, such as Webchat. |
Images in Transcript | Selector | Configures 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 one specified in Settings > Generative AI Settings of your Project. Choose the model you added earlier while configuring the 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 | Set the maximum number of tokens that can be used during a process to manage costs. If the limit is too low, the output may be incomplete. For example, setting 100 tokens roughly corresponds to 100 words, depending on language and tokenization. |
Temperature | Slider | Define the sampling temperature, ranging from 0 to 1. Higher values, for example, 0.8. make output more random; lower values, for example, 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 such as Text with Buttons, Quick Replies, and other types. 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 the rich media. 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. This parameter is inactive by default. |
Store in Input | Toggle | Store errors in the Input object. |
Select Error Handling Approach | Select | Choose one of the Error Handling options:
|
Select Flow | Select | Appears when Go to Node is selected. Choose a Flow from the available options. |
Select Node | Select | Appears when Go to Node is selected. Choose a Node from the available options. |
Error Message (optional) | CognigyScript | Add an 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 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. |
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. |
Send request logs to Webhook | Toggle | Send the request sent to the LLM provider and the subsequent completion to a webhook service, including metadata, the request body, and custom logging data. With this parameter, you can use a webhook service to view detailed logs of the request to the LLM. The parameter is inactive by default. |
Webhook URL | CognigyScript | Enter the URL of the webhook service to send the request logs to. |
Custom Logging Data | CognigyScript | Enter custom data to send with the request to the webhook service. |
Condition for Webhook Logging | CognigyScript | Enter the condition for the webhook logging. |
Webhook Headers | Input fields | Enter the headers to send with the request to the webhook service. Use the Key and Value fields to enter a header. The Value field supports CognigyScript. After entering the header key, new empty Key and Value fields are automatically added, in case you need to add more headers. Alternatively, you can click Show JSON Editor and add input examples in the code field. |
Examples
Get AI Agent Jobs and Tools via API
You can retrieve all job configurations and associated tools for a specific AI Agent via the Cognigy.AI APIGET /v2.0/aiagents/{aiAgentId}/jobs
request. The response includes each job’s configuration details and a list of available tools.