Guidelines

Guidelines

Guidelines are a powerful customization feature. While they're quite simple in principle, there is a lot to say about them.

What Are Guidelines?

Guidelines are the primary way to nudge the behavior of agents in Parlant in a contextual and targeted manner.

They allow us to instruct how an agent should respond in specific situations, overriding its default behavior, thus ensuring that its behavior aligns with our expectations and business needs.

Guidelines allow us to shape an agent's behavior in two key scenarios:

1. When certain out-of-the-box responses don't meet our expectations
2. When we simply want to ensure consistent behavior across all interactions

Guidelines vs. Journeys

Journeys are the ideal way to provide a structured, step-by-step interaction flow, while guidelines are more about providing contextual nudges to the agent's behavior. Use journeys for complex interactions that require multiple steps, and guidelines for simpler, context-specific adjustments—as well as for simple, general tool-calling triggers that aren't necessarily within any particular journey.

Example

Suppose we have an agent that helps customers order products. By default, the agent's behavior might look like this:

User: I'd like to order a new laptop.

Agent: Sure, what are your preferences? (e.g., budget, operating system, screen size, use cases?)

But say we want to make our agent more personable by first having it ask simply whether they want Mac or Windows. We can add a guideline to ensure that this happens consistently, like so:

await agent.create_guideline(
    condition="The customer wants to buy a laptop",
    action="First, determine whether they prefer Mac or Windows"
)

Resulting in a conversation like this:

User: I'd like to order a new laptop.

Agent: Sounds good. Would you prefer Mac or Windows?

Careful What You Wish For

Instructing an LLM is very similar to instructing a human, except that by default it has absolutely zero context of who is instructing it and the context in which the instruction is given. For this reason, when we provide guidelines, we must strive to be as clear and articulate as possible, so that the agent can follow them without ambiguity. More about this later in this page.

The Structure of Guidelines

In Parlant, each guideline is composed of two parts: the condition and the action.

1. The action part describes what the guideline should accomplish. For example, "Offer a discount."
2. The condition is the part the specifies when the action should take place. For example, "It is a holiday".

await agent.create_guideline(
    condition="It is a holiday",
    action="Offer a discount on the order"
)

When speaking informally about guidelines, we often describe them in when/then form: When <CONDITION>, Then <ACTION>, or in this case, When it is a holiday, Then offer a discount.

Guideline Tracking

Once the action is accomplished in a session, Parlant will deactivate the guideline—unless it has reason to believe the action should re-apply due to a contextual shift (e.g., in the example above, if the customer starts another order).

Expanded Descriptions

Sometimes (not always!) a condition or action requires elaboration, either to clarify what we mean by it, or to tweak the agent's understanding after trial and error reveals that it isn't interpreting things quite right.

For such cases, you can provide a description that elaborates on the guideline:

await agent.create_guideline(
    condition="The customer mentions a competitor product",
    action="Acknowledge their experience and highlight our differentiators",
    description="""We want to be respectful of competitor products
(such as BrandX, ABC Corp, and others in our sector), while
emphasizing our unique value. Never disparage competitors directly.
Focus on features like our 24/7 support and flexible pricing."""
)

The description is included in the agent's context when the guideline is matched, helping it understand the nuance behind the condition or action, assisting both in the matching process as well as in the agent's ability to correctly follow the guideline during message generation.

Criticality

In practice, there's often a fundamental tension in designing agents that must follow many guidelines: the more you enforce instructions, the more you risk losing contextual nuance and meeting with robotic rigidity.

Indeed, some instructions can't tolerate mistakes, like compliance disclosures, high-stakes action confirmations, or security checks. The agent had better be pedantic about those, even at the occasional cost of making it sound more robotic in those moments.

But with other instructions, you often just want the agent to keep them in mind, like a conversational style preference or a nudge for how it should approach specific scenarios.

Criticality levels let you tell your agent how much attention to pay to each guideline:

Level	Description	When to Use
LOW	The agent will make an effort to follow the guideline, but won't spend significant resources on conforming to it.	"Nice to have" guidelines where you want to reduce rigidity.
MEDIUM	The agent will try harder to conform to the guideline, while keeping some flexibility around it. This is the default.	"Should have" guidelines within the right context.
HIGH	The agent will try its hardest to follow the guideline, potentially even to the point of being pedantic about it. Parlant will use more resources to comply.	Absolute "must have" guidelines for critical points in the interaction.

Examples

# HIGH - Compliance disclosure that must be followed
await agent.create_guideline(
    condition="Customer asks about cancellation fees",
    action="Disclose the $50 cancellation fee before proceeding",
    criticality=p.Criticality.HIGH
)

