Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt

Use this file to discover all available pages before exploring further.

Updated in 2026.9 Extensions in Cognigy.AI are packages that enhance your Flows with additional capabilities. An Extension can include Extension Nodes, Knowledge Connectors, or both.
  • Extension Nodes let you:
    • Integrate with third-party APIs.
    • Run custom logic for lightweight operations.
    • Build convenience nodes using npm modules.
  • Knowledge Connectors let you:
    • Import documents or data as Knowledge Sources.
    • Improve AI Agents’ RAG capabilities.
You can install Extensions from the Marketplace, develop your custom Extensions, or modify existing ones.

​
Limitations

  • Extensions have a default 20-second timeout. You can 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, except for api.log(). For more details, see the Best Practices for Developing Custom Extensions.
  • By default, objects passed as arguments to Extension API calls have a size limit of 62 KB.
  • The Extension runtime environment is cleaned up after 15 minutes of inactivity.

​
Working with Extensions

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.

​
Extension Nodes

You can add Extension Nodes to your Flows in the Flow editor.

​
Knowledge Connectors

Knowledge Connectors allow you to import Knowledge Sources from external knowledge databases to a Knowledge Store and schedule regular knowledge import in Build > Knowledge.

​
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 to create fully customized Extension Nodes and Knowledge Connectors. After developing a custom Extension, you can install it by uploading it in Manage > Extensions.

​
Best Practices for Developing Custom Extensions

Extensions are designed for lightweight operations. Follow these best practices:
PracticeDescription
Keep Extensions leanStrip development dependencies before packaging. Run either npm ci --omit=dev or npm ci --production. Development dependencies, such as test frameworks, type definitions, linters, and bundlers, increase startup time, consume memory for the lifetime of the running environment, and increase overhead on every execution, even when the Extension is warm.

Heavy Extensions increase costs on cold start, under concurrent load, and in memory-constrained environments.
Comply with the API call limitDesign your Extension to:
  • Manage its functionality with a buffer below the limits.
  • Compute values locally.
  • Consolidate writes whenever possible.
For example, instead of calling addToContext() three times for three keys, build the object containing the three keys locally, and pass it once in a single API call.

The api.log() function has no call limit but should still be used at appropriate log levels instead of on every variable.
Use module-level singletonsInitialize HTTP clients, database connections, or configuration objects at the module’s top level. This approach is efficient, because these resources are initialized once on startup and are reused for all subsequent warm executions.
Scope execution dataAvoid storing mutable data related to a single execution at the module level. Sharing data related to a single execution across concurrent executions can lead to unintended data sharing and bugs. Examples of such data include user input, context values, and execution results. Create and store such data inside the Extension Node function instead.
Handle errors explicitlyWrap external calls and async operations in try/catch blocks and expose meaningful errors with api.log() or by writing them to the Context object.

Unhandled exceptions don’t crash the execution environment. The runtime catches unhandled exceptions and returns an error to the calling Flow. However, the Flow doesn’t receive any output, and the execution counts against the timeout budget.
Store temporary data in memoryUse in-memory variables for temporary data within a single execution. The filesystem is read-only. fs.writeFile(), fs.mkdir(), and similar operations will throw an error at runtime.
Store persistent data externallyStore critical data in an external store, such as a database or file storage. Data in module-level variables persists only while the execution environment is active. After 15 minutes of inactivity, or on redeployment, the environment is cleaned up. Critical data stored in module-level variables is lost after the inactivity period or on redeployment.
Comply with the object size limitValidate argument sizes before your Extension passes large payloads (for example, document content, API responses, or arrays) to API methods or Context objects. Alternatively, split data across smaller keys.

​
Publish Custom Extensions

Additionally, you can publish your custom Extension on the Marketplace so other Cognigy users can access it.
The following materials provide in-depth information on developing a custom Extension:
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.
Best practices for developing custom ExtensionsTo guarantee the performance of a custom Extension, make sure the Extension code:
  • Undergoes review by experienced developers.
  • Avoids very complex logic and use cases. Keep Extensions small in size and with few Nodes, for example, fewer than 20.
  • Contains only production- or runtime-relevant dependencies in the final build.
  • Is tested both independently and in Flows before production rollout.
  • Provides error handling across all potential error cases, for example, using try/catch blocks and resolving promises.
