> ## Documentation Index
> Fetch the complete documentation index at: https://docs-classic.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage AI Agents
[Updated in 2026.20.0](https://docs-classic.cognigy.com/release-notes/2026.20.md)
To manage a new generation of AI Agents, Cognigy introduces the *AI Agent Management* interface,
where you can create, edit, and delete AI Agents.
## 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](#create-from-scratch)
* [Hire from the Job Market](#hire-from-the-job-market)
### Create from Scratch
> [tab] GUI
>
> 1. In the left-side menu of the **Project** page, select **Build > AI Agents**.
>
> 2. 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:
>
> > [accordion] 1. General Settings
> >
> > 1. 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?` or `Our 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.`
> > 2. 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 PSD template](https://docscognigyassets.blob.core.windows.net/assets/Template.psd). To open and customize the template, you will need Adobe Photoshop or [Paint.net](https://www.getpaint.net/) with the [PSD plugin](https://www.psdplugin.com/) 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.
>
> > [accordion] 2. Speaking Style
> >
> > 1. 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](https://docs-classic.cognigy.com/voice-gateway/index.md) and set up the [Voice Preview](https://docs-classic.cognigy.com/ai/agents/test/voice-preview.md) provider. Then, fill in the fields following the same process you used for [Set Session Config Node](https://docs-classic.cognigy.com/ai/agents/develop/node-reference/voice/voice-gateway/parameter-details.md):
> > * **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](https://docs-classic.cognigy.com/voice-gateway/webapp/applications.md#add-additional-tts-and-stt-vendor). 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.
> > * **Language Configuration** — by default, this setting is activated. Deactivate automatic language detection to ensure the AI Agent always responds in the language defined by your instructions. This setting provides predictable and consistent responses, preventing unintended language switching when users say or type words from more than one language. When active, this setting also simplifies the system prompt, giving you clearer control over language behavior.
>
> > [accordion] 3. Instructions
> >
> > 1. In the **Instructions** step, configure the following setting:
> > * **Instructions** — provide special instructions to your AI Agent in bullet-point form. For example:
> > ```txt theme={null}
> > - Greet users warmly and professionally.
> > - Keep responses concise; expand only if requested.
> > - Start with a formal tone; adjust as needed.
> > - Share troubleshooting links for technical issues.
> > - Apologize if errors occur, then correct promptly.
> > ```
>
> > [accordion] 4. Knowledge Store
> >
> > 1. 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](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/overview) to use Knowledge AI. Select one of the following options:
> > * **Choose existing Knowledge Store** — select the [Knowledge Store](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-store.md) 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](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-source/text-formats/ctxt.md) 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](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-source/text-formats/web-page.md) article.
>
> > [accordion] 5. Data Privacy & Security
> >
> > 1. 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](https://docs-classic.cognigy.com/ai/agents/analyze/contact-profiles.md):
> > * **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](https://docs-classic.cognigy.com/ai/agents/analyze/contact-profiles.md#profile-schema) 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](https://docs-classic.cognigy.com/ai/agents/analyze/contact-profiles.md#profile-schema) 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.
>
> > [accordion] 6. Job Selection
> >
> > 1. 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](https://docs-classic.cognigy.com/ai/agents/overview.md#prerequisites) 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.
> [tab] API
>
> You can create an Agent from scratch using the [Cognigy API POST beta/aiagents](https://api-trial.cognigy.ai/openapi#post-/beta/aiagents) request.
### Hire from the Job Market
> [tab] GUI
>
> 1. In the left-side menu on the **Project** page, select **Build > AI Agents**.
> 2. On the **AI Agents** page, click **Hire AI Agent**. The **Job Market** page displays a list of available AI Agents to hire.
> 3. 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.
> 4. Check the status of the **Hire AI Agent** task by clicking  in the upper-right corner.
> 5. Once the task is complete, go to **Build > Flows** and find the Flow with the AI Agent name from the template you installed.
> [tab] API
>
> You can hire an Agent from the Job Market using the [Cognigy API POST beta/aiagents/hire](https://api-trial.cognigy.ai/openapi#post-/beta/aiagents/hire) request.
## 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:
1. On the **AI Agents** page, select **+ Hire AI Agent**. The **Job Market** page displays a list of available AI Agents to hire.
2. Hover your cursor over the desired AI Agent template and click  **> Hire & Configure**.
3. 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.
4. Click **Combine**. This action will trigger the **Hire AI Agent** and **Merge Package** tasks in the Task Manager.
5. In the left-side menu of the **Project** page, select **Build > Flows**.
6. 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.
1. Open the created AI Agent and go to the **Jobs** tab.
2. 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`.
### 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:
> [tab] Regular Tool
>
> A tool is a specific task that an AI Agent can perform. The AI Agent can call tools to perform different tasks, such as retrieving information from a database or interacting with an external API. Fill in the following fields:
>
> > [accordion] Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). If you use more than one tool, the tool ID provides context to trigger the correct tool. In this case, enter a clear tool ID for each tool, for example, `update_user-1`. |
> > | Description | CognigyScript | Defines instructions to guide the AI Agent to call the tool. The description field provides context to trigger the tool. Enter a detailed description of what the tool does, when it should be used, and what parameters it requires. |
>
> > [accordion] 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](https://json-schema.org).
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Use Parameters | Toggle | Displays the **Parameters** section in the Node editor. In this section, you can define additional parameters for the tool. The AI Agent collects all data it needs and calls a tool with these parameters filled as arguments. This parameter values can be accessed directly in the `input.aiAgent.toolArgs` object. |
> > | Name | Text | Sets the name of the parameter. The name must be clear and concise, and describe the purpose of the parameter. |
> > | Type | List | Sets the parameter type:- **String** — a sequence of characters. For example, `"hello"`, `"123"`.
- **Number** — a numerical value, which can be either an integer, for example, `5`, or a float, 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 | Text | Describes the parameter's purpose. |
> > | Enum (optional) | Enum | Defines 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. Might not be supported by all LLM providers. |
> > | Add Parameter | Button | Adds another parameter. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the tool. If false, the AI Agent can't access the tool during execution. For example, when using the `unlock_account` tool, you can enter a condition like `context.accountStatus === "locked"`. With this condition, the AI Agent checks the value of the `context.accountStatus` key in the Context object, and if the key is missing or the value is different from `"locked"`, the AI Agent can't use the tool. |
> [tab] MCP
>
> An MCP tool connects to a remote [MCP server](https://modelcontextprotocol.io/introduction) to load tools that the AI Agent can execute. Fill in the following fields:
>
> > [accordion] MCP Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Name | CognigyScript | Defines a name for the MCP connection. This name helps you identify the source of the loaded tool. |
> > | MCP Server SSE URL | CognigyScript | Defines the URL to an SSE (server-sent events) endpoint from a remote [MCP server](https://modelcontextprotocol.io/introduction). Ensure that you connect only to trusted MCP servers. |
> > | Timeout | Slider | Sets the timeout for the MCP connection in seconds. |
>
> > [accordion] Authentication
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Authentication Type | List | Sets the authentication type to use for the MCP server connection. Select one of the following options: - **None** — no authentication. This option is used by default.
- **OAuth2** — authenticate using OAuth 2.0, which provides improved security and control compared to API keys. OAuth 2.0 supports scoped permissions, expiring tokens, and reduced exposure through short-lived tokens.
If you want to use a different authentication method, such as an API key, you can add it as a custom header in **Custom Headers** of the **Advanced** section. |
> > | OAuth2 Parameters | List | Opens the dialog to configure OAuth 2.0 authentication. The dialog includes fields that allow the AI Agent to securely request and use access tokens when communicating with the MCP server. Configure the following fields: - **Connection Name** — enter a descriptive name for the connection, for example, `MCP Tool OAuth`.
- **OAuth URL** — enter the token endpoint URL exposed by the MCP server, for example: `https://mcp.example.com/oauth2/token`.
- **Client ID** — enter the application (client) ID issued by the MCP server.
- **Client Secret** — enter the application secret issued by the MCP server. Keep this secret secure.
- **Scope** — add a list of scopes that define the permissions required by your application, for example: `read write admin`. Separate multiple scopes with spaces.
|
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Loaded Tools | Toggle | Displays a debug message listing all tools loaded from the MCP server. The debug message also includes tools filtered out in the [Advanced section](#advanced). This parameter shows whether tools were loaded from the cache or directly from the MCP server. |
> > | Debug with Parameters | Toggle | Includes the tool parameters in the debug message. |
> > | Debug calling Tool | Toggle | Outputs a debug message with detailed information about the tool call each time it is triggered. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Cache Tools | Toggle | Disables caching of loaded tools during development. Ensure that caching is enabled in production for performance reasons. The caching time is 10 minutes. In [debug mode](ai/agents/test/interaction-panel/chat#debug-mode), you can verify whether the cache was used. To do this, make sure **Debug Loaded Tools** is enabled. For more information, see the [Debug Settings](#debug-settings) section. |
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the MCP tool. If false, the AI Agent can't access the tool during execution. For example, when using the `unlock_account` tool, you can enter a condition like `context.accountStatus === "locked"`. With this condition, the AI Agent checks the value of the `context.accountStatus` key in the Context object, and if the key is missing or the value is different from `"locked"`, the AI Agent can't use the tool. |
> > | Tool Filter | Select | Excludes tools from execution. You can select one of the following options:- **None** — no tool filtering is applied, and all tools are available for execution. This option is selected by default.
- **Whitelist** — only tools on the list are available for execution, while all other tools are excluded.
- **Blacklist** — excludes the tools on the list from execution, while all other tools remain available.
|
> > | Blacklist | CognigyScript | This parameter appears if you select **Blacklist** in **Tool Filter**. Defines which tools to block from execution. Enter only one tool per field. |
> > | Whitelist | CognigyScript | This parameter appears if you select **Whitelist** in **Tool Filter**. Sets the tools you want to allow for execution. Enter only one tool per field. |
> > | Custom Headers | Input fields | Sets the headers to send with the request to the MCP server. You can switch between the graphical and JSON editors to enter the header key and value either in the **Key** and **Value** fields or in the code field in JSON format. |
> > | Key | Text | Sets the header name. After entering the header key, new empty **Key** and **Value** fields are automatically added, in case you need to add more headers. |
> > | Value | CognigyScript | Sets the header value. |
>
> You can add multiple tools to the AI Agent. The recommended maximum number of tools is 20. The following video shows an MCP Tool example:
>
> [MCP Tool](https://www.youtube.com/embed/pRjJtbfw4_0)
> [tab] A2A Agent
>
> An A2A Agent tool connects to a remote A2A agent through the open [Agent2Agent (A2A) protocol](https://a2a-protocol.org/) and uses it as a single tool. Cognigy.AI automatically creates a Call A2A Agent Node below the A2A Agent Node to execute the call. Fill in the following fields:
>
> > [accordion] A2A Agent
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Name | CognigyScript | Defines the name of the A2A Agent connection. |
> > | A2A Agent Base URL | CognigyScript | Defines the base URL of the A2A agent. Connect only to trusted A2A agents. |
> > | Custom Agent Card Path | CognigyScript | Overrides the default Agent Card discovery path. |
> > | Test Connection | Button | Tests the connection and verifies that the remote Agent Card can be retrieved. |
> > | Timeout | Slider | Sets the request timeout in seconds when **Execution mode** is **Blocking**. Ranges from 1 to 30 seconds. The default value is `12`. |
> > | Execution mode | List | Determines how the Node waits for the remote A2A agent:- **Blocking** — waits for the final result.
- **Non-blocking** — sends the message and polls the task until it completes or the **Task timeout** is reached.
|
> > | Task timeout | Slider | Sets the maximum time in seconds to poll a task when **Execution mode** is **Non-blocking**. Ranges from 10 to 300 seconds. The default value is `60`. |
> > | Max autonomous calls per turn | Slider | Limits the number of times the AI Agent Node can call this tool autonomously during one turn. Ranges from 1 to 10. The default value is `4`. |
> > | Cache Agent Card | Toggle | Caches the remote Agent Card for 10 minutes. This parameter is active by default. When developing, set the parameter to inactive to fetch the Agent Card on every turn. |
>
> > [accordion] Authentication
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Authentication Type | List | Authentication method for requests to the remote A2A agent: **None**, **OAuth2**, **Bearer Token**, **Basic Auth**, or **API Key**. |
> > | OAuth2 Parameters | Connection | Appears when **OAuth2** is selected. Configures the connection used to obtain and cache an access token. |
> > | Basic Auth Parameters | Connection | Appears when **Basic Auth** is selected. Configures the username and password. |
> > | Bearer Token | Connection | Appears when **Bearer Token** is selected. Configures the token sent in the `Authorization` header. |
> > | API Key | Connection | Appears when **API Key** is selected. Configures the API key value. |
> > | API Key Header Name | CognigyScript | Appears when **API Key** is selected. Specifies the header used for the API key. Default: `X-API-Key`. |
> > | Use Authentication for Agent Discovery | Toggle | Applies the configured authentication to Agent Card discovery. Inactive by default. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug loaded A2A Skills | Toggle | Displays the skills loaded from the remote Agent Card and indicates whether the Agent Card came from the cache. This parameter is active by default. |
> > | Debug calling A2A Skill | Toggle | Displays a debug message when the tool is called. This parameter is active by default. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Condition | CognigyScript | Enables the tool only when the condition evaluates to `true`. |
> > | A2A Skill Filter | Select | Controls which remote skills are summarized in the tool description. The A2A Agent Node remains a single tool regardless of the filter. Options:- **None** — includes all skills.
- **Whitelist** — includes only the specified skills.
- **Blacklist** — excludes the specified skills.
|
> > | Whitelist | CognigyScript | Appears when **Whitelist** is selected. Specifies the skill IDs to include. |
> > | Blacklist | CognigyScript | Appears when **Blacklist** is selected. Specifies the skill IDs to exclude. |
> > | Custom Headers | - | Adds custom headers to requests sent to the remote A2A agent. Supports CognigyScript values. |
>
> Use the Call A2A Agent Node, created automatically below the A2A Agent Node, to modify or inspect the message before it's sent, add a Say Node, and configure how the result is returned to the AI Agent Node.
>
> > [accordion] Call A2A Agent
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Resolve Immediately | Toggle | Immediately returns the full result to the AI Agent Node as the tool answer. This parameter is active by default. |
> > | Progress Message | CognigyScript | Sends an optional status message to the A2A client. The message is sent only to a client connected via an [A2A Server Endpoint](https://docs-classic.cognigy.com/ai/agents/deploy/endpoint-reference/a2a-server.md) with streaming enabled. This setting is relevant only when this Cognigy.AI Flow is called via an A2A Server Endpoint. If the parameter is empty, an automatically generated message such as `Delegating to ...` is shown instead. |
>
> > [accordion] Storage Options
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | How to handle the result | Select | Determines where to store the result: **Input** or **Context**. **Store in Input** is selected by default. |
> > | Input Key to store Result | CognigyScript | Appears when **Store in Input** is selected. Stores the result in `input.aiAgent.toolResult` by default. |
> > | Context Key to store Result | CognigyScript | Appears when **Store in Context** is selected. Stores the result in `context.aiAgent.toolResult` by default. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug A2A Skill Result | Toggle | Displays a debug message with the result after a successful call. This parameter is inactive by default. |
> > | Debug Raw Request | Toggle | Displays the raw JSON-RPC request sent to the A2A agent. This parameter is inactive by default. |
> [tab] Knowledge
>
> A Knowledge tool is a tool that allows the AI Agent to directly access [Knowledge Stores](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-store.md) to provide context-aware responses. Fill in the following fields:
>
> > [accordion] Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Knowledge Store | List | Sets the Knowledge Store to read information from. |
> > | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). If you use more than one Knowledge tool, the tool ID provides context to trigger the correct Knowledge tool. In this case, enter a clear tool ID for each Knowledge tool, for example, `search_appliances` |
> > | Description | CognigyScript | Defines instructions to guide the AI Agent to call the Knowledge tool. The description field provides context to trigger the Knowledge tool. If you want to use more than one Knowledge tool, enter clear instructions for the cases when each Knowledge tool should be used. For example, `Find the answer to prompts or questions about appliances by searching the attached data sources. Use this tool when a customer asks about appliance items such as washing machines, dryers, and other household appliances. Focus exclusively on a knowledge search and don't execute tasks like small talk, calculations, or script running.` |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Top K | Slider | Sets how many Knowledge Chunks to return. The default value is 5, and the maximum value is 10. Providing more results gives the AI Agent additional context, but it also increases noise and token usage. |
> > | Store Location | List | Sets whether and where to store the knowledge search results. Select one of the following options:- **Don't store** — the content isn't stored. This option is set by default.
- **Input** — the content is stored in the Input object.
- **Context** — the content is stored in the Context object.
|
> > | Input Key to store result | CognigyScript | This parameter appears when **Store Location** is set to **Input**. The property in the Input object where the result is stored. For example, if you enter `knowledgeSearch`, you can retrieve the knowledge search result from `input.knowledgeSearch`. |
> > | Context Key to store result | CognigyScript | This parameter appears when **Store Location** is set to **Context**. The property in the Context object where the result is stored. For example, if you enter `knowledgeSearch`, you can retrieve the knowledge search result from `context.knowledgeSearch`. |
> > | Source Tags | CognigyScript | Defines [Knowledge Source Tags](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-source/knowledge-source-tags.md) to refine the scope of your knowledge search, including only the most relevant Knowledge Chunks in the Knowledge Store. Before entering the tags, ensure they are included in the Knowledge Sources. Add a tag by entering it in the field and pressing Enter. You can add up to 5 Source Tags. When multiple Source Tags are added, 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 | List | The operator to filter Knowledge Sources by Source Tags. Select one of the following options:- **AND** — requires all Source Tags to match across multiple Knowledge Sources. This option is selected by default. Consider the following example: there are Knowledge Sources with Source 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` are included in the search results.
- **OR** — requires at least one Source Tag to match across multiple Knowledge Sources. Consider the following example: there are Knowledge Sources with Source 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` is included in the search results.
|
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the Knowledge tool. If false, the AI Agent can't access the tool during execution. For example, when using the Knowledge tool, you can enter a condition like `context.productCategory === "appliances"`. With this condition, the AI Agent checks the value of the `context.productCategory` key in the Context object, and if the key is missing or the value is different from `"appliances"`, the AI Agent can't use the tool. |
> [tab] Send Email
>
> The Send Email tool lets your AI Agent send emails directly to users. The Send Email tool has the capabilities and restrictions as the [Email Notification Node](https://docs-classic.cognigy.com/ai/agents/develop/node-reference/data/email-notification.md) but is more flexible. While the Email Notification Node sends emails at a fixed step in a Flow, the Send Email tool allows the AI Agent to send emails dynamically, based on user input, conversation context, or instructions. This tool makes automation more flexible and minimizes extra Flow steps.
>
> > [accordion] Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). The default ID is `send_email`. If you use more than one Send Email tool, the tool ID provides context to trigger the correct Send Email tool. In this case, enter a clear tool ID for each Send Email tool, for example, `send_order_confirmation`. |
> > | Description | CognigyScript | Defines instructions to guide the AI Agent to call the Send Email tool. The description field provides context to trigger the Send Email tool. The default description is `Create and send a new email message.` |
> > | Recipient TO Email Addresses | CognigyScript | A comma-separated list of email addresses to which the email will be sent. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the Send Email tool. If false, the AI Agent can't access the tool during execution. For example, when using the Send Email tool, you can enter a condition like `context.orderFinished === true`. With this condition, the AI Agent checks the value of the `context.orderFinished` key in the Context object, and if the key is missing or the value is different from `true`, the AI Agent can't use the tool. |
> [tab] Handover to AI Agent
>
> The Handover to AI Agent tool lets you transfer a conversation to another AI Agent in the same or a different Flow. This approach ensures that different AI Agents share the same conversation context and can handle specific tasks, and that multi-step conversations run smoothly across Flows.
>
> > [accordion] Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). The default ID is `handover_to_ai_agent`. If you use more than one Handover to AI Agent tool, the tool ID provides context to trigger the correct Handover to AI Agent tool. In this case, enter a clear tool ID for each Handover to AI Agent tool, for example, `handover_to_billing_agent`. |
> > | Description | CognigyScript | Defines instructions to guide the AI Agent to call the Handover to AI Agent tool. The description field provides context to trigger the correct receiving AI Agent. If you use more than one Handover to AI Agent tool, enter clear instructions for the cases when each receiving AI Agent should take over. For example, `Handle product recommendations`, `Perform technical troubleshooting`, or `Assist with billing questions`. |
> > | Select Flow | List | Sets the target Flow to hand over to. By default, all Flows in the Project are displayed in the list. The selected Flow must contain an AI Agent Node. |
> > | Select Node | List | Sets the AI Agent Node to hand over to. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the Handover to AI Agent tool. If false, the AI Agent can't access the tool during execution. For example, when using the Handover to AI Agent tool, you can enter a condition like `context.accountStatus === "locked"`. With this condition, the AI Agent checks the value of the `context.accountStatus` key in the Context object, and if the key is missing or the value is different from `"locked"`, the AI Agent can't use the tool. |
> [tab] Handover to Human Agent
>
> The Handover to Human Agent tool lets you transfer a conversation to a human agent through handover providers. This tool allows your AI Agents to refer complex tasks to a human agent if they can't address the user's request.
>
> > [accordion] Tool
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). The default ID is `handover_to_human_agent`. If you use more than one Handover to Human Agent tool, the tool ID provides context to trigger the correct Handover to Human Agent tool. In this case, enter a clear tool ID for each Handover to Human Agent tool, for example, `handover_to_billing_support`. |
> > | Description | CognigyScript | Defines instructions to guide the AI Agent to call the Handover to Human Agent tool. The description field provides context to trigger the handover. Enter clear instructions for the situations when the AI Agent should refer to a human agent. For example, `Use this tool if the user explicitly asks for a human.` or `Use this tool if you fail to answer the user's question three times.` |
> > | Handover Provider | List | Sets a handover provider that you previously created in **Deploy > Handover Providers**. A section with handover provider-specific settings appears. [Configure the handover accordingly](https://docs-classic.cognigy.com/ai/escalate/handover-reference/overview):- [Live Agent](https://docs-classic.cognigy.com/ai/escalate/handover-reference/live-agent.md)
- [Chatwoot](https://docs-classic.cognigy.com/ai/escalate/handover-reference/chatwoot.md#2-add-a-handover-to-human-agent-node)
- [Salesforce](https://docs-classic.cognigy.com/ai/escalate/handover-reference/salesforce.md#2-add-a-handover-to-human-agent-node)
- [NiCE CXone](https://docs-classic.cognigy.com/ai/escalate/handover-reference/nice-cxone/overview)
- [Genesys Cloud Open Messaging](https://docs-classic.cognigy.com/ai/escalate/handover-reference/genesys-cloud-open-messaging#2-configure-handover-settings) or [Genesys Cloud Guest Chat](https://docs-classic.cognigy.com/ai/escalate/handover-reference/genesys-cloud-guest-chat.md#2-configure-handover-settings)
- [8x8](https://docs-classic.cognigy.com/ai/escalate/handover-reference/8x8.md#2-configure-handover-settings)
- [RingCentral Engage](https://docs-classic.cognigy.com/ai/escalate/handover-reference/ring-central-engage.md#2-add-a-handover-to-human-agent-node)
|
> > | Handover Accepted Message | CognigyScript | Defines the message sent to the user when the handover is requested. |
> > | Repeat Handover Accepted Message | Toggle | Repeatedly outputs the text in **Handover Accepted Message** if the user sends a message while waiting in the queue for an agent. |
>
> > [accordion] Cancel Handover Options
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Cancel Intent | CognigyScript | Defines the Intent the user must trigger to cancel the handover request. |
> > | Cancel Button Text | CognigyScript | Defines the text for a Quick Reply button that cancels the handover request when clicked. |
>
> > [accordion] On Resolve Options
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Flow Continuation | List | Controls where the Flow continues after the human agent leaves the conversation. When the user needs assistance completing the Flow with the AI Agent, the conversation is handed over to a human agent. The human agent can trigger the Flow by sending a `/bot` command as a reply in the conversation interface. For example, the user enters their date of birth in an incorrect format, and the AI Agent can't process the response. The conversation is handed over to a human agent, who identifies the incorrect format and sends the corrected date using `/bot MM/DD/YYYY`. The AI Agent takes over and continues the Flow. You can select one of the following options to determine where the Flow continues:- **Below this Node** — the Flow continues from the first Node below the Human Agent Node, regardless of where the human agent stopped assisting the user. This option is selected by default.
- **At current AgentInject Entrypoint** — the Flow continues from the Node where the human agent stopped assisting the user.
|
> > | Send resolve event to Virtual Agent | Toggle | Controls whether the Flow receives the `conversation_status_changed` event with the status set to `resolved`. This parameter is activated by default.- When the parameter is activated, the event is sent when the human agent leaves the conversation. As a result, the Flow continues immediately, without waiting for the user to send another message. If the [Lookup Case](https://docs-classic.cognigy.com/ai/agents/develop/node-reference/logic/lookup.md) Node is configured with **Handover Status** set to **Completed**, the Node can detect the completed handover and continue the Flow.
- When the parameter is deactivated, the event isn't sent when the human agent leaves the conversation. The Flow continues after the user sends their next message.
|
>
> > [accordion] Event Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Send Queue Event | Toggle | Sends an event to the Flow once the handover is queued. |
> > | Send Active Event | Toggle | Sends an event to the Flow once the handover is active. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Condition | CognigyScript | Sets a condition that must be evaluated as true to activate the Handover to Human Agent tool. If false, the AI Agent can't access the tool during execution. For example, when using the Handover to Human Agent tool, you can enter a condition like `context.issueType === "complaint"`. With this condition, the AI Agent checks the value of the `context.issueType` key in the Context object, and if the key is missing or the value is different from `"complaint"`, the AI Agent can't use the tool. |
> [tab] Execute Workflow Tool
>
> The Execute Workflow tool lets the AI Agent execute another Flow. After the target Flow executes, the conversation returns to the AI Agent.
>
> The target Flow inherits the [Context object](https://docs-classic.cognigy.com/ai/agents/develop/ai-agent-memory/context.md) from the AI Agent. If the Context object is changed during the target Flow execution, these changes are also available to the AI Agent.
>
> | Parameter | Type | Description |
> | - | - | - |
> | Tool ID | CognigyScript | Defines the tool ID. This ID can contain only letters, numbers, underscores (`_`), or dashes (`-`). The default ID is `execute_workflow`. If you use more than one Execute Workflow tool, the tool ID provides context to trigger the correct Execute Workflow tool. In this case, enter a clear tool ID for each Execute Workflow tool, for example, `execute_returns_workflow`. |
> | Description | CognigyScript | Defines instructions to guide the AI Agent to call the Execute Workflow tool. The description field provides context to trigger the Execute Workflow tool. Describe when the AI Agent should execute the target Flow. For example, `Use this tool if the user explicitly asks to return a package.` |
> | Target Flow | List | Sets the target Flow that the AI Agent executes when this tool is called. Click  to open the target Flow. |
> | Select Node | List | Sets the target Node that the AI Agent executes when the target Flow is called. You must set the Node you want to select as an Entrypoint with the [Set Entrypoint](https://docs-classic.cognigy.com/ai/agents/develop/nodes/overview#set-nodes-as-entrypoints) setting before you can select it. |
>
> > [accordion] Debug Settings
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Debug Message when called | Toggle | Activates the output of a debug message when the tool is called to provide detailed information about the tool call. |
>
> > [accordion] Advanced
> >
> > | Parameter | Type | Description |
> > | - | - | - |
> > | Parse Intents | Toggle | Sets whether Intents should be parsed in the target Flow. This parameter is activated by default. If this parameter is activated, Cognigy NLU reparses the Intents in the target Flow based on `text` in the [Input object](https://docs-classic.cognigy.com/ai/agents/develop/ai-agent-memory/input.md#accessing-input-properties). Then, Cognigy NLU generates Intent scores using the Intents from the target Flow instead of the ones from the current Flow. |
> > | Parse Slots | Toggle | Sets whether Slots should be parsed in the target Flow. This parameter is activated by default. If this parameter is activated, Cognigy NLU reparses the Slots in the target Flow based on `text` in the [Input object](https://docs-classic.cognigy.com/ai/agents/develop/ai-agent-memory/input.md#accessing-input-properties). Then, Cognigy NLU generates Slot scores using the Slots from the target Flow instead of the ones from the current Flow. |
> > | Absorb Context | Toggle | Sets whether the [default Context object](https://docs-classic.cognigy.com/ai/agents/develop/ai-agent-memory/context.md#default-context) of the target Flow is used in the context of the Flow the AI Agent is currently in. If the default Context of the target Flow has a value, it is copied into the Context object of the AI Agent as soon as the target Flow is executed. |
### Configure AI Agent Settings for Each Job
Configure more settings for managing AI Agents:
> [accordion] Memory Handling
>
> | Parameter | Type | Description |
> | - | - | - |
> | Long-Term Memory Injection | List | Allow the AI Agent to access [Contact Profile](https://docs-classic.cognigy.com/ai/agents/analyze/contact-profiles.md) 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](https://docs-classic.cognigy.com/ai/agents/develop/manage-ai-agents.md#create-ai-agents).
- **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 | 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](https://docs-classic.cognigy.com/ai/agents/analyze/contact-profiles.md#profile-schema) 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. |
> [accordion] Grounding Knowledge
>
> | Parameter | Type | Description |
> | - | - | - |
> | Knowledge Injection | List | Use the Knowledge AI feature for the AI Agent. Select one of the following options:- **Never** — don't 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 | This 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](#create-ai-agents) will be used. |
> | Use Job Knowledge | Toggle | This 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 | List | This parameter appears when you select either **When Required** or **Once for Each User Input**. This parameter appears when the **Use Job Knowledge** option is enabled. Select a specific Knowledge Store for this AI Agent's job. |
> | Top K | Slider | This parameter appears when you select either **When Required** or **Once for Each User Input**. Specify how many Knowledge Chunks to return. The default value is 3, and the maximum value is 5. Providing more results gives the AI Agent additional context, but it also increases noise and token usage. |
> | Source Tags | CognigyScript | This 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 | This 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 | This 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. |
> [accordion] Storage and Streaming Options
>
> | Parameter | Type | Description |
> | - | - | - |
> | How to handle the result | List | Determines how to handle the prompt result:- **Store in Input** — stores the result in the Input object. To print the prompt result, use the LLM Prompt Result token or `{{ci.promptResult.result}}` in the Say Node, or activate the **Output result immediately** option.
- **Store in Context** — stores the result in the Context object. To print the prompt result, use `{{cc.promptResult.result}}` in the Say Node or activate the **Output result immediately** option.
- **Stream to Output** — streams the result directly into the output. This means that the model provides outputs directly into the conversation chat as soon as Cognigy matches a Stream Buffer Flush Token, and you don't need to use the LLM Prompt Result 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. Streaming might not be supported by all [AI Agent Node](https://docs-classic.cognigy.com/ai/agents/develop/gen-ai-and-llms/model-support-by-feature.md) providers, such as Google[1](#footnote1). If streaming isn't supported, enabling the **Store Copy in Input** option saves the result to the Input object.
|
> | Input Key to store Result | CognigyScript | This parameter appears when **Store in Input** is selected or when **Stream to Output** is selected and **Store Copy in Input** is activated. Enter a JSON key under which to store the result object in the Input object. The default key is `promptResult`. |
> | Context Key to store Result | CognigyScript | This parameter appears when **Store in Context** is selected. Enter a JSON key under which to store the result object in the Context object. The default key is `promptResult`. |
> | Stream Buffer Flush Tokens | Text Array | This parameter appears when **Stream to Output** is selected. Defines tokens that trigger the stream buffer to print the output to the user. The tokens can be punctuation marks or symbols, such as `\n`. |
> | Output result immediately | Toggle | This parameter appears when you select either **Store in Input** or **Store in Context**. Outputs prompt results immediately to the user without using the Say Node and LLM Prompt Result token. This parameter is activated by default. |
> | Store Copy in Input | Toggle | This parameter appears when **Stream to Output** is selected. Stores a copy of the streamed output in the Input object. Enter the JSON key under which to store the result object in the **Input Key to store Result** field. |
> [accordion] 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:- - **Inherit from AI Agent** — use the voice settings defined in the [AI Agent creation settings](#create-ai-agents).
- - **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, if you create a marketing AI Agent, the voice can be more engaging, friendly, and persuasive. However, if the same AI Agent performs a different role, such as customer support, the voice might be more neutral, empathetic, and formal. |
> | 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](https://docs-classic.cognigy.com/ai/agents/develop/node-reference/voice/voice-gateway/set-session-config.md) 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](https://docs-classic.cognigy.com/voice-gateway/webapp/speech-services.md#add-custom-speech-vendors). 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](https://docs-classic.cognigy.com/voice-gateway/webapp/speech-services.md) 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](https://docs-classic.cognigy.com/voice-gateway/webapp/applications.md#add-additional-tts-and-stt-vendor). 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. |
> [accordion] Tool Settings
>
> | Parameter | Type | Description |
> | - | - | - |
> | Tool Choice | List | If supported by your LLM, determines how the AI Agent selects tools:- **Auto** — tools are automatically selected by the AI Agent when available and needed.
- **Required** — your AI Agent always uses one of its tools.
- **None** — your AI Agent doesn't use tools.
|
> | Use Strict mode | Toggle | If supported by the LLM provider, ensures that the arguments passed to a tool call precisely match the expected parameters. Activating this mode can help prevent errors. However, it might cause a slight delay in the response, especially during the first call after making changes. |
> [accordion] Image Handling
>
> | Parameter | Type | Description |
> | - | - | - |
> | Process Images | Toggle | Allows the AI Agent to read and understand image attachments. Ensure that your LLM supports image processing; refer to your LLM provider's documentation. In addition, ensure that attachments are supported by and activated in your Endpoint, for example, Webchat. |
> | Images in Transcript | List | Sets how images uploaded before the last turn are handled to reduce token usage. You can select the following options: - **Minify** — reduces the size of these images to 512x512px.
- **Drop** — excludes the images.
- **Keep** — sends the maximum size (this option consumes more tokens).
Limitations and token consumption depend on the LLM used. |
> [accordion] Advanced
>
> | Parameter | Type | Description |
> | - | - | - |
> | LLM | List | Select a model that supports the [AI Agent Node feature](https://docs-classic.cognigy.com/ai/agents/develop/gen-ai-and-llms/model-support-by-feature.md). 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](https://docs-classic.cognigy.com/ai/agents/overview.md#prerequisites) while configuring Agentic AI feature. This model will manage your AI Agent. |
> | AI Agent Base Version | List | 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 | Sets 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 | Defines 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 the text from the [Textual Description](https://docs-classic.cognigy.com/ai/agents/develop/node-reference/basic/say.md#output-type) field in Say, Question, and Optional Questions Nodes is added to the AI Agent's prompt. This text provides AI Agents with additional information, improving their responses. If you have filled in a **Textual Description** field in other Nodes, this text is added to the prompt as context for rich media, such as Text with Quick Replies. If the **Textual Description** field is empty, the button titles and alt text from the rich media are added to the prompt. By default, the **Include Rich Media Context** parameter is active. When this parameter is inactive, nothing related to the rich media is added to the prompt. **Examples**:- If **Textual Description** is filled in: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 information related to the rich media is added to the prompt.
|
> [accordion] Error Handling
>
> | Parameter | Type | Description |
> | - | - | - |
> | Log to System Logs | Toggle | Logs errors to the system logs. They can be viewed on the [Logs](https://docs-classic.cognigy.com/ai/agents/test/logs.md) page of your Project. This parameter is inactive by default. |
> | Store in Input | Toggle | Store errors in the Input object. |
> | Select Error Handling Approach | List | Sets how Flow execution behaves if the AI Agent Node throws an error. You can select one of the following options:- **Stop Flow Execution** — terminates the current Flow execution.
- **Continue Flow Execution** — allows the Flow to continue executing, bypassing the error and proceeding to the next steps.
- **Go to Node** — redirects Flow execution to a specific Node, which can be useful for error recovery or customized error handling.
|
> | Select Flow | List | This parameter appears when you select **Go to Node** in **Select Error Handling Approach**. Sets the Flow that includes the Node to which you want to redirect Flow execution. |
> | Select Node | List | This parameter appears when **Go to Node** in **Select Error Handling Approach** is selected. Sets the Node to which you want to redirect Flow execution. |
> | Error Message (optional) | CognigyScript | This parameter appears when you select **Continue Flow Execution** in **Select Error Handling Approach**. Add a message to output if the AI Agent Node fails. |
> [accordion] 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](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is enabled. This 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](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is enabled. This parameter is inactive by default. |
> | Show Token Count | Toggle | Sends a debug message containing the input, output, and total token count. The message appears in the Interaction Panel when [debug mode](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is active. Cognigy uses the GPT-3 tokenizer algorithm, so actual token usage may vary depending on the model used. This parameter is inactive by default. |
> | Log System Prompt & Completion | Toggle | Sends a debug message containing the system prompt sent to the LLM provider and the subsequent completion. The message appears in the Interaction Panel when [debug mode](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is active. This parameter is inactive by default. |
> | Log LLM Latency | Toggle | Sends 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](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is enabled. This parameter is inactive by default. |
> | Log Tool Definitions | Toggle | Sends a debug message containing information about the configured AI Agent tools. The message appears in the Interaction Panel when [debug mode](https://docs-classic.cognigy.com/ai/agents/test/interaction-panel/chat.md#debug-mode) is enabled. This parameter is inactive by default. |
>
> To test and refine the job settings, use the Interaction Panel on the right side of the screen.
>
> To view the AI Agent's Flow in detail, click **Advanced Editor** in the upper-right corner.
>
> One AI Agent can have multiple jobs. To add another job, click **Add Job** in the bottom-left corner. Note that each job corresponds to one Flow.
## Other Operations
> [tab] GUI
>
> You can view and delete AI Agents, and copy their Reference ID in **Build > AI Agents**.
> [tab] API
>
> You can create, edit, and delete AI Agents using [Cognigy API](https://api-trial.cognigy.ai/openapi#get-/beta/aiagents).
> [tab] CLI
>
> You can clone and edit AI Agents using [Cognigy CLI](https://github.com/Cognigy/Cognigy-CLI).
## More Information
* [Overview](https://docs-classic.cognigy.com/ai/agents/overview.md)
* [Getting Started](https://docs-classic.cognigy.com/ai/agents/quickstart.md)
***
: Note that not all LLMs support streaming.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.