Skip to main content

​
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:
  1. Define an AI Agent job.
  2. Define the tool actions to perform this task.

​
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.
ParameterTypeDescription
AI AgentSelectorSelect the AI Agent.
Job NameCognigyScriptSpecify the name of the job. For example, Customer Support Specialist.
Job DescriptionCognigyScriptProvide 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 ContextToggleAdd 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.
ParameterTypeDescription
Long-Term Memory InjectionSelectorAllow the AI Agent to access Contact Profile information for the current user. Select one of the following options:
  • None – no memory.
  • 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 FieldsTextThis 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 InjectionCognigyScriptSpecify a static string or a dynamic value via CognigyScript to make available to the AI Agent in the current turn.
ParameterTypeDescription
Knowledge InjectionSelectorUse 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 KnowledgeToggleAppears 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 KnowledgeToggleAppears 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 StoreSelectorAppears 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 KSliderAppears 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 TagsCognigyScriptAppears 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 TagsSelectAppears when you select When Required or Once for Each User Input. Defines the operator for filtering Knowledge Sources by tags:
  • AND — default; requires all tags to match. Example: filtering by S-a and S-b only includes Sources with both tags.
  • OR — requires at least one tag to match. Example: filtering by S-a or S-b includes Sources with either tag.
Generate Search PromptToggleAppears 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.
ParameterTypeDescription
How to handle the resultSelectDetermine 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. Chunks from the prompt response will be output into the conversation chat as soon as a Stream Buffer Flush Token is matched. You don’t need to use the AI Agent Output token and a Say Node. By default, the result is not stored in the Input or Context. To store it, enable Store Copy in Input.
Input Key to store ResultCognigyScriptAppears 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 ResultCognigyScriptAppears when Store in Context is selected. The result is stored in context.aiAgentOutput by default. You can specify another key.
Stream Buffer Flush TokensText ArrayAppears 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 immediatelyToggleAppears 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 InputToggleAppears 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.
ParameterTypeDescription
Voice SettingSelectConfigure 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:
  • Inherit from AI Agent — use the voice settings defined in the AI Agent creation settings.
  • Use Job Voice — apply custom voice settings specific to this job, allowing the AI Agent to adapt to the particular role it performs. For example, for a marketing AI Agent, the voice can be engaging, friendly, and persuasive. For customer support, it might be neutral, empathetic, and formal.
TTS VendorDropdownSelect 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)CognigyScriptAppears 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 LanguageDropdownDefine the language of the AI Agent output. Ensure it aligns with the preferred language of the end user.
Custom (Language)CognigyScriptAppears 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 VoiceDropdownDefine the voice for AI Agent output. Customize tone, gender, style, and regional specifics to align conversations with your brand and audience.
Custom (Voice)CognigyScriptAppears 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 LabelCognigyScriptAlternative 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 CachingToggleDisables 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.
ParameterTypeDescription
Tool ChoiceSelectorIf supported by your LLM Model, determines how tools should be selected by the AI Agent:
  • Auto — tools (or none) are automatically selected by the AI Agent when needed.
  • Required — the AI Agent will always use one of its Tools.
  • None — the AI Agent won’t use a tool.
Use Strict ModeToggleWhen 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.
ParameterTypeDescription
Process ImagesToggleEnables 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 TranscriptSelectorConfigures how images older than the last turn are handled to reduce token usage:
  • Minify — reduces the size of these images to 512×512 px.
  • Drop — excludes the images.
  • Keep — sends the maximum size (consumes more tokens).
Limitations and token consumption depend on the LLM used.
ParameterTypeDescription
LLMSelectorSelect 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 VersionSelectorSelect the base version of the AI Agent to use:
  • Fixed Version — choose a specific version, for example, 1.0, to ensure stability and avoid potential breaking changes. Use this version in production environments or critical workflows. The version dropdown will be updated as future AI Agent Node versions are released.
  • Latest — use the most recent version of the AI Agent Node. This gives access to the latest features but may require manual updates if breaking changes occur.
When upgrading to a fixed version or switching to the latest, always test your AI Agent carefully to ensure compatibility.
TimeoutNumberDefine the maximum number of milliseconds to wait for a response from the LLM provider.
Maximum Completion TokensSliderSet 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.
TemperatureSliderDefine 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 ContextToggleControls 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:
  • If Textual Description is filled:

    Textual Description: Select your preferred delivery option: Standard Delivery or Express Delivery.

    Quick Replies’ buttons: Standard Delivery, Express Delivery.

    Context added to the prompt: Select your preferred delivery option: Standard Delivery or Express Delivery.

  • If Textual Description is empty:

    Textual Description: empty.

    Quick Replies’ buttons: Standard Delivery, Express Delivery.

    Context added to the prompt: Standard Delivery, Express Delivery.

  • If Include Rich Media Context is inactive:

    No context is added to the prompt.

ParameterTypeDescription
Log to System LogsToggleLog errors to the system logs. They can be viewed on the Logs page of your Project. This parameter is inactive by default.
Store in InputToggleStore errors in the Input object.
Select Error Handling ApproachSelectChoose 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, useful for error recovery or custom error handling.
Select FlowSelectAppears when Go to Node is selected. Choose a Flow from the available options.
Select NodeSelectAppears when Go to Node is selected. Choose a Node from the available options.
Error Message (optional)CognigyScriptAdd an optional message to the output if the AI Agent Node fails.
ParameterTypeDescription
Log Job ExecutionToggleSend 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 ResultsToggleSend 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 CountToggleSend 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 PromptToggleSend 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 DefinitionsToggleSend 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 LatencyToggleSend 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 WebhookToggleSend 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 URLCognigyScriptEnter the URL of the webhook service to send the request logs to.
Custom Logging DataCognigyScriptEnter custom data to send with the request to the webhook service.
Condition for Webhook LoggingCognigyScriptEnter the condition for the webhook logging.
Webhook HeadersInput fieldsEnter 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 API GET /v2.0/aiagents/{aiAgentId}/jobs request. The response includes each job’s configuration details and a list of available tools.

​
More Information