Skip to main content

Module Imports and Dependencies

A module can use code from other modules in your tenant. This lets you keep a shared helper, such as an API client, in one module and import it from every module that needs it, instead of copying the file into each one.

Two settings control how this works:

  • Isolated module — a module setting that decides where the module's files are placed when an agent starts, and therefore how other code imports them.
  • Dependencies — the list of other modules this module imports code from.

Both are on the Functions stage of the tool builder. See Create a tool for the builder itself.

The layouts and import forms on this page apply to tools that are connected to an agent directly. Tools that reach an agent only through a skill are deployed differently. See Tools in skills.

Choose isolated or shared folder​

The Isolated module switch sits under the module name. The tool builder lists the import rules for the current choice right below the switch.

Isolated module onIsolated module off (shared folder)
Where the files goThe module's own folder, named after the moduleA folder shared with the agent's other non-isolated modules
Other modules import it asfrom <module_name>.<file> import ...from <file> import ...
Files inside the module import each other asfrom .<file> import ...from <file> import ...
File name clashesFiles never clash with files of other modulesA file with the same name but different content in another non-isolated module stops the agent from starting

New modules start with Isolated module on. Existing modules keep the layout they were saved with until you change it.

Use isolated modules for new code. Turn the switch off only when the code already imports its own files by their bare names (from helper import ...) and you don't want to change it.

Module names

A module name must be a valid Python identifier that isn't a Python keyword, whether the module is isolated or uses the shared folder: letters, digits, and underscores, not starting with a digit. For example, crm_utils works. Names such as CRM utils, crm-utils, or class are rejected when you save, with the message Module name "…" is not a valid Python identifier. For an isolated module the name matters twice, because other code imports the module by it.

Change the layout of an existing module​

When you change the switch on a module that's already saved, the tool builder shows a warning that modules depending on this one stop importing it until their code is updated.

Before you save the change, update the imports in every module that depends on this one. Renaming an isolated module has the same effect, because the module name is part of the import.

Add a dependency​

  1. Open the module in the tool builder and go to the Functions stage.
  2. In the Dependencies card, click Add dependencies.
  3. In the Add dependency dialog, search for and select one or more modules, and then click Add.
  4. In your code, import the dependency according to its layout, not the layout of the module you're editing:
    • Isolated dependency: from <dependency_name>.<file> import ...
    • Shared-folder dependency: from <file> import ...
  5. Save the module.

Each dependency card shows the version of the module it records.

To remove a dependency, click the remove icon on its card in the Dependencies list, and then click Remove in the confirmation.

Example​

Module crm_utils is isolated and contains client.py with a get_customer function. Module orders adds crm_utils as a dependency and imports the function:

from crm_utils.client import get_customer

If crm_utils used the shared folder instead, the import would be:

from client import get_customer

Inside crm_utils, another file imports client.py with a relative import:

from .client import get_customer

How it works​

  • When an agent starts, its tools' modules are deployed together with their dependencies, including the dependencies of those dependencies. You don't have to connect any tool of a dependency to the agent.
  • Data files (for example spreadsheets, templates, or images) are placed in the agent's resources folder by file name, whatever the module's layout.
  • Dependencies can't form a cycle. If module A depends on B, B can't depend on A, directly or through other modules — saving such a module fails with a Circular module dependency error that lists the cycle.

Tools in skills​

A tool that reaches an agent only through a skill is deployed into the skill's own folder, and the module's layout isn't applied there: the module files and the files of its dependencies are copied flat, and the tool is registered by file name alone. In that deployment, imports from another module don't resolve, whether the dependency is isolated or uses the shared folder, and relative imports inside an isolated module fail too.

If a skill's tool needs code from another module, test the skill in the Playground before you rely on it.

Check imports before you save​

The Errors and alerts panel checks imports against the layout of the module and of each dependency. Typical messages:

  • Import '…' looks like it should be 'from … import ...' — the dependency is isolated, but the code imports its file by bare name. Add the module name in front of the file.
  • Import '…' won't resolve — module '…' is a declared dependency but is not deployed as a package (flat layout) — the dependency uses the shared folder, but the code imports it by module name. Import its files directly.
  • Import '…' won't resolve — this module is deployed as a package; use 'from . import …' instead — in an isolated module, one file imports another by bare name. Use from . import <file> or from .<file> import ...; both work in an isolated module.
  • Relative import '…' cannot resolve — a relative import in a shared-folder module. Import the file by its bare name, or turn on Isolated module.

Common issues​

  • Tools fail with an import error after you changed Isolated module on a module. Modules that depend on it still use the old import form. Update their imports as shown in Add a dependency and save them.
  • The agent won't start, with "File '…' is defined differently by modules: …". Two non-isolated modules connected to the same agent contain a file with the same name but different content. Turn on Isolated module for one of them, or rename the file, and update the imports.

Was this article helpful?