> ## 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. # Extensions > Extend Cognigy Flows with custom Nodes, third-party API integrations, and Knowledge Connectors via Extensions. [Updated in 2026.21](https://docs-classic.cognigy.com/release-notes/2026.21.md) *Extensions* in Cognigy are packages that enhance your Flows with additional capabilities. An Extension can include *Extension Nodes*, *Knowledge Connectors*, or both. * [Extension Nodes](#extension-nodes) let you: * Integrate with third-party APIs. * Run custom logic for lightweight operations. * Build convenience nodes using npm modules. * [Knowledge Connectors](#knowledge) let you: * Import documents or data as [Knowledge Sources](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-source/overview). * Improve AI Agents' RAG capabilities. You can install Extensions from the [Marketplace](https://www.cognigy.com/marketplace#/), develop your [custom Extensions](#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 Helm Chart](https://github.com/Cognigy/cognigy-ai-helm-chart/blob/main/values.yaml). * 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](#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](#extension-runtime) is cleaned up after 15 minutes of inactivity. ## Working with Extensions > [tab] GUI > > In **Manage > Extensions**, you can install, update, and uninstall Extensions from the Marketplace or [custom Extensions](#custom-extensions). > > The Extension Marketplace is also available on [Cognigy's website](https://www.cognigy.com/marketplace#/). > [tab] CLI > > You can pull Extensions using the [Cognigy CLI](https://github.com/Cognigy/cognigy-cli). > [tab] API > > You can view, delete, upload, and update Extensions using the [Cognigy API](https://api-trial.cognigy.ai/openapi#tag--Extensions-v2.0). ### Extension Nodes You can add Extension Nodes to your Flows in the [Flow editor](https://docs-classic.cognigy.com/ai/agents/develop/projects-and-flows/editor.md). ### Knowledge Connectors [Knowledge Connectors](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-connectors.md) allow you to import Knowledge Sources from external knowledge databases to a [Knowledge Store](https://docs-classic.cognigy.com/ai/agents/develop/knowledge-ai/knowledge-store.md) and schedule regular knowledge imports in **Build > Knowledge**. ### Custom Extensions Cognigy allows anyone to extend its capabilities 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**. ### Extension Dependencies If you don't build the dependencies of your Extension and list them only in the `package.json` and `package-lock.json` files, Cognigy installs the dependencies from the official sources when you upload the Extension. If your Extension contains a `node_modules` folder, Cognigy copies it to the target file storage instead. ### Best Practices for Developing Custom Extensions Extensions are designed for lightweight operations. Follow these best practices: > [accordion] Best Practices > > | Practice | Description | > | - | - | > | Keep Extensions lean | Strip 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 limit | Design your Extension to: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 singletons | Initialize HTTP clients, database connections, or configuration objects at the module's top level. This approach is efficient because these resources are initialized once at startup and reused for all subsequent warm executions. | > | Scope execution data | Avoid 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 explicitly | Wrap 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 memory | Use 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 externally | Store 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 a period of inactivity or upon redeployment. | > | Comply with the object size limit | Validate argument [sizes](#limitations) 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. > [accordion] Develop Custom Extensions > > The following materials provide in-depth information on developing a custom Extension: > > * [Readme](https://www.npmjs.com/package/@cognigy/extension-tools) of the `@cognigy/extension-tools` package for requirements. > > * [Cognigy Sessions Episode](https://support.cognigy.com/hc/en-us/articles/360019893139-Cognigy-Sessions-Extensions) about Extensions for a technical deep dive. > > * An [Extension Node](https://github.com/Cognigy/Extensions/tree/master/docs/example/src/nodes) example that shows how to build an Extension Node. > > * A [Knowledge Connector](https://github.com/Cognigy/Extensions/blob/master/docs/example/src/knowledge-connectors/simpleKnowledgeConnector.ts) example that shows how to build a Knowledge Connector. > > * [GitHub repository](https://github.com/Cognigy/Extensions/tree/master/extensions) for more Extension examples. > > > [!TIP] > > > > [Cognigy Hammer](https://github.com/tgbv/cognigy-hammer/), created by the Cognigy community, is an Extension development suite designed for Cognigy. Cognigy Hammer offers several tools and features to assist in the development of Cognigy Extensions. Note that Cognigy Hammer isn't a Cognigy product and doesn't qualify for enterprise support. > > **Best practices for developing custom Extensions** > > To guarantee the [performance](#execution-performance-and-security) 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** > > ```javascript theme={null} > 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'); > } > } > ``` > [accordion] Publish Custom Extensions > > If you want to publish a custom Extension on the Marketplace, follow the approval procedure in the [Extensions GitHub repository](https://github.com/Cognigy/Extensions). ## Execution, Performance, and Security ### Extension Runtime The Extension runtime, known as Cognigy Serverless in earlier releases, is the execution runtime for all Marketplace and [custom Extensions](#custom-extensions). Each organization has an isolated environment for Extensions that is created on demand and automatically cleaned up after a period of inactivity. Most Extensions run on the Extension runtime without changes, and the [Extension API functions](https://docs-classic.cognigy.com/ai/for-developers/code/api-functions.md) work the same way. If an Extension fails, it probably uses a pattern that the Extension runtime doesn't support. For the cause and the fix, see [Unsupported Extension Design Patterns](#unsupported-extension-design-patterns). > [!WARNING] > > Starting with Cognigy 2026.21.0, the Extension runtime is required. All uploaded Extension Nodes always run on the Extension runtime. > > * **SaaS installations**. Cognigy performed the migration for you. No action is required. > * **On-premises installations**. [Install the Extension runtime](https://docs-classic.cognigy.com/ai/administer/installation/serverless-installation) before upgrading to 2026.21.0. Otherwise, all Extensions will stop working after the upgrade. Extensions must also use tenant-scoped storage. Extensions still stored in the legacy layout fail to upgrade and return an error asking you to re-upload them. Re-upload affected Extensions in **Manage > Extensions** to restore them. For the migration steps, see [Migrate Extensions Tenant Storage](https://docs-classic.cognigy.com/ai/administer/installation/migration/extensions-tenant-storage-migration). #### Unsupported Extension Design Patterns Specific Extension design patterns may have unintentionally worked in the previous runtime. The Extension runtime makes sure that previous Extension limitations are enforced to guarantee performance and security. > [accordion] Unsupported Patterns > > | Pattern | Reason for failure | Recommended alternative | > | - | - | - | > | Writing to the local filesystem | Read-only filesystem | Use external storage on a public IP address. | > | Connecting to services on private IP address ranges | Blocked private network access | Use a publicly accessible endpoint or a SaaS equivalent. | > | Storing data permanently in module-level variables | The environment is cleaned up after 15 minutes of inactivity. | Write to an external database or storage service. | > | Accessing internal Cognigy services directly over HTTP | Blocked private network access | Use [Cognigy API functions](https://docs-classic.cognigy.com/ai/for-developers/code/api-functions.md). | > | Installing npm packages dynamically at runtime | Package 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. | #### Reuse Connections and Clients In the Extension runtime, your Extension module can stay loaded between executions, and module-scoped objects are created once and reused across executions until a cold start recreates them. Function-scoped objects are recreated on every execution regardless. Using module-scoped objects improves Extension execution speed and reduces outbound network resource consumption. Create HTTP, SDK, and authentication clients once at the module level and reuse them across executions. For example: > [accordion] Example: Module-scoped HTTP Client > > ```typescript theme={null} > // Module scope: created once, reused across executions > const client = axios.create({ timeout: 10_000 }); > > export const myNode = createNodeDescriptor({ > // ... > function: async ({ cognigy, config }) => { > // Reuses the client and its open connections > const response = await client.get(`${config.connection.baseUrl}/data`); > }, > }); > ``` The execution environment reuses network connections automatically: HTTP clients that don't configure their own agent — the default `axios` instance, `axios.create()` without an `httpsAgent`, plain `https.request`, and native `fetch` — share a managed keep-alive connection pool, so consecutive executions reuse open connections instead of paying a TCP connection and TLS handshake per call. You don't need a custom `https.Agent` for connection reuse. Module-scoped clients still matter for everything the connection pool can't cover: recreating an SDK or authentication client on every execution discards its internal caches and often adds an authentication round trip to every call. When a client depends on Connection fields, such as credentials, cache one client instance per Connection at module scope, keyed by a stable identifier like the client ID. Reusing authentication clients lets their internal token caches work. With this approach, most Extension executions don't need to fetch a new token. For reliable outbound calls, follow these rules: * Set an explicit timeout for every outbound request, well below the Extension execution timeout. Without a request timeout, error handling never runs when a server doesn't respond; instead, the platform stops execution. * Never create an HTTP agent or client inside the node's `function`. A new agent can't reuse connections from previous executions, so every call incurs the cost of a new connection. The discarded agent's open connections also aren't closed. They stay open until the environment recycles, consuming outbound connection capacity shared across all executions. * If you configure your own `https.Agent` (for example, for custom TLS options), set `keepAlive: true`, create it at module scope, and keep its idle socket timeout at 2 minutes or below. Cloud load balancers silently drop connections that remain idle for extended periods. * Treat module scope as a cache, not as storage. The environment is cleaned up after a period of inactivity. Cached clients are simply recreated on the next execution. Don't store business data in the cache. For more details, see [Unsupported Extension Design Patterns](#unsupported-extension-design-patterns). ## 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. ## 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](https://www.npmjs.com/package/@cognigy/extension-tools#extension-localization) documentation. ## Error Handling If an Extension [times out or sends too many API calls](#limitations), the Flow execution doesn't stop. Instead, an error message is written to the `input.extensionError` Input object. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.