Journeys

Journeys

Journeys let you define the happy flow of conversations in your agent. They are a powerful way to create structured interactions, guiding users through a series of steps or questions.

Journeys have 2 important components:

1. Conditions: These contextual queries determine when a journey should be active.
2. Description: This is a structured outline of the steps or questions that will be asked during the journey.

Consider the following example for a "Booking" journey in a travel agent:

• Conditions: The customer is looking to book a trip
• Description:
  1. Determine if they have a destination in mind or if they need suggestions
  2. Get the dates of travel
  3. Clarify the number of guests
  4. Ask about their budget
  5. Confirm the details and offer to book the trip

This journey will be activated when the user expresses interest in booking a trip. The agent will then follow the structured steps outlined in the description in a natural, conversational manner at the pace of the customer, yet ensuring that all necessary information is collected in a logical order.

How Parlant Uses Journeys

LLMs are a magnificent creation, built on the principle of statistical attention in text; yet, their attention span is painfully finite. When it comes to following instructions, they need help.

Behind the scenes, Parlant ensures that agent responses are aligned with expectations by dynamically managing the LLM's context to only include the relevant journeys at each point. It does this by using a specialized component called the GuidelineMatcher, which is responsible for matching the current conversation context with the relevant journeys' conditions, which, behind the scenes are basically observational (non-actionable) guidelines.

Before each response, Parlant only loads the guidelines and journeys that are relevant to the conversation's current state. This dynamic management keeps the LLM's "cognitive load" minimal, maximizing its attention and, consequently, the alignment of each response with expected behavior.

Formulating Journeys

DON'T

Description: Determine if they have a destination in mind or if they need suggestions, then get the dates of travel, clarify the number of guests, ask about their budget, and confirm the details and offer to book the trip.

Parlant utilizes the journey description better if you break it down into an ordered list of steps. This allows the agent to focus on one step at a time, ensuring a smoother and more engaging conversation.

DO

Description:

1. Determine if they have a destination in mind or if they need suggestions
2. Get the dates of travel
3. Clarify the number of guests
4. Ask about their budget
5. Confirm the details and offer to book the trip

Creating a Journey

Create a Journey (CLI)

description=$(cat <<EOF
Proactively help the customer decide what new car to get.

1. First vibe and seek to clarify their situation and needs.
    Chit-chat about their current car, what they like or don't,
    as well as whether they have children or pets.
2. Ask them about budget and preferences.
3. Once needs are clarified, recommend relevant categories
    or specific models for consideration.
4. Once a choice is made, ask them to confirm the order
EOF
)

parlant journey create \
  --title "Sell a car" \
  --description "$description" \
  --condition "The customer expressed general interest in new cars" \
  --condition "The customer wants to buy a new car" \
  --tag <tag>  # Optional

Create a Journey (SDK)

from textwrap import dedent
import parlant.sdk as p

sell_car_journey = await my_agent.create_journey(
    title="Sell a car",
    conditions=[
        "The customer wants to buy a new car",
        "The customer expressed general interest in new cars",
    ],
    description=dedent("""\
        Proactively help the customer decide what new car to get.

        1. First vibe and seek to clarify their situation and needs.
            Chit-chat about their current car, what they like or don't,
            as well as whether they have children or pets.
        2. Ask them about budget and preferences.
        3. Once needs are clarified, recommend relevant categories
            or specific models for consideration.
        4. Once a choice is made, ask them to confirm the order"""),
)

Attaching Guidelines to Journeys

If you don't already know how to create guidelines, check out the Guidelines page.

Otherwise, know that you can attach guidelines to journeys such that those guidelines will only be activated when their dependent journey is active. This is a great way to maintain a clean and organized conversation model, ensuring that guidelines are only activated in their intended context.

Attach a Guideline to a Journey (CLI)

You can specify the special tag journey:<journey ID> when creating a guideline to attach it to a journey. This will ensure that the guideline is only activated when the specified journey is active.

parlant relationship create \
  --kind dependency \
  --source <guideline ID> \
  --target journey:<journey ID>

Attach a Guideline to a Journey (SDK)

Using the SDK, you simply need to create your guidelines using the journey object on which you want to attach them.

guideline = await my_journey.create_guideline(
    condition="<condition>"
    action="<action>",
),