Tool Service Setup

A tool service allows you to connect external APIs to Parlant so that your agents can dynamically fetch data and take action in the real world.

Generally speaking, you can connect multiple tool services to Parlant, such that each service is responsible for some external system. For example, you could connect a calendar service, or a payment service.

For our purposes, we'll build a tool that fetches product data from a database. We’ll support the scenario where a customer needs help choosing laptops. Our agent will help clarify the customer's needs, and recommend the most relevant products.

Creating a Tool Service

To get started, we need to create a new server module—a place where we can write custom code that'll load into our Parlant server. We'll use a tool-service module template to make things easy.

parlant-server module create --template tool-service retail

This should create the file retail.py in the current directory. Additionally, the command added the service to ./parlant.toml, where auto-loaded modules are listed. Whenever you start parlant-server, it looks to check if there's a parlant.toml file in the current directory, and automatically loads the module specified in it.

Adding Your Database

For the sake of this tutorial, we'll represent our database as a simple JSON file containing product details such as type, description, tags, quantities, and prices. Here’s an example of the structure we'll use:

[
  {
    "title": "MSI MPG Z690 Edge WiFi DDR4",
    "type": "Motherboard",
    "vendor": "MSI",
    "description": "Intel Z690 chipset motherboard with PCIe 5.0, WiFi 6E, and robust power delivery.",
    "tags": [ "intel", "z690", "wifi", "gaming"],
    "qty": 18,
    "price": 279.99
  },
 ...
]

To help you get started quickly, we've prepared a JSON file of 100 products.

curl -o products.json https://www.parlant.io/files/products.json

Your tree should now look like this:

parlant-tutorial/
├── parlant-data
├── retail.py
└── products.json

With this boilerplate set up, we're now ready to code our tool's logic!