- Integrate with third-party APIs.
- Execute custom logic for lightweight operations.
- Create convenience Nodes using various NPM modules.
Limitations
- Extensions have a default 20-second timeout. You can change the timeout by doing the following:
- For dedicated SaaS installations, contact Cognigy technical support to change the timeout.
- For on-premises installations, change the environment variable as described in the Cognigy.AI Helm Chart.
- Extensions can make up to 10 API calls per execution.
Working with Extensions
- GUI
- CLI
- API
In Manage > Extensions, you can install, update, and uninstall Extensions from the Marketplace or custom Extensions. Also, you can mark your custom Extensions as trusted.The Extension Marketplace is also available on Cognigy’s website.
Custom Extensions
Cognigy allows anyone to extend the capabilities of Cognigy.AI by developing their own Extensions. Custom Extensions are JavaScript or TypeScript modules that you can use as Nodes. After developing a custom Extension, you can install it by uploading it in Manage > Extensions. Extensions are designed for lightweight operations. When developing a custom Extension, avoid implementing CPU-intensive computations, high memory operations, or large loops in the Extensions code, or code issues, for example, that lead to infinite loops or unresolved promises. These practices can impact the performance of your AI Agents. Additionally, you can publish your custom Extension on the Marketplace so that other Cognigy users have access to it.Develop Custom Extensions
Develop Custom Extensions
The following materials will provide you with in-depth information to develop a custom Extension:Best Practices for Developing Custom ExtensionsTo guarantee the performance of a custom Extension, make sure the Extension code:
- Readme of the
@cognigy/extension-tools
package for requirements. - Get Started documentation for the first steps.
- Cognigy Sessions Episode about Extensions for a technical deep dive.
- GitHub repository for Extensions examples.
Cognigy Hammer, created by the Cognigy community, is an Extension development suite designed for Cognigy.AI. Cognigy Hammer offers several tools and features to assist in the development of Cognigy Extensions. Note that Cognigy Hammer isn’t a product of Cognigy and doesn’t qualify for enterprise support.
- Undergoes review by experienced developers.
- Avoids handling very complex logic and use cases.
- Is tested both independently and in Flows before production rollout.
- Provides error handling across all potential error cases, for example, with try/catch blocks and by resolving promises.
Publish Custom Extensions
Publish Custom Extensions
If you want to publish a custom Extension on the Marketplace, follow the approval procedure in the Extensions GitHub repository.
Extension Performance and Security
- Executing the Extension code in a separate microservice. This approach ensures that, in a worst-case scenario, a breakout affects only the dedicated microservice, but not the rest of the system.
- Using a dedicated child process that the system spawns for each execution of the Extension code within the separate microservice. This approach ensures that the Extension code can access only a defined set of environment variables and allows Cognigy.AI to terminate this code if it runs for too long.
- Creating a separate JavaScript virtual machine within the child process in which the Extension code is executed. This approach restricts usability of certain APIs from the underlying Node.js execution context, limiting what the code can do when running on the Cognigy.AI infrastructure.
Make Extensions Trusted
Never trust Extension code without thorough review. Extensions can use external packages from NPM, which may contain malicious code or routines. An Extension can steal sensitive information when executed in the standard environment.
Make Extensions Trusted
Make Extensions Trusted
- Mark an Extension as trusted in Manage > Extensions. Trusted Extensions display the
icon. Only admins and users with the
extension_trust_admin
role can mark Extensions as trusted and update them. - For dedicated SaaS or on-premises installations:
- Set the
FEATURE_ALLOW_TRUSTED_CODE_CONFIGURATION
environment variable totrue
by adding the following code to yourconfig-map_patch.yaml
in thekubernetes
repository where the deployment manifest files are stored:
- Use the Cognigy.AI API PATCH request to update the
trustedCode
property of an Extension.
- Set the
Install Extensions for All Organizations
On-premises customers can install Extensions in all organizations of their installation. To do so, add theFEATURE_ADDITIONAL_SYSTEM_WIDE_EXTENSIONS_PATH
environment variable to values.yaml
under the cognigyEnv
mapping key and enter the path to the Extension.
Cache Extensions in your Local Directory
You can cache Extensions in your local directory to improve the Extensions’ loading performance.Maximum cache storage
Maximum cache storage
By default, when Extensions exceed the maximum cache directory size, the last 10 Extensions are removed from the local directory. On premises and dedicated SaaS customers can change the number of Extensions that are removed when the maximum cache directory size is exceeded using the
EXCEED_DIR_SIZE_AMOUNT_TO_DROP_FROM_MAP
environment variable.On-premises and dedicated SaaS customers can change the maximum directory size by adding the MAX_EXTENSIONS_CACHE_DIR_SIZE_IN_MB
environment variable to values.yaml
. By default, the maximum directory size is 512 MB.The cache is in the service-execution
Kubernetes pod.Dynamic Fields
You can use a dynamic selection field as a field type in Extensions. This feature can be used to dynamically fetch the content of a selection field, for example, through an external API call.Localization for Extensions
Extension builders can include localized UI texts, such as default Node labels or Node field descriptions. For more details, read the Localization for Extensions documentation.Error Handling
If an Extension times out or sends too many API calls, the Flow execution doesn’t stop. Instead, an error message is written to theinput.extensionError
Input object.