Live Expert Handoff Agent

The Uptok Live Expert Hand-off Agent is a native watsonx Orchestrate agent that detects when a conversation requires human assistance, checks Uptok expert availability in real time, and launches a live Uptok audio or video consultation with the appropriate team member.

This documentation provides a technical overview of the integration between IBM watsonx Orchestrate and Uptok, including agent behavior, onboarding flow, API endpoints, provisioning behavior, and usage-based metering.

Audience & Prerequisites

This documentation is intended for:

IBM solution engineers and architects
Customer technical owners of watsonx Orchestrate
Uptok implementation and support engineers

Prerequisites:

An IBM Cloud account with access to watsonx Orchestrate
The Uptok Live Expert Hand-off Agent added to your catalog
Network access to the Uptok API domain (https://api.uptok.com)

Architecture & Integration Flow

The agent connects Orchestrate conversations with Uptok’s real-time expert platform using three core API endpoints:

Expert Availability Check — Determines if at least one expert is online
Live Consultation Creation — Generates a live Uptok video/audio session URL
Metering Report — Reports billable handoff usage to IBM metering

Each conversation follows this flow:

User expresses intent or friction
Agent evaluates whether escalation is appropriate
Agent calls check_expert_availability
If available, agent calls create_live_consultation
Agent returns a live session link to the user
Uptok tracks confirmed human connections and reports metering usage

Provisioning & Custom Parameters

When a customer installs the agent through IBM Cloud, Orchestrate sends Uptok a provisioning request with:

Company Name — Used to create or associate an Uptok workspace
Agent Name / Purpose — Helps define initial routing logic and UX
Admin Email — Used to send onboarding instructions for Uptok account setup

Uptok responds with a workspace ID and provisioning confirmation.

API Endpoints

1. Check Expert Availability

{
  "available": true
}

2. Create Live Consultation

{
  "session_url": "https://app.uptok.com/link?k=abc123",
  "mode": "video"
}

3. Submit Metering Usage

Uptok reports usage to IBM using the customer’s plan and instance CRN.

{
  "instanceId": "starter-instance-01",
  "metricName": "HANDOFF_COUNT",
  "planId": "STARTER",
  "timestamp": "2025-11-20T20:00:00Z",
  "value": 1
}

Agent Behavior Summary

Never escalates unless intent is explicit or strongly implied
Always checks expert availability before creating a consultation
Never fabricates session URLs or availability
Provides short, clean messages to users
Avoids medical, legal, financial or binding commitments
Delegates a summary to the “Uptok Handoff Summary Writer” when handoff occurs

Usage-Based Metering

Uptok reports billable usage to IBM using the metric name: HANDOFF_COUNT.

A “billable live handoff” is counted when:

A live consultation URL is created
A human Uptok expert accepts the live call

IBM Cloud processes these reports on a 60-minute aggregation cycle.

Support

For implementation support, enterprise setup, or testing guidance, contact:

support@uptok.com

UPTOK DEVELOPERS