Completing the Tool Service

Tool Service Overview

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

Implementing the Tool Service

Now that you've got the grasp of how we need to build our tool service, let's build it!

Edit parlant_tool_service_starter/service.py:

import asyncio
from enum import Enum
import json

from parlant.sdk import (
    PluginServer,
    ToolContext,
    ToolResult,
    tool,
)

with open("products.json", 'r') 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})

TOOLS = [
    get_products_by_type
]

async def main() -> None:
    async with PluginServer(tools=TOOLS, port=8089):
        pass

if __name__ == "__main__":
    asyncio.run(main())

info

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.

Integrating Our Tool Service

Now that our code is ready, the next step is to give Parlant agents access to it by registering it on the server.

Make sure the Parlant server is running, then run:

$ parlant service create \
    --name products \
    --kind sdk \
    --url http://localhost:8089

As tool services in Parlant are sandboxed—they run in a separate process to protect the general Parlant server from any service-specific malfunctions—we need to ensure the tool service is running.

In a separate terminal, let's also keep the tool service running in the background:

cd tool-service
poetry run python parlant_tool_service_starter/service.py

note

You should have 3 terminals open now. One with a running parlant-server, another with a running tool service, and another one ready to run new commands.

Create The Guideline

In Parlant, tools are always run in the context of specific guidelines. This 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 relevant tools for those guidelines.

note

Remember, Parlant may try to warn you about a potential conflict with our previous guideline. This is an important feature to ensure your agent stays coherent. If you see this warning, re-run the command adding --no-check at the end to assert that there's no real conflict here.

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

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

parlant guideline tool-enable \
    --agent-id $AGENT_ID \
    --id <last-guideline-id> \
    --service "products" \
    --tool "get_products_by_type"

Second, handle the case where a customer doesn't know what to choose:

$ parlant guideline create \
    --agent-id $AGENT_ID \
    --condition "customer's interested in a product type but didn't choose yet" \
    --action "help the customer clarify their needs and preferences"

(For this guideline we probably don't have to enable our tool)

Third, recommend products based on needs:

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

$ parlant guideline tool-enable \
    --agent-id $AGENT_ID \
    --id <last-guideline-id> \
    --service "products" \
    --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.

Now let's test it out! Head over to http://localhost:8800 (or wherever your server's running) and enjoy the fruits of your work!

What Next?

We invite you to peruse our Concepts docs to better understand how Parlant works internally, and how to make the best use of it.