# MEDIUM - Standard business logic
await agent.create_guideline(
    condition="Customer wants to return an item",
    action="Suggest store credit as an alternative to a refund",
    criticality=p.Criticality.MEDIUM
)

# LOW - Style preference / gentle nudge
await agent.create_guideline(
    condition="The conversation has just started",
    action="Inquire if they want to hear about on-sale items",
    criticality=p.Criticality.LOW
)

Practical recommendations:

• Default to MEDIUM, then adjust based on observed behavior
• Reserve HIGH for: compliance requirements, legal obligations, security checks, safety-critical instructions
• Use LOW for: stylistic preferences and non-critical behavioral nudges (incidentally, this level also helps reduce latency and costs, as the matching quality can be more relaxed)

Using Tools

One of the foremost issues with most LLMs is their bias toward false-positives. Put simply, they are always looking to please, so they will tend to answer positively to most questions.

This becomes a huge problem when we want to ensure that an agent only performs certain actions when it has the right context or information.

For this reasons, Parlant allows us to associate tools (essentially, functions) with guidelines, such that the agent would only consider calling a tool when a guideline's requisite condition is met within the interaction's current context.

Just as importantly, it also allows you to specify contextual information on how and why you want a particular tool to be called when certain circumstances hold. Here's an example:

@p.tool
async def find_products_in_stock(context: p.ToolContext, query: str) -> p.ToolResult:
  ...

await agent.create_guideline(
    condition="The customer asks about the newest laptops",
    action="First recommend the latest Mac laptops",
    # The guideline's action will ensure the following tool is
    # called with the right query (e.g., "Latest Mac laptops")
    tools=[find_products_in_stock],
)

How Guidelines Work

To understand how guidelines work, we need to look briefly at Parlant's response processing pipeline.

When an agent receives a message, it goes through a response processing pipeline that involves several steps to ensure the response is aligned with the guidelines and expectations.

As the figure above suggests, guidelines are evaluated and matched before the agent composes its response.

Keep in Mind

This means that the agent needs to be able to evaluate and apply instructions and tool calls based on the interaction's context before generating the response. In other words, guidelines such as "Do X immediately after you've done Y" may not work as you expect.

Questions? Reach out!

How Parlant Uses Guidelines

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 guidelines at each point.

Before each response, Parlant only loads the guidelines 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.

info

Another important ability that Parlant employs to ensure alignment is supervising the agent's outputs before they reach the customer, to ensure to the utmost degree that guidelines were correctly adhered to. To achieve this, NLP researchers working on Parlant have devised an innovative prompting technique called Attentive Reasoning Queries (ARQs). You're welcome to explore the research paper on arxiv.org, Attentive Reasoning Queries: A Systematic Method for Optimizing Instruction-Following in Large Language Models

Managing Guidelines

Parlant is built to make guideline management as simple as possible.

Often, guidelines are added when business experts request behavioral changes in the agent. Developers can use Parlant to make those changes, iterating quickly and reliably, at the pace of the business experts they're working with.

Here's a practical example. When Sales requests: "The agent should first ask about the customer's needs and pain points before discussing our solution," implementing this feedback takes just a minute by adding the following:

await agent.create_guideline(
  condition="The customer has yet to specify their current pain points",
  action="Seek to understand their pain points before talking about our solution"
)

Once added, Parlant takes care of the rest, automatically ensuring this new guideline is followed consistently across all relevant conversations, without degrading your agent's conformance to other guidelines.

Match Handlers

You can register handlers that are called when a guideline (or an observation, which is a special term for an actionless guideline) is matched. This is useful for triggering side effects such as logging, analytics, or external integrations when specific conditions are detected.

on_match Handler

The on_match handler is called immediately after the guideline is matched, before the agent generates its response:

async def my_handler(ctx: p.EngineContext, match: p.GuidelineMatch) -> None:
  ...

await agent.create_guideline(condition=CONDITION, action=ACTION, on_match=my_handler,)

This also works with observations:

await agent.create_observation(condition=CONDITION, on_match=my_handler)

on_message Handler

In contrast to on_match which is called before the agent's response is sent, the on_message handler is called after the agent has generated and sent a message while the guideline was active:

await agent.create_guideline(condition=CONDITION, action=ACTION,on_message=my_handler)

Custom Matchers

By default, Parlant uses LLM-based guideline matching to determine which guidelines apply to the current conversation context. Custom matchers let you override this behavior for specific guidelines.

A custom matcher is an async function that receives the matching context and the guideline, and returns a GuidelineMatch indicating whether the guideline should be activated:

