AI Agent¶
Description¶
Note
This feature is in Beta. We encourage you to try it out and provide us with feedback.
The AI Agent Node lets you assign an AI Agent to a job, provide instructions and tool actions for that job, and configure 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 an AI Agent to a job, defines its role and responsibilities, and provides additional instructions or context to guide its actions.
AI Agent¶
| Parameter | Type | Description |
|---|---|---|
| AI Agent | Selector | Select the AI Agent to assign to the job. |
| Job Name | CognigyScript | Specify the name of the job to define the AI Agent's role. 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 will be considered in addition to those specified in the AI Agent creation settings. |
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: - None – no memory handling. - Inherit from AI Agent – use the settings specified in the AI Agent creation settings. - Inject full Contact Profile – use all information from the Contact Profile. - Inject Contact Memories only – use information only from the Memories field in the Contact Profile. - Inject selected Profile fields – use information from specific fields in the Contact Profile. |
| Selected Profile Fields | Text | The 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¶
| Parameter | Type | Description |
|---|---|---|
| Knowledge Injection | Selector | Use the Knowledge AI feature for the AI Agent. Select one of the following options: - Never — do not use the Knowledge Stores. - When Required — let the AI Agent decide when querying the Knowledge Stores is required to help the user. - Once for Each User Input — query the Knowledge Store(s) after each user input. Note that executing a query on every user input can lead to increased costs and latency. |
| 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: - AND — the default value, requires all tags to match across multiple Knowledge Sources. Consider the following example: there are Knowledge Sources with Tags S-a, S-b, and S-c. When you use the AND operator to filter by S-a and S-b, only Sources with both Tags S-a and S-b will be included in the search results.- OR — requires at least one tag to match across multiple Knowledge Sources. Consider the following example: there are Knowledge Sources with Tags S-a, S-b, and S-c. When you use the OR operator to filter by S-a or S-b, any Source with either Tag S-a or S-b will be included in the search results. |
| 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 & Streaming Options¶
| Parameter | Type | Description |
|---|---|---|
| How to handle the result | Select | Determine how to handle the prompt result: - Store in Input — stores the AI Agent result in the Input object. To print the prompt result, refer to the configured Context key in a Say Node or enable the Output result immediately option. - Store in Context — stores the result in the Context object. To print the prompt result, refer to the configured Context key in a Say Node or enable the Output result immediately option. - Stream to Output — streams the result directly into the output. This means that chunks coming from the prompt response will be output directly into the conversation chat as soon as a Stream Buffer Flush Token is matched, and you don't need to use the AI Agent Output Token token and Say Node. By default, this result won't be stored in either the Input or the Context. You can change this behavior by activating the Store Copy in Input option. |
| 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 value. |
| 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. |
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: - Auto — tools (or none) are automatically selected by the AI Agent when needed. - Required — your AI Agent will always use one of its Tools. - None — your AI Agent won't use a tool. |
| 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¶
| 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 (e.g., Webchat) |
| Images in Transcript | Selector | Configure how images older than the last turn are handled to reduce token usage: - Minify — reduces the size of these images to 512x512px. - Drop — excludes the images. - Keep — sends the max size (this option consumes more tokens). Limitations and token consumption depend on the LLM used. |
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: - Fixed Version — select a specific version, such as 1.0, to ensure stability and avoid potential breaking changes. Use this version in production environments or for critical workflows. The version dropdown will be updated as future versions of the AI Agent Node are released.- Latest — use the most recent version of the AI Agent Node. While this version ensures access to the latest features, it may cause breaking changes that require manual updates. When upgrading to a fixed version or switching to the latest, always test your AI Agent carefully to ensure it works with the selected version. |
| 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. |
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: - Stop Flow Execution — terminate the current Flow execution. - Continue Flow Execution — allow the Flow to continue executing, bypassing the error and proceeding to the next steps. - Go to Node — redirect the workflow to a specific Node in the Flow, which can be useful for error recovery or customized error handling. |
| 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¶
| Parameter | Type | Description |
|---|---|---|
| Log Job Execution | Toggle | Send a debug message with the current AI Agent Job configuration. The parameter is active by default. |
| Log Knowledge Results | Toggle | Send a debug message containing the result from a knowledge search. The parameter is inactive by default. |
| Log Token Count | Toggle | Send a debug message with the token count for both the request and completion. The parameter is inactive by default. |
AI Agent Tool Settings¶
Tool Actions are child-nodes to AI Agent Nodes. They define actions that can be taken by the AI Agent. If an AI Agent wants to execute the Tool, the branch below the child-Node is executed.
At the end of a Tool Action branch, it is advisable to use a Resolve Tool Action Node to return to the AI Agent.
Clicking on the Tool Node lets you define a tool, set its parameters, and allows for debugging by enabling detailed messages about the tool's execution.
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¶
Configure the parameters that will be collected by the AI Agent before the tool is called. You can switch between the Graphical and JSON editors. When editing the JSON, follow the JSON Schema specification.
| 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: - String — a sequence of characters. For example, "hello", "123".- Number — a numerical value, which can be either an integer (for example, 5) or a floating point number (for example, 3.14).- Boolean — a logical value representing true or false.- Array — a collection of elements, which can contain multiple values of any type. For example, ["apple", "banana", "cherry"].- Object — a collection of key-value pairs, where each key is a string and the value can be of any type. For example, {"name": "John", "age": 30}. |
| 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¶
| 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¶
| Parameter | Type | Description |
|---|---|---|
| Condition | CognigyScript | The tool will only be enabled if the condition is evaluated as true. If false, the tool is not 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. |
Example¶
AI Agent Tool¶
In this example, the unlock_account tool unlocks a user account by providing the email and specifying the reason for the unlocking.
Parameter configuration in JSON:
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "User's login email for their account."
}
},
"required": ["email"],
"additionalProperties": false
}
where:
type— the type for a tool parameter schema, which must always beobject.properties— defines the parameters for the tool configuration:email— a required tool parameter for unlocking the account.type— defines the data type for the tool parameter.description— a brief explanation of what the property represents.
required— listsemailas a required parameter, ensuring that this value is always provided when the tool is called.additionalProperties— ensures that the input contains only theemailtool parameter, and no others are allowed.