Parlant

A session represents a continuous, structured interaction between an agent and a customer. Unlike many frameworks that assume a rigid turn-by-turn model (Message $\rightarrow$ Reply), Parlant uses a Modern Interaction Model that supports real-world conversational patterns, such as:

• Multiple customer messages sent before an agent responds.
• Agent-initiated follow-ups or status updates (e.g., putting a customer on hold).
• Asynchronous events like tool calls and status indicators.

Sessions encapsulate the entire conversation history, including message history, status indicators, frontend events, and tool results. This built-in history serves as the agent's 'memory', allowing it to remain aware of the full context to apply instructions and generate appropriate responses.

A guideline is the fundamental modeling entity in Parlant used to nudge an AI agent on how to approach specific situations. Instead of using a single large system prompt, you define granular guidelines that consist of two parts:

1. Condition: Describes the circumstances in which the guideline should apply.
2. Action: Describes what the agent should do when the condition is met.

Key Features of Guidelines:

• Automatic Selection: Parlant automatically filters and selects the most relevant guidelines for any given situation based on the condition and action.
• State Awareness: Parlant tracks whether a guideline has already been applied to prevent unnecessary repetition.
• Applicability Types: It distinguishes between guidelines that are always applicable and those that are only applicable once per conversation.
• Enforcement & Explainability: Parlant enforces matched guidelines and provides logs explaining how the agent interpreted the situation and the guidelines.

await agent.create_guideline(
  condition="you have suggested a solution that did not work for the user",
  action="ask if they'd prefer to talk to a human agent, or continue troubleshooting with you",
)

In Parlant, tools are not called based on the LLM's judgment alone. Instead, they are tightly integrated with the guidance system. A tool only executes when its associated guideline is matched to the conversation.

This creates a separation of concerns:

• Guidelines (the 'Button'): Determine the when and why (the intent/condition).
• Tools (the 'API function'): Handle the how (the business logic/execution).

By associating tools with specific guidelines, you prevent the false-positive tool calls common in standard LLM implementations. You can explicitly define the relationship using agent.create_guideline or let Parlant infer the association from the tool's description using agent.attach_tool.

# Explicitly connecting a tool to a guideline
await agent.create_guideline(
    condition=CONDITION,
    action=ACTION,
    tools=[my_tool],
)

# Or letting Parlant infer the association from the tool description
await agent.attach_tool(condition=CONDITION, tool=my_tool)

To secure a production deployment, you can implement custom authorization logic by subclassing AuthorizationPolicy or, more commonly, by extending ProductionAuthorizationPolicy.

The AuthorizationPolicy Interface

All policies must implement the following abstract methods:

• check_permission(request, permission): Returns True if the request has permission for the specific AuthorizationPermission.
• check_rate_limit(request, permission): Returns True if the request is within allowed frequency limits.
• authorize(request, permission): A combined check that calls both methods above. This is typically not overridden as its default behavior is to raise an authorization error if either check fails.

Recommended Implementation Pattern

Instead of building from scratch, subclass ProductionAuthorizationPolicy. This allows you to leverage existing production rules while adding custom logic, such as JWT validation or Machine-to-Machine (M2M) token support.

class AuthorizationPolicy:
    @abstractmethod
    async def check_permission(
        self,
        request: fastapi.Request,
        permission: AuthorizationPermission
    ) -> bool:
        ...

    @abstractmethod
    async def check_rate_limit(
        self,
        request: fastapi.Request,
        permission: AuthorizationPermission
    ) -> bool:
        ...

    async def authorize(
        self,
        request: fastapi.Request,
        permission: AuthorizationPermission
    ) -> None:
        ...

The glossary is not just for customer understanding; it is also used by the agent to interpret its own Guidelines. When a guideline's condition or action contains specific terminology, the agent uses the glossary to resolve those terms.

For example, if a guideline triggers when a user asks about "Ocean View rooms", and "Ocean View" is defined in the glossary, the agent can correctly map user phrases like "rooms with a view to the Atlantic" to that guideline.

# The guideline relies on the terms defined below
await agent.create_guideline(
    condition="the user asks about Ocean View rooms",
    action="explain the Sunrise Package benefits",
)

# The glossary provides the necessary context for the guideline to function
await agent.create_term(
    name="Ocean View",
    description="Our premium rooms on floors 15-20 facing the Atlantic",
    synonyms=["seaside rooms", "beach view"],
)

await agent.create_term(
    name="Sunrise Package",
    description="Complimentary breakfast and early check-in for Ocean View bookings",
    synonyms=["morning special", "sunrise special"],
)

Unlike traditional LLM applications that use large, static system prompts, Parlant uses an engine to dynamically assemble a focused context for each conversational turn.

Instead of overwhelming the model with all possible instructions, the engine matches only the relevant components based on the current interaction. The core components used for context assembly include:

• Observations: Events that trigger specific tools or behaviors.
• Guidelines: Behavioral rules defined as condition-action pairs.
• Journeys (SOPs): Multi-turn standard operating procedures that adapt to user interaction.
• Retrievers: Domain knowledge used to augment context.
• Glossary: Domain-specific vocabulary.
• Variables: Memories or stateful information.

This approach ensures that adding more rules makes the agent smarter rather than more confused, as the engine filters for relevance before the LLM ever sees the prompt.