Therapy Session

The Therapy Session event manages standard therapy conversations between a client and therapist agent.

Overview

Property	Value
Key	therapy_session
Type	Conversation Event
Focus	Client-Therapist Dyad

Description

The Therapy Session is the primary event type in PatientHub, orchestrating conversations between client and therapist agents. It manages turn-taking, tracks conversation state, handles end conditions, and saves session output for later analysis.

Key Features

• Turn Management - Controls alternating responses between client and therapist
• State Tracking - Maintains full conversation history and metadata
• End Conditions - Multiple termination triggers (max turns, explicit end)
• Reminders - Notifies therapist when session is nearing end
• Output Saving - Automatically saves sessions in JSON format

Configuration

Python Usage

from patienthub.events import get_event

event = get_event(event_name="therapy_session")

Parameters

Parameter	Type	Default	Description
event_type	string	therapy_session	Event type identifier
max_turns	int	15	Maximum conversation turns
reminder_turn_num	int	2	Turns before end to show reminder
output_dir	string	varies	Output file path for session data

Session Flow

The TherapySession runs as a finite-state workflow:

START
  │
  ▼
init_session
  │
  ▼
generate_therapist_response
  │
  ▼
generate_client_response ──┬──► end_session (therapist says END/end/exit)
  │                        │
  ├──► end_session (num_turns >= max_turns)
  │
  └──► check_and_remind ──► generate_therapist_response
            │
            └── (adds reminder when turns_left <= reminder_turn_num)

Session State

The session state is not a separate importable type — it is defined inline through Burr's .with_state(...) when the workflow is built. The state carries the following fields:

Field	Type	Description
messages	List[Dict[str, Any]]	Conversation history
msg	str	Current message being processed
num_turns	int	Number of completed turns
session_ended	bool	End flag
initialized	bool	Init flag
needs_reminder	bool	Reminder flag

Methods

set_characters(characters: Dict[str, Any])

Set up the session participants:

event.set_characters({
    'client': client_agent,
    'therapist': therapist_agent,
    'evaluator': evaluator_agent,  # Optional
})

start()

Begin the session:

event.start()

reset()

Reset for a new session:

event.reset()

Output Format

Sessions are saved as JSON:

{
  "profile": { "name": "Client" },
  "messages": [
    { "role": "therapist", "content": "Hello, how are you feeling today?" },
    { "role": "client", "content": "I've been really anxious lately..." }
  ],
  "num_turns": 15
}

Use Cases

• Training Simulations - Practice therapy conversations
• Research Studies - Generate conversation data for analysis
• Agent Evaluation - Test client and therapist agents
• Demonstrations - Interactive therapy demos