Building Robust AI Agents with Parlant: A Step-by-Step Guide

Creating dependable AI agents that perform consistently in real-world scenarios remains a significant hurdle for developers, especially when working with large language models (LLMs). While these models often excel in controlled testing environments, they can falter during live interactions-overlooking system instructions, delivering inaccurate or irrelevant answers, mishandling unusual cases, or exhibiting erratic behavior across conversations.

Parlant offers a solution by moving beyond traditional prompt engineering towards a framework centered on principled development. This approach empowers developers to establish explicit rules and integrate external tools, enabling AI agents to safely and reliably access and process real-time data.

Getting Started: Installing Parlant and Setting Up Your Environment

To begin, install the Parlant package using pip:

pip install parlant

Then, import the necessary modules to build your AI agent:

import asyncio
from datetime import datetime
import parlant.sdk as p

Creating Domain-Specific Tools for an Insurance AI Assistant

To simulate the core functionalities of an insurance support agent, we define three asynchronous tools:

• fetch_open_claims: Retrieves a current list of open insurance claims, allowing the agent to inform users about pending or approved claims.
• submit_claim: Accepts claim details and simulates filing a new insurance claim, returning a confirmation message.
• retrieve_policy_info: Provides key policy details such as policy number and coverage limits, enabling accurate responses to coverage inquiries.

@p.tool
async def fetch_open_claims(context: p.ToolContext) -> p.ToolResult:
    return p.ToolResult(data=["Claim #789 - Under Review", "Claim #101 - Approved"])

@p.tool
async def submit_claim(context: p.ToolContext, claim_info: str) -> p.ToolResult:
    return p.ToolResult(data=f"Claim successfully submitted: {claim_info}")

@p.tool
async def retrieve_policy_info(context: p.ToolContext) -> p.ToolResult:
    return p.ToolResult(data={
        "policy_id": "INS-2024-3344",
        "coverage_details": "Includes fire, flood, and theft protection up to $75,000"
    })

Establishing a Domain Glossary and Defining Customer Interaction Flows

To ensure the AI agent comprehends essential business terminology and follows structured conversation paths, we define a glossary and customer journeys.

Glossary Terms

These terms help the agent reference critical information accurately during interactions:

• Support Hotline: Reachable at +1-800-INSURE-24/7
• Business Hours: Monday through Friday, 8 AM to 7 PM

Customer Journeys

Two primary journeys guide the agent’s responses:

• Claim Submission Journey: Walks customers through reporting and filing a new insurance claim.
• Policy Explanation Journey: Retrieves and clearly explains the customer’s insurance coverage details.

async def add_insurance_glossary(agent: p.Agent):
    await agent.create_term(
        name="Support Hotline",
        description="Available 24/7 at +1-800-INSURE-24/7",
    )
    await agent.create_term(
        name="Business Hours",
        description="Open Monday to Friday, 8 AM - 7 PM",
    )

async def build_claim_submission_journey(agent: p.Agent) -> p.Journey:
    journey = await agent.create_journey(
        title="Submit an Insurance Claim",
        description="Guides customers through the claim filing process.",
        conditions=["Customer wants to file a new claim"],
    )
    step1 = await journey.initial_state.transition_to(chat_state="Request accident details")
    step2 = await step1.target.transition_to(tool_state=submit_claim, condition="Customer provides claim info")
    step3 = await step2.target.transition_to(chat_state="Confirm claim submission")
    await step3.target.transition_to(state=p.END_JOURNEY)
    return journey

async def build_policy_explanation_journey(agent: p.Agent) -> p.Journey:
    journey = await agent.create_journey(
        title="Explain Insurance Policy",
        description="Fetches and clarifies policy coverage for customers.",
        conditions=["Customer inquires about policy coverage"],
    )
    step1 = await journey.initial_state.transition_to(tool_state=retrieve_policy_info)
    await step1.target.transition_to(
        chat_state="Provide clear explanation of policy coverage",
        condition="Policy data retrieved successfully",
    )
    await agent.create_guideline(
        condition="Customer requests legal interpretation",
        action="Politely inform that legal advice cannot be provided",
    )
    return journey

Launching the Insurance Support Agent

The final step involves assembling all components and starting the Parlant server. This setup initializes the insurance agent, loads the glossary and journeys, and manages ambiguous customer intents by prompting the agent to select the appropriate conversation path. Once running, the server outputs a confirmation message, and you can interact with the agent via the Parlant UI at http://localhost:8800.

async def main():
    async with p.Server() as server:
        agent = await server.create_agent(
            name="Insurance Support Agent",
            description="A courteous and knowledgeable assistant for claims and policy questions.",
        )
        await add_insurance_glossary(agent)
        claim_journey = await build_claim_submission_journey(agent)
        policy_journey = await build_policy_explanation_journey(agent)

        # Handle unclear customer intents by offering journey choices
        ambiguous_intent = await agent.create_observation(
            "Customer mentions an issue without specifying claim or policy"
        )
        await ambiguous_intent.disambiguate([claim_journey, policy_journey])

        # Global guideline for off-topic queries
        await agent.create_guideline(
            condition="Customer asks unrelated questions",
            action="Kindly steer the conversation back to insurance-related topics",
        )

        print("✅ Insurance Support Agent is live! Access the Parlant UI to start chatting.")

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

Conclusion

By leveraging Parlant’s principle-driven framework, developers can build AI agents that maintain consistent, reliable behavior in production environments. Integrating domain-specific tools and structured conversational journeys ensures that agents not only understand user intents but also provide accurate, context-aware responses. This approach significantly reduces the unpredictability often encountered with LLM-based assistants, enhancing user satisfaction and operational efficiency.

With the insurance agent example, you can see how Parlant facilitates the creation of specialized AI systems capable of handling complex workflows while maintaining clarity and professionalism in customer interactions.