Implementing Tools

Our goal is to enable the agent to handle customer inquiries about product categories in the store. When a customer asks about products in a certain category, the agent will first check that we indeed have products in that category, and, if so, ask about specific needs before recommending specific products.

Implementing the Tool Service

Now that we know what we need to accomplish, let's build it.

Edit the tool service module retail.py and add the following code:

with open("products.json") as file:
    database = json.load(file)

class ProductType(Enum):
    MONITOR = "Monitor"
    KEYBOARD = "Keyboard"
    MOUSE = "Mouse"
    HEADSET = "Headset"
    AUDIO = "Audio"
    LAPTOP = "Laptop"
    OTHER = "Other"

@tool
async def get_products_by_type(context: ToolContext, product_type: ProductType) -> ToolResult:
    """Get all products that match the specified product type"""
    products = [item for item in database if item['type'] == product_type.value]
    return ToolResult({"available_products": products})

In the same file, look for the global variable TOOLS which defines the tools your service exports, add your new tool to the list. You can remove its sample greet_person tool while you're at it, to get:

TOOLS = [get_products_by_type]

Argument Classification

Notice how we've used an Enum class with all the product types that we wish to support. Every time a customer inquires about any category, Parlant will automatically classify the query to the most relevant term in our Enum.

While an Enum represents a static, hard-coded list of choices, Parlant also allows you to provide a dynamic list. Read up on ToolParameterOptions or jump on our Discord server to get help.

Create The Guideline

In Parlant, tools are always run in the context of specific matched guidelines. This inherently associated guidance helps to ensure that they're run at the right time, and for the right reasons.

Hence our next step is to create some guidelines to tell our agent how to approach our scenario (where the customer needs help choosing a product) and enable our tool for those guidelines.

First, let's tell Chip to ensure that we have this product in stock:

parlant guideline create \
  --condition "the customer is interested in a product" \
  --action "ensure we carry this type of product; if not, tell them we don't" \
  --tag retail

Now let's associate our tool with the guideline we just created:

parlant guideline tool-enable --id <guideline ID> --service retail --tool get_products_by_type

Second, let's make Chip more proactively helpful when a customer doesn't know what to choose:

parlant guideline create \
  --condition "customer is interested in a product type but didn't choose a specific product" \
  --action "help the customer clarify their needs and preferences" \
  --tag retail

(For this guideline we don't have to enable our tool—it only guides Chip's approach to the situation)

Lastly, recommend products based on needs:

parlant guideline create \
  --condition "customer said what product they want as well as their needs" \
  --action "recommend the best fit out of what we have available" \
  --tag retail

parlant guideline tool-enable --id <guideline ID> --service retail --tool get_products_by_type

Voila! Chip can now search the store's database for any product and assist the customer find the right product for them. You can see how much careful control you have over its behavior, and you can easily adjust it if you see Chip doing something in a sub-optimal way.

You can add more guidelines freely: Parlant will ensure the underlying LLM's attention stays focused and grounded by matching only the relevant elements of your conversation model to each conversation at each point, and it will enforce their application to the conversation according to your intention.

Now let's give Chip a spin. Head over to http://localhost:8800 and enjoy the fruits of your work!

What Next?

We invite you to peruse our Concepts docs to better understand how Parlant works and its vast feature set to learn how to make the best use of it.