Code Example for Error Handling
function: async ({ cognigy, config }) => {
    const { api } = cognigy;
    const { contextKey, inputKey } = config;

    const endpoint = `API_TO_CALL`;

    try {
        const result = await axios.get(endpoint);

        // store in context
        api.addToContext(contextKey, result.data, 'simple');

        // store in input 
        api.addToInput(inputKey, result.data);
    }
    catch (error) {
        api.addToContext(contextKey, { error: error.message }, 'simple');
    }
}
If you want to publish a custom Extension on the Marketplace, follow the approval procedure in the Extensions GitHub repository.

​
Execution, Performance, and Security

Before Cognigy.AI 2026.9.0, all Extension code was considered untrusted and was executed in a secure, isolated environment. This additional security layer introduced some overhead during startup. As a result, Extensions typically ran slower than default Nodes in Flows. However, you could still mark Extensions as trusted to execute them in the trusted environment. After Cognigy.AI 2026.9.0, all organizations will be gradually migrated to a more modern, unified execution runtime for all Extensions, called Cognigy Serverless. This new runtime provides high security, stability, and execution isolation for all Extensions. Additionally, Cognigy Serverlesse provides a significant performance boost for both all Extensions. Extension API functions are unchanged, and Extensions are expected to continue working as before. In rare cases, Extensions relying on nonstandard or unintended runtime behaviors, may have their execution blocked under the new service. For more details, see Unsupported Extension Design Patterns. The migration to Cognigy Serverless starts with the release of Cognigy.AI 2026.9 for Cognigy SaaS installations. The migration is performed in the background and users don’t need to take any action.

​
Cognigy Serverless

This feature is in beta. We encourage you to provide us with feedback on the performance of your Extensions.
Cognigy Serverless is the execution runtime that powers all Marketplace and custom Extensions with further enhanced security for the AI era, stability, and execution isolation. In this runtime, each organization has an isolated environment for Extensions that is created on demand and automatically cleaned up after a period of inactivity. This approach provides consistent behavior and strong isolation across all organization environments.

​
Unsupported Extension Design Patterns

Specific Extension design patterns may have unintentionally worked in the previous runtime. Cognigy Serverless makes sure that previous Extension limitations are enforced to guarantee performance and security.
PatternReason for failureRecommended alternative
Writing to the local filesystemRead-only filesystemUse external storage on a public IP address.
Connecting to services on private IP address rangesBlocked private network accessUse a publicly accessible endpoint or a SaaS equivalent.
Storing data permanently in module-level variablesThe environment is cleaned up after 15 minutes of inactivity.Write to an external database or storage service.
Accessing internal Cognigy services directly over HTTPBlocked private network accessUse Cognigy.AI API functions.
Installing npm packages dynamically at runtimePackage managers and filesystem write access aren’t available in the execution environment.Include all dependencies in package.json before uploading the Extension.
Spawning child processes (child_process.spawn, exec)Shell access and system binaries aren’t available in the execution environment.Implement the logic natively in Node.js.

​
Make Extensions Trusted

Never trust Extension code without thorough review. Extensions can use external npm packages, which may contain malicious code or routines. An Extension can expose sensitive information when executed in the standard environment.
A trusted Extension is considered safe to run in the standard environment. This means that trusted Extensions may offer lower latency but need to be handled more carefully to avoid performance issues. To make Extensions trusted and let them run in the standard environment, you have two options:
  • Mark an Extension as trusted in Manage > Extensions. Trusted Extensions display the trust-extensions icon. Only admins and users with the extension_trust_admin role can mark Extensions as trusted and update them.
  • For on-premises installations:
    1. Set the FEATURE_ALLOW_TRUSTED_CODE_CONFIGURATION environment variable to true by adding the following code to your config-map_patch.yaml in the kubernetes repository where the deployment manifest files are stored:
    - op: add
  path: /data/FEATURE_ALLOW_TRUSTED_CODE_CONFIGURATION
  value: "true"
    1. Use the Cognigy.AI API PATCH request to update the trustedCode property of an Extension.

​
Install Extensions for All Organizations

On-premises customers can install Extensions across all organizations in their installation. To do so, add the FEATURE_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 loading performance.
By default, when Extensions exceed the maximum cache directory size, the last 10 Extensions are removed from the local directory. On-premises 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 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. You can use this feature 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 text, 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 the input.extensionError Input object.