Understanding Human Handoff in Customer Service Automation: A Guide to Implementation

In today’s fast-paced digital world, customer service automation is becoming the norm. However, as much as AI technology has advanced, there are moments when human intervention is still essential. This is where human handoff systems come into play, acting as a bridge between automated customer service and human expertise. In this article, we’ll explore how to create an effective human handoff system for an AI-powered insurance agent, utilizing a framework called Parlant.

What is Human Handoff?

Human handoff refers to a process in customer service automation where, if an AI system fails to adequately address a customer’s needs, a skilled human operator seamlessly takes over the conversation. This ensures continuity of service, maintaining high levels of customer satisfaction while combining the efficiency of AI with the nuanced understanding that only a human can provide.

Setting Up the Dependencies

To successfully implement a human handoff system, the first step is ensuring that you have the necessary tools in place.

1. Obtaining OpenAI API Key

Before diving into the code, you’ll need a valid OpenAI API key. Generate this from your OpenAI dashboard. To keep your credentials secure, create a .env file in your project’s root directory and store the key:

plaintext
OPENAI_API_KEY=your_api_key_here

This method ensures your API key is safe from being exposed within your codebase.

2. Installing Required Libraries

Next, you’ll need to install several libraries:

bash
pip install parlant dotenv streamlit

Building the Insurance Agent

With the dependencies in place, you can build your insurance agent, which will facilitate customer interactions while maintaining a human handoff capability.

Loading Required Libraries

Start by importing the necessary libraries in your Python script:

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

The agent’s functionality relies on various tools that it can use to assist customers effectively.

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"
})

These tools allow the agent to provide customers with crucial information, file claims, and retrieve policy details.

Introducing the Human Handoff Mechanism

One of the key tools you will implement is for initiating a human handoff:

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" # Switch session to manual mode
}
)

This tool ensures that when the AI encounters a query it cannot handle, it will smoothly transition the conversation to a human operator.

Defining the Glossary

An effective glossary helps the AI recognize and respond to specific terms consistently. This ensures that your agent provides accurate and contextually appropriate answers.

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",
)

Creating Journeys for Customer Interactions

Human handoff should be incorporated within various customer journeys. For instance, the "Claim Journey" can guide customers through filing a claim, while a "Policy Journey" can help explain coverage.

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"],
)

s0 = await journey.initial_state.transition_to(chat_state="Ask for accident details")
s1 = await s0.target.transition_to(tool_state=file_claim, condition="Customer provides details")
s2 = await s1.target.transition_to(chat_state="Confirm claim was submitted", condition="Claim successfully created")
await s2.target.transition_to(state=p.END_JOURNEY, condition="Customer confirms submission")

return journey

Running the Agent

Your agent can now be executed locally, handling all conversation logic via the user interface. The esteemed users will connect to your AI agent via http://localhost:8800, engaging in real-time support.

Developing the Human Handoff Interface

Once the agent is up and running, you can create a Streamlit-based interface for human operators.

Setting Up Streamlit

Initially, start with importing necessary libraries:

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

Client Setup and Session Management

Here, you connect to the running instance of your agent and set up session management using Streamlit’s state features. This allows data persistence across user interactions:

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

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

Rendering Messages Within the Interface

Implement distinct message rendering functions for various participants in conversations to ensure clarity:

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

Implement an asynchronous function to fetch new messages from your agent, keeping the conversation updated in the Streamlit interface:

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:
message = event.data.get("message")
source = event.source
participant_name = event.data.get("participant", {}).get("display_name", "Unknown")
timestamp = getattr(event, "created", None) or event.data.get("created", "Unknown Time")
st.session_state.events.append((message, source, participant_name, timestamp))
st.session_state.last_offset = max(st.session_state.last_offset, event.offset + 1)
except Exception as e:
st.error(f"Error fetching events: {e}")

Interaction Features

The interface allows the human agent to either interact directly with the customer or send messages on behalf of the AI, ensuring a fluid transition between AI and human interaction.

python
if st.button("Send as Human"):
if operator_msg.strip():
asyncio.run(send_human_message(session_id, operator_msg))
st.success("Message sent as human agent ✅")

Final Thoughts

Implementing a human handoff system is crucial in today’s customer service landscape where AI plays an increasing role. By integrating effective tools, creating structured journeys, and ensuring seamless transitions between AI and human agents, organizations can significantly enhance their customer service experience. Building the right infrastructure will enable businesses to meet customer needs efficiently while leveraging the strengths of both AI and human interaction.

Explore the full code here, and don’t hesitate to reach out for further inquiries or guidance on implementation.