async def my_matcher(ctx: p.GuidelineMatchingContext, guideline: p.Guideline) -> p.GuidelineMatch:
    return p.GuidelineMatch(
        id=guideline.id,
        matched=True,  # or False
        rationale="Explanation of why it matched or didn't",
    )

await agent.create_guideline(condition=CONDITION, action=ACTION, matcher=my_matcher)

Use Cases

Cost Optimization

Perhaps the most common use case for custom matchers is to implement matching in a more cost-effective manner. If you can match specific guidelines using simpler methods (e.g., a smaller BERT model, embeddings, or even regular expressions) you will significantly reduce costs compared to LLM-based matching.

Keep in mind that if you use a simplistic matcher, you may sacrifice some accuracy in matching. Always test and validate your custom matchers to ensure they meet your requirements.

import re

async def keyword_matcher(ctx: p.GuidelineMatchingContext, guideline: p.Guideline) -> p.GuidelineMatch:
    last_message = ctx.interaction.last_customer_message or ""
    matched = bool(re.search(r"refund|return|money back", last_message, re.IGNORECASE))
    return p.GuidelineMatch(
        id=guideline.id,
        matched=matched,
        rationale="Keyword match on refund-related terms" if matched else "No refund keywords found",
    )

Always-On Guidelines

For guidelines that should always be in context, use p.Guideline.MATCH_ALWAYS. It's recommended to still qualify the condition to ensure clarity, precisely because the agent will always be asked to follow this guideline.

await agent.create_guideline(
    condition="You need to present data which lends itself to tabular form",
    action="Use markdown table formatting",
    matcher=p.Guideline.MATCH_ALWAYS,
)

Cognitive Load

Be careful with always-on guidelines. The more guidelines are in context, the harder it is for the LLM to follow them consistently. This is why guideline matching exists in the first place. Use this function sparingly, despite its convenience.

Nuanced Matching Logic

Sometimes you need matching logic that the built-in matcher doesn't provide. Custom matchers let you run specialized LLM queries, consult external data sources, or apply complex business logic to determine relevance.

The GuidelineMatchingContext Object

The matching context provides access to:

• session - current session
• agent - current agent
• customer - current customer information
• variables - context variables and their values

Formulating Guidelines

Think of an LLM as a highly knowledgeable stranger who's just walked into your business. They might have years of general experience, but they don't know your specific context, preferences, or way of doing things. Yet, this stranger is eager to help and will always try to—even when uncertain.

This is where guidelines come in. They're your way of channeling this endless enthusiasm and broad knowledge into focused, appropriate responses.

But specifying effective guidelines is a bit of an art—just like it is with people.

The Art of Guidance

Consider a customer service scenario. As a very naive example, we might be tempted to have:

DON'T

• Condition: Customer is unhappy
• Action: Make them feel better

While well-intentioned, this is an example of a guideline that is just too vague. The LLM might interpret this in countless ways, from offering discounts it can't actually provide to making jokes that might be inappropriate for your brand. Instead, consider:

DO

• Condition: Customer expresses dissatisfaction with our service
• Action: Acknowledge their frustration specifically, express sincere empathy, and ask for details about their experience so we can address it properly.

Notice how this guideline is both specific and bounded.

DON'T

• Condition: Customer asks about products
• Action: Recommend something they might like

DO

• Condition: Customer asks for product recommendations without specifying preferences
• Action: Ask about their specific needs, previous experience with similar products, and any particular features they're looking for before making recommendations

Finding the Right Balance

In principle, we're looking for guidelines that are "just right"—neither over nor under specified. Consider these iterations for a technical support agent:

DON'T

Too vague:

• Condition: Customer has a technical problem
• Action: Help them fix it

DON'T

Too rigid:

• Condition: Customer reports an error message
• Action: First ask for their operating system version, then their browser version, then their last system update date

DO

Just right:

• Condition: Customer reports difficulty accessing our platform
• Action: Express understanding of their situation, ask for key details about their setup (OS and browser), and check if they've tried some concrete troubleshooting steps

Remember, LLMs will usually take your guidance quite literally. If you tell your agent to "always suggest premium features," it might do so even when talking to a customer who's complaining about pricing. Always try to consider the broader context and potential edge cases when formulating your guidelines. It'll pay off in less changes and trouleshooting down the line.

If in doubt, prefer to err on the side of vagueness. The goal of your Alignment Model isn't to script out every possible interaction but to provide clear, contextual guidance that shapes the LLM's natural generalization abilities into reliable, appropriate responses for your specific use case.