Building a Human Handoff Interface for AI-Powered Insurance Agent Using Parlant and Streamlit

Human handoff plays a crucial role in customer service automation, particularly in scenarios where artificial intelligence encounters limitations. This mechanism allows a trained human operator to step in seamlessly, ensuring customers receive the assistance they need even when AI falls short. In this tutorial, we’ll focus on creating a human handoff system for an AI-powered insurance agent using the Parlant framework. You’ll learn how to build a Streamlit-based interface that enables human operators (Tier 2) to engage with live customer interactions, facilitating a dynamic collaboration between AI automation and human expertise. You can access the FULL CODES here for reference.

Setting Up the Dependencies

Before diving into the project, ensure you have a valid OpenAI API key. You can generate this key from your OpenAI dashboard. Create a .env file in the root directory of your project to securely store this key as follows:

plaintext
OPENAI_API_KEY=your_api_key_here

Storing credentials in this manner prevents exposure in your codebase, enhancing security.

Next, install the necessary libraries using the following:

bash
pip install parlant dotenv streamlit

Insurance Agent (agent.py)

Loading the Required Libraries

The agent.py script will form the backbone of your AI interaction logic. Start by importing the following libraries:

python
import asyncio
import os
from datetime import datetime
from dotenv import load_dotenv
import parlant.sdk as p

load_dotenv()

Defining the Agent’s Tools

In this section, you’ll create the tools that the AI will utilize. These tools simulate common interactions for an insurance assistant.

python
@p.tool
async def get_open_claims(context: p.ToolContext) -> p.ToolResult:
return p.ToolResult(data=["Claim #123 – Pending", "Claim #456 – Approved"])

@p.tool
async def file_claim(context: p.ToolContext, claim_details: str) -> p.ToolResult:
return p.ToolResult(data=f"New claim filed: {claim_details}")

@p.tool
async def get_policy_details(context: p.ToolContext) -> p.ToolResult:
return p.ToolResult(data={
"policy_number": "POL-7788",
"coverage": "Covers accidental damage and theft up to $50,000"
})

Initiating Human Handoff

The next tool will facilitate the transition from AI to a human agent when necessary.

python
@p.tool
async def initiate_human_handoff(context: p.ToolContext, reason: str) -> p.ToolResult:
print(f"🚨 Initiating human handoff: {reason}")
return p.ToolResult(
data=f"Human handoff initiated because: {reason}",
control={
"mode": "manual"
}
)

Defining the Glossary

Creating a glossary helps the AI recognize and respond to critical terms accurately, ensuring a consistent user experience:

python
async def add_domain_glossary(agent: p.Agent):
await agent.create_term(
name="Customer Service Number",
description="You can reach us at +1-555-INSURE",
)
await agent.create_term(
name="Operating Hours",
description="We are available Mon-Fri, 9AM-6PM",
)

Defining User Journeys

Now, let’s create two primary journeys for the AI: filing an insurance claim and explaining policy coverage.

Claim Journey

python
async def create_claim_journey(agent: p.Agent) -> p.Journey:
journey = await agent.create_journey(
title="File an Insurance Claim",
description="Helps customers report and submit a new claim.",
conditions=["The customer wants to file a claim"],
)

Define journey states…

return journey

Policy Journey

python
async def create_policy_journey(agent: p.Agent) -> p.Journey:
journey = await agent.create_journey(
title="Explain Policy Coverage",
description="Retrieves and explains customer’s insurance coverage.",
conditions=["The customer asks about their policy"],
)

Define journey states…

return journey

Defining the Main Runner

Finally, set up the main function that will initiate the server and register the agent.

python
async def main():
async with p.Server() as server:
agent = await server.create_agent(
name="Insurance Support Agent",
description=(
"Friendly Tier-1 AI assistant that helps with claims and policy questions. "
"Escalates complex or unresolved issues to human agents (Tier-2)."
),
)

Add glossary, journeys, and guidelines…

    print("✅ Insurance Support Agent with Human Handoff is ready! Open the Parlant UI to chat.")

Human Handoff (handoff.py)

Importing Libraries

In the handoff.py, import the necessary libraries:

python
import asyncio
import streamlit as st
from datetime import datetime
from parlant.client import AsyncParlantClient

Setting Up the Parlant Client

To communicate with the running instance of your AI agent, create an asynchronous client:

python
client = AsyncParlantClient(base_url="http://localhost:8800")

Session State Management

Use Streamlit’s session state to manage data persistently across user interactions:

python
if "events" not in st.session_state:
st.session_state.events = []
if "last_offset" not in st.session_state:
st.session_state.last_offset = 0

Message Rendering Function

Define a function to render messages within your interface, distinguishing between different sources (customer, AI agent, and human operator):

python
def render_message(message, source, participant_name, timestamp):
if source == "customer":
st.markdown(f"🧍‍♂️ Customer [{timestamp}]: {message}")
elif source == "ai_agent":
st.markdown(f"🤖 AI [{timestamp}]: {message}")
elif source == "human_agent":
st.markdown(f"🙋 {participant_name} [{timestamp}]: {message}")

Fetching Events from Parlant

Create an asynchronous function to pull new messages from your Parlant session:

python
async def fetch_events(session_id):
try:
events = await client.sessions.list_events(
session_id=session_id,
kinds="message",
min_offset=st.session_state.last_offset,
wait_for_data=5
)
for event in events:

Append event data…

except Exception as e:
    st.error(f"Error fetching events: {e}")

Sending Messages as Human or AI

Define functions to send messages, allowing either a human operator or the AI (acting on behalf of a human) to respond to customers effectively:

python
async def send_human_message(session_id: str, message: str, operator_name: str = "Tier-2 Operator"):
event = await client.sessions.create_event(…)
return event

async def send_message_as_ai(session_id: str, message: str):
event = await client.sessions.create_event(…)
return event

Streamlit Interface

Finally, build a simple, interactive Streamlit UI where human operators can enter session IDs, view chat history, send messages, and refresh to pull new messages:

python
st.title("💼 Human Handoff Assistant")
session_id = st.text_input("Enter Parlant Session ID:")
if session_id:

Display chat history and message options…

By following these steps, you’ll create a robust Human Handoff interface that enhances your AI-powered insurance agent’s functionality, combining the efficiency of AI with the nuanced understanding of human operators. Access the FULL CODES here for further exploration and implementation.