Jobs and tools

Once you create a flow agent, you can add or change jobs and tools in the flow agent configuration.

Open the created flow agent and go to the Jobs tab.
Fill in the following fields:
- Job Name — enter a title for the job you want to assign to the flow 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 flow 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 flow agents

In the Tools section, click Add Tool to add tools that the flow agent can use to perform its job. Select one of the following options:

A tool is a specific task that a flow agent can perform. The flow 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:

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 flow 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.

Parameters

Configure the parameters that will be collected by the flow 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	Displays the Parameters section in the Node editor. In this section, you can define additional parameters for the tool. The flow 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.

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.

Advanced

Parameter	Type	Description
Condition	CognigyScript	Sets a condition that must be evaluated as true to activate the tool. If false, the flow 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 flow 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 flow agent can’t use the tool.

An MCP tool connects to a remote MCP server to load tools that the flow agent can execute. Fill in the following fields:

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 URL	CognigyScript	Defines the URL of a remote MCP server, for example, `https://my-mcp-server.com/mcp`. The legacy `/sse` endpoint is also supported. Ensure that you connect only to trusted MCP servers.
Timeout (seconds)	Slider	Sets the timeout for the MCP connection in seconds. The default is 12 seconds. The range is 1–30 seconds.

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 flow 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.

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. This parameter shows whether tools were loaded from the cache or directly from the MCP server.
Debug with Parameters	Toggle	Appears when Debug loaded Tools is active. Includes the tool parameters in the Debug loaded Tools message. This parameter is inactive by default.
Debug calling Tool	Toggle	Outputs a debug message with detailed information about the tool call each time it is triggered. This parameter is active by default.

Advanced

Parameter	Type	Description
Cache Tools	Toggle	Caches loaded tools. Deactivate this parameter while developing. Ensure that caching is enabled in production for performance reasons. The caching time is 10 minutes. In 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 section.
Condition	CognigyScript	Sets a condition that must be evaluated as true to activate the MCP tool. If false, the flow 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 flow 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 flow 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 flow agent. The recommended maximum number of tools is 20. The following video shows an MCP Tool example:

An A2A Agent tool connects to a remote A2A agent through the open Agent2Agent (A2A) protocol and uses it as a single tool. Cognigy automatically creates a Call A2A Flow Agent Node, labeled Call an A2A Agent, below the A2A Agent Node to execute the call. Fill in the following fields:

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.
Test Connection	Button	Tests the connection and verifies that the remote Agent Card can be retrieved.
Timeout (seconds)	Slider	Sets the timeout in seconds for each request to the remote agent: Agent Card discovery, sending the message, and, in Non-blocking mode, each poll. 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 (poll until complete) — 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 Flow Agent node can call this tool autonomously during one turn. Ranges from 1 to 10. The default value is `4`.

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.

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.

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.
Custom Agent Card Path	CognigyScript	Overrides the default Agent Card discovery path. When you set a path, Cognigy uses only this path. When the field is empty, Cognigy tries `.well-known/agent-card.json` first, and then the legacy `.well-known/agent.json`.
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.

Use the Call A2A Flow 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 Flow Agent node. The node also sends the status message Delegating to <tool name>... automatically, but only to clients connected through the A2A Server channel.

Call A2A flow agent

Parameter	Type	Description
Resolve Immediately	Toggle	Immediately returns the full result to the Flow Agent node as the tool answer. This parameter is active by default.

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.

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.

A Knowledge tool is a tool that allows the flow agent to directly access Knowledge Stores to provide context-aware responses. Fill in the following fields:

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 flow 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.`

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.

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 flow 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 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 flow 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 flow 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 flow agent can’t use the tool.

The Send Email tool lets your flow agent send emails directly to users. The Send Email tool has the capabilities and restrictions as the Email Notification Node but is more flexible. While the Email Notification Node sends emails at a fixed step in a Flow, the Send Email tool allows the flow agent to send emails dynamically, based on user input, conversation context, or instructions. This tool makes automation more flexible and minimizes extra Flow steps.

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 flow 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	CognigyScript	A comma-separated list of email addresses to which the email will be sent.

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.

Advanced

Parameter	Type	Description
Condition	CognigyScript	Sets a condition that must be evaluated as true to activate the Send Email tool. If false, the flow 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 flow 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 flow agent can’t use the tool.
CC Email Addresses	CognigyScript	A comma-separated list of email addresses that receive a copy of the email.
BCC Email Addresses	CognigyScript	A comma-separated list of email addresses that receive a blind copy of the email.
Email Priority	List	Sets the priority of the email: high, normal, or low. The default is normal.

The Handover to Flow Agent tool lets you transfer a conversation to another flow agent in the same or a different Flow. This approach ensures that different flow agents share the same conversation context and can handle specific tasks, and that multi-step conversations run smoothly across Flows.

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 Flow Agent tool, the tool ID provides context to trigger the correct Handover to Flow Agent tool. In this case, enter a clear tool ID for each Handover to Flow Agent tool, for example, `handover_to_billing_agent`.
Description	CognigyScript	Defines instructions to guide the flow agent to call the Handover to Flow Agent tool. The description field provides context to trigger the correct receiving flow agent. If you use more than one Handover to Flow Agent tool, enter clear instructions for the cases when each receiving flow agent should take over. For example, `Handle product recommendations`, `Perform technical troubleshooting`, or `Assist with billing questions`.
Target flow agent	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 a Flow Agent node.
Select Node	List	Sets the Flow Agent node to hand over to. The list includes only Flow Agent nodes.

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.

Advanced

Parameter	Type	Description
Condition	CognigyScript	Sets a condition that must be evaluated as true to activate the Handover to Flow Agent tool. If false, the flow agent can’t access the tool during execution. For example, when using the Handover to Flow Agent tool, you can enter a condition like `context.accountStatus === "locked"`. With this condition, the flow 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 flow agent can’t use the tool.

The Handover to Human Agent tool lets you transfer a conversation to a human agent through handover providers. This tool allows your flow agents to refer complex tasks to a human agent if they can’t address the user’s request.

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 flow 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 flow 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: Live Agent Chatwoot Salesforce NiCE CXone Genesys Cloud Open Messaging or Genesys Cloud Guest Chat 8x8 RingCentral Engage
Handover acceptance message	CognigyScript	Defines the message sent to the user when the handover is requested.
Repeat handover acceptance message	Toggle	Repeatedly outputs the text in Handover acceptance message if the user sends a message while waiting in the queue for an agent.

Cancel options

Parameter	Type	Description
Cancel intent	CognigyScript	Defines the intent the user must trigger to cancel the handover request.
Cancel button label	CognigyScript	Defines the text for a quick reply button that cancels the handover request when clicked.

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 flow 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 flow 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 flow agent takes over and continues the Flow. You can select one of the following options to determine where the Flow continues: Next 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. Current agent inject entrypoint — the Flow continues from the Node where the human agent stopped assisting the user.
Send resolve event to 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 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.

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.

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.

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 flow 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 flow 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 flow agent can’t use the tool.

The Execute Workflow tool lets the flow agent execute another Flow. After the target Flow executes, the conversation returns to the flow agent.The target Flow inherits the Context object from the flow agent. If the Context object is changed during the target Flow execution, these changes are also available to the flow agent.How the Execute Workflow tool behaves at runtime

Result returned to the LLM. The tool always answers the LLM with the fixed text Workflow executed. The outputs and results of the target Flow aren’t returned to the LLM as the tool result. To let the flow agent use a result, write it to the Context in the target Flow. Messages from Say Nodes in the target Flow go directly to the user.
execution_reason parameter. The default tool parameters ask the LLM for an execution_reason. It isn’t passed to the target Flow as input. It appears only in the Debug Message when called output, together with the target Flow and Node. Use it as a debugging aid.
Calls through an MCP Server Endpoint. When an MCP client calls the tool, the target Flow runs and the client receives Workflow executed. No flow agent job is involved.
Loop protection. If the LLM keeps calling the same Execute Workflow tool, the tool can run up to four times for one user input. The fifth run stops with an Infinite Loop Detected error.

When the flow agent calls an Execute Workflow tool, the target Flow runs right away, in the same turn, and any messages it sends go straight to the user. When the Flow finishes, the flow agent continues in the same turn and generates its next reply. At that point it sees the tool result Workflow executed and the messages the Flow sent, but no other output from the Flow. If the Flow asks a question or waits for input, the flow agent continues only after the user responds. If the Flow ends with a Stop Node or jumps away with a Go To Node, the flow agent doesn’t continue.To test the tool independently:

Test the target Flow on its own. Open it in the Interaction Panel and start from the selected Entrypoint Node.
Test the tool call through the flow agent with Debug Message when called activated. You can then see execution_reason and the target.

Check that the Context values written by the target Flow are available to the flow agent when it continues in the same turn.

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 flow agent to call the Execute Workflow tool. The description field provides context to trigger the Execute Workflow tool. Describe when the flow 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 flow agent executes when this tool is called. Click to open the target Flow.
Select Node	List	Sets the target Node that the flow agent executes when the target Flow is called. You must set the Node you want to select as an Entrypoint with the Set Entrypoint setting before you can select it.

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.

Advanced

Parameter	Type	Description
Condition	CognigyScript	Sets a condition that must be evaluated as true to activate the Execute Workflow tool. If false, the flow agent can’t access the tool.
Parse Intents	Toggle	Sets whether Intents should be parsed in the target Flow. This parameter is inactive by default. If this parameter is activated, Cognigy NLU reparses the Intents in the target Flow based on `text` in the Input object. 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 inactive by default. If this parameter is activated, Cognigy NLU reparses the Slots in the target Flow based on `text` in the Input object. 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 of the target Flow is used in the context of the Flow the flow agent is currently in. If the default Context of the target Flow has a value, it is copied into the Context object of the flow agent as soon as the target Flow is executed.

Configure flow agent settings for each job

Configure more settings for managing flow agents:

Memory handling

Parameter	Type	Description
Long-Term Memory Injection	List	Allow the flow agent to access Contact Profile information for the current user. Select one of the following options: None – no memory. Inherit from flow agent – use the settings specified in the flow agent creation settings. This option is selected by default. 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 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 flow agent in the current turn.

Grounding knowledge

Parameter	Type	Description
Knowledge Injection	List	Use the Knowledge AI feature for the flow agent. Select one of the following options: Never — don’t use the Knowledge Stores. When Required — let the flow agent decide when querying the Knowledge Stores is required to help the user. On 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 flow agent knowledge	Toggle	This parameter appears when you select either When Required or On each User Input. Enable to use the Knowledge Store configured in the flow agent. The Knowledge Store configured within the flow agent creation settings will be used.
Use Job Knowledge	Toggle	This parameter appears when you select either When Required or On each User Input. Enable this option to configure a specific Knowledge Store for this particular job, allowing the flow agent to access job-specific data or resources.
Job Knowledge Store	List	This parameter appears when you select either When Required or On each User Input. This parameter appears when the Use Job Knowledge option is enabled. Select a specific Knowledge Store for this flow agent’s job.
Top K	Slider	This parameter appears when you select either When Required or On 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 flow agent additional context, but it also increases noise and token usage.
Source Tags	CognigyScript	This parameter appears when you select either When Required or On 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 On 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 On 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 flow agent result in the Input object. To print the result, use the AI Agent Output token or the configured Input key in a Say Node, or enable the Output Responses 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 Responses 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 and Say Node. Store Copy in Input is active by default. When you deactivate it, the result isn’t stored in the Input or the Context. Stream to Output is the default option.
Input Key to store Result	CognigyScript	The parameter appears when you select Store in Input, or when you select Stream to Output and Store Copy in Input is active. The result is stored in the `input.aiAgentOutput` object by default. You can specify another value, but the AI Agent Output token will not work if the value is changed.
Context Key to store Result	CognigyScript	The parameter appears when Store in Context is selected. The result is stored in the `context.aiAgentOutput` object by default. You can specify another key.
Stream Buffer Flush Tokens	Text Array	The parameter appears when Stream to Output is selected. It defines tokens that trigger the stream buffer to flush to the output. The tokens can be punctuation marks or symbols, such as `\n`. The default tokens are `.`, `!`, `?`, and `\n`.
Output Responses 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. This parameter is active by default.
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. This parameter is activated by default.

Voice

The parameters after Voice Setting appear only when Voice Setting is set to Use Job Voice.

Parameter	Type	Description
Voice Setting	Select	Configure the voice settings for the flow agent job. This parameter determines how the flow agent selects the voice for text-to-speech (TTS) output. Select one of the following options: - Inherit from flow agent — use the voice settings defined in the flow agent creation settings. - Use Job Voice – apply custom voice settings specific to this job, allowing the flow agent to adapt to the particular role it performs. For example, if you create a marketing flow agent, the voice can be more engaging, friendly, and persuasive. However, if the same flow 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.
TTS ElevenLabs Model	Dropdown	Appears when ElevenLabs is selected in TTS Vendor. Select the TTS model for ElevenLabs. Each model has specific languages available. The default is `eleven_multilingual_v2`.
TTS OpenAI Model	Dropdown	Appears when OpenAI is selected in TTS Vendor. Select the TTS model for OpenAI: `tts-1`, `tts-1-hd`, or `gpt-4o-mini-tts`. The default is `tts-1`.
Custom (Vendor)	CognigyScript	The Custom parameter appears when you select Custom from the TTS Vendor list. Specify the custom TTS Vendor. For preinstalled providers, use all lowercase letters, for example, `microsoft`, `google`, `aws`. For custom providers, use the name that you specified on the Speech Service page in the Voice Gateway Self-Service Portal.
TTS Language	Dropdown	Define the language of the voice flow 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 flow 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 flow agent output. This parameter allows you to customize the flow agent’s voice by defining its tone, gender, style, and regional specifics, making conversations more personalized and aligned with your brand and target audience.
Custom (Voice)	CognigyScript	The Custom parameter appears when you select Custom from the TTS Voice list. Use this parameter to specify a custom voice, which is often required for region-specific voices. The format depends on the option selected in TTS Vendor and typically follows the pattern `language-region-VoiceName`. For example, `de-DE-ConradNeural` for German (Germany) male voice or `en-US-JennyNeural` for English (US) female voice.
TTS Label	CognigyScript	The alternative name of the TTS vendor is the one you specify in the Voice Gateway Self-Service Portal. If you have created multiple speech services from the same vendor, use the label to specify which service to use.
Disable TTS Audio Caching	Toggle	Disables TTS audio caching. By default, the setting is deactivated. In this case, previously requested TTS audio results are stored in the flow agent cache. When a new TTS request is made and the audio text has been previously requested, the flow agent retrieves the cached result instead of sending another request to the TTS provider. When the setting is activated, the flow agent caches TTS results but doesn’t use them. In this case, each request is directly sent to your speech provider. Note that disabling caching can increase TTS costs. For detailed information, contact your speech provider.

Tool settings

Parameter	Type	Description
Tool Choice	List	If supported by your LLM, determines how the flow agent selects tools: Auto — tools are automatically selected by the flow agent when available and needed. This option is selected by default. Required — your flow agent always uses one of its tools. None — your flow 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.

Image handling

Parameter	Type	Description
Process Images	Toggle	Allows the flow 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. This option is selected by default. Drop — excludes the images. Keep — sends the maximum size (this option consumes more tokens). Limitations and token consumption depend on the LLM used.

Advanced

Parameter	Type	Description
LLM	List	Select a model that supports the Flow Agent node feature. The selected Default model is the model assigned to AI Agents in Manage > AI & Voice Providers > Language Models > Assignments. Select the model that you added earlier while configuring the Agentic AI feature. This model will manage your flow agent.
Flow agent base version	List	Select the base version of the flow agent to use: 1.0 — 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 Flow Agent node are released. Latest — use the most recent version of the Flow 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 flow 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. The default is 8000 ms.
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. The default is 4000, and the range is 100–8000. If your installation has deprecated this parameter, migrate it to Custom Model Options in the Custom Options section.
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. The default is 0.7. If your installation has deprecated this parameter, migrate it to Custom Model Options in the Custom Options section.
Include Rich Media Context	Toggle	Controls whether the text from the Textual Description field in Say, Question, and Optional Questions Nodes is added to the flow agent’s prompt. This text provides flow 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.
Ignore deprecated parameters	Toggle	This parameter appears only if your installation has deprecated the Maximum Completion Tokens and Temperature parameters. Ignores these parameters. This parameter is inactive by default.

Custom options

Parameter	Type	Description
Custom Model Options	JSON	Sends custom options to the LLM. These options override the model options set in the Node. For the available options, refer to the API specification of your LLM provider. The default is `{}`.
Custom Request Options	JSON	Sends custom request options to the LLM provider. The default is `{}`.

Error handling

Parameter	Type	Description
Log to System Logs	Toggle	Logs errors to the system logs. They can be viewed on the Logs page of your Project. This parameter is inactive by default.
Store in Input	Toggle	Store errors in the Input object. This parameter is active by default.
Select Error Handling Approach	List	Sets how Flow execution behaves if the Flow 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.
Go to Node	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 Flow Agent node fails.

Debug settings

Parameter	Type	Description
Log Job Execution	Toggle	Send a debug message with the current flow agent job configuration. The message appears in the Interaction Panel when 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 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 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	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 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 is enabled. This parameter is inactive by default.
Send request logs to Webhook	Toggle	Sends 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. This parameter is inactive by default.
Webhook URL	CognigyScript	This parameter appears when you toggle on Send request logs to Webhook. Sets the URL of the webhook service to send the request logs to. Logging requires a URL.
Custom Logging Data	CognigyScript	This parameter appears when you toggle on Send request logs to Webhook. Sets custom data to send with the request to the webhook service. You can use CognigyScript to reference any value or object.
Condition for Webhook Logging	CognigyScript	This parameter appears when you toggle on Send request logs to Webhook. Sets a condition that controls when Cognigy writes the logs to the webhook. Cognigy logs the request only if the condition is empty or evaluates to true.
Webhook Headers	Input fields	Sets the headers to send with the request to the webhook service. 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. When using the JSON editor, follow the JSON Schema specification.
Log Tool Definitions	Toggle	Sends a debug message containing information about the configured flow agent tools. The message appears in the Interaction Panel when 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 flow agent’s Flow in detail, click Advanced Editor in the upper-right corner.One flow 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.

More information

¹: Note that not all LLMs support streaming.

Getting started

Design

Test

Deploy

Analyze

Advanced

Configure tools for flow agents

Configure flow agent settings for each job

More information

​Configure tools for flow agents

​Configure flow agent settings for each job

​More information

Configure tools for flow agents

Configure flow agent settings for each job

More information