Modules

Modules

Working with an external framework and adapting it to your needs isn’t always simple, especially when you need it to behave in ways its original design didn’t anticipate. Modifying the framework’s source code is a treacherous path—not just because it requires deeper expertise, but also because it leads to divergences between your locally-modified version and upstream updates.

So how do you get a pre-built system to work differently? The idea is to be able to run a system or software that includes your code customizations without breaking its fundamental assumptions.

The Open/Closed Principle states that software should be open for extension, but closed for modification, such that it can allow its behavior to be extended without modifying its source code. Parlant is carefully designed to abide by this principle, allowing you to achieve extreme extensibility by hooking into its structure with custom Modules.

With Modules, you can build and integrate a host of useful functionalities—like optimizing few-shots for engine components, host tool services within the server process, and extend engine behavior using special hook functions—all under one umbrella. This way, you can focus on building exactly what you need without waiting for updates or modifying core engine components.

This is a good time to remind you that you can join our Discord community to ask questions.

What You Can Build with Modules

Here are several key examples of customizations you can implement in your modules:

Tool Services: While for production deployment tool services should be sandboed in their own processes, this is usually a hassle during development. With modules, you can create and run your tool services directly within the Parlant server process, making it easier to rapidly develop and prototype tool services without worrying about managing multiple processes and network ports.

Infrastructure Modifications: Parlant has certain defaults which make development and prototyping easy to start with, but are not necessarily the best choices for production deployment. For example, out of the box, Parlant uses ChromaDB and JSON files for data persistence. You can easily use modules to replace them, like telling Parlant to use MongoDB instead of JSON files.

Few-Shot Optimizations: You can define custom few-shot examples to help your agent’s make sense of your domain and instructions and follow them in accordance with your needs.

Engine Hooks: These allow you to inject custom logic at key strategic moments during the processing pipeline of an agent’s response, like tool calling, message generation, and more.

Optimized Evaluations: If you find that evaluating guidelines and tool calls takes too long, you can override the default general-purpose evaluation mechanism with specialized functions to dramatically reduce cost and response latency.

Module Structure

Modules let you configure and modify Parlant's engine by giving you access to Parlant's Dependency Injection container. Each module has 3 possible hooks you can define:

1) Configuration

Configuration is used, in some modules, to override Parlant's engine components. For example, you can use this to replace storage backends, or decorate and hook into core engine components.

async def configure_module(container: Container) -> Container:
    ...

2) Initialization

At the initialization stage, the configured components (and the container itself) are initialized and ready to work with. Many components in Parlant are customizable once initialized.

async def initialize_module(container: Container) -> None:
    ...

3) Shutdown

This hook is a good place to perform graceful shutdown, such as flushing storage, closing sockets, sending shutdown signals to monitoring processes, etc.

async def shutdown_module() -> None:
    ...

Working with Modules

You can easily generate a new module based on templates using parlant-server's module create command. Take a moment to explore it and the built-in templates you can utilize.

parlant-server module create --help

To learn how to list and enable or disable modules, run:

parlant-server module --help