Skip to main content

Customers

Customers​

In Parlant, a customer is a code word for anyone who interacts with an agent—regardless of the real nature of the relationship between them. In other words, a customer can be a real person, a bot, or even a human agent.

While agents can operate anonymously (without knowing who they're talking to), Parlant allows you to track registered customers and provide deeply personalized experiences based on their identity and preferences.

By letting your agents understand who they're talking to, you can tailor interactions for different user segments: high-profile customers might receive premium offers, new users can get focused onboarding guidance, and so forth...

Parlant makes customer registration simple, requiring only minimal identification—a name is enough to get started.

import parlant.sdk as p

async with p.Server() as server:
    # Register a new customer
    customer = await server.create_customer(name="Alice")

Authentication​

Parlant aims to live as a backend service, leaving authentication and authorization to the application layer. This means that while you can register customers, you should handle their authentication (e.g., via OAuth, JWT, etc.) in your application code, in whatever way suits your needs.

Once you have identified your customer, then you can pass their ID when creating a session with an agent, allowing your agent to personalize interactions based on the registered customer.

Custom IDs​

By default Parlant will auto-generate a customer's ID when you create it. But you can also create customers with custom IDs. This is particularly useful when you want to map them directly to your existing user identifiers:

customer = await server.create_customer(
    id="usr_12345"  # Your external system's user ID
    name="Alice",
)

Updating a Session's Customer​

You can update a session's customer ID at any time using the REST API or native client SDKs. A key use case is when you want to start a session in guest mode and authenticate the user on-the-go during the conversation, allowing the agent to switch to a more personalized experience mid-session.

from parlant.client import ParlantClient

client = ParlantClient(PARLANT_SERVER_URL)

# User authenticates mid-session
client.sessions.update(
    session_id=SESSION_ID,
    customer_id="authenticated_user_123"
)
# From now on, the agent can provide a personalized experience

Storage​

You can choose where you store customers.

By default, Parlant does not persist customers, meaning that they are stored in memory and will be lost when the server restarts. This is useful for testing and development purposes.

If you want to persist customers, you can configure Parlant to use a database of your choice. For local persistence, we recommend using the integrated JSON file storage, as there's zero setup required. For production use, you can use MongoDB, which comes built-in, or another database.

This is particularly useful when your tools need to access external services (like a CRM or billing system) using the customer ID. By using the same ID in Parlant as in your external systems, tools can directly look up customer data without needing a separate mapping.

Alternative Option - Integrate with Your Existing Database

If you already have customer data in your own database, you can actually implement the p.CustomerStore interface and register it with the container, to load customers directly from there. This avoids duplicating customer entries in a Parlant-specific database and keeps your customer data in a single source of truth.

Persisting to Local Storage​

This will save customers under $PARLANT_HOME/customers.json.

import asyncio
import parlant.sdk as p

async def main():
    async with p.Server(customer_store="local") as server:
        # ...

asyncio.run(main())

Persisting to MongoDB​

Just specify the connection string to your MongoDB database when starting the server:

import asyncio
import parlant.sdk as p

async def main():
    async with p.Server(customer_store="mongodb://path.to.your.host:27017") as server:
        # ...

asyncio.run(main())
Install the MongoDB Extra

To use MongoDB as your customer store, you need to install the parlant[mongo] extra.

pip install "parlant[mongo]"
github We can help you ramp up

Customer Groups​

You can also divide your customers into different groups and control group-specific personalization by using tags.

For example, you can create a tag for VIP customers:

# Create a new tag to represent VIP customers
vip_tag = await server.create_tag(name="VIP")

# Register a new customer
customer = await server.create_customer(name="Alice", tags=[vip_tag.id])
Learn More

To learn more about advanced personalization possibilities for specific customers and groups, check out the variables section.

Adding Metadata​

You can also attach custom metadata to customers, which can be used to store additional information about them. This metadata can be used to further personalize interactions or to provide context for tool calls.

customer = await server.create_customer(name="Alice", metadata={
    "external_id": "12345",
    "location": "USA",
})
@p.tool
async def get_customer_location(context: p.ToolContext) -> p.ToolResult:
    customer = p.Customer.current
    return p.ToolResult(customer.metadata.get("location", "Unknown location"))

Registering Customers​

While you can register customers using the SDK itself, it's often more practical to handle customer registration through your application layer. This allows you to integrate customer management with your existing user authentication and authorization systems.

You can do this by using Parlant's REST API or native Client SDKs to create and manage customers.

from parlant.client import ParlantClient

# Change localhost to your server's address
client = ParlantClient("http://localhost:8800")

client.customers.create(
    name="Alice",
    metadata={
        "external_id": "12345",
        "location": "USA",
        "hobby": "reading",
    },
    tags=[TAG_ID]  # Optional: specify tag IDs to assign to the customer
)

Updating Customer Data​

You can update customer data at any time, including their name, metadata, and tags. This is useful for keeping customer information up-to-date as your application evolves.

client.customers.update(
    customer_id=CUSTOMER_ID,
    name="Alice Smith",
    metadata={
        "set": {
            "location": "Canada",
        },
        "remove": ["hobby"],
    },
    tags=[NEW_TAG_ID]  # Optional: specify new tag IDs to assign to the customer
)
github Reach out for help