Skip to content

Commit b2ea86a

Browse files
adamweeksAdam Weeks
adamweeks
and
Adam Weeks
authored
docs: document BYOVA handoff summaries (#48)
Co-authored-by: Adam Weeks <adweeks+cisco@cisco.com>
1 parent 16a0a24 commit b2ea86a

6 files changed

Lines changed: 219 additions & 0 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,7 @@ endpoint testing, logs, and troubleshooting.
178178
| Install and run the sample locally | [Local Development](docs/LOCAL_DEVELOPMENT.md) |
179179
| Configure the gateway and connectors | [Configuration Reference](config/README.md) |
180180
| Configure runtime JWT validation | [gRPC JWT Authentication](docs/JWT_AUTHENTICATION.md) |
181+
| Pass a virtual-agent summary to a human agent | [BYOVA Handoff Summary](docs/BYOVA_HANDOFF_CONTEXT.md) |
181182
| Run automated and service tests | [Testing Guide](docs/TESTING.md) |
182183
| Configure the monitoring dashboard | [Monitoring Interface](src/monitoring/README.md) |
183184
| Add or configure connectors | [Connector Guide](src/connectors/README.md) |

‎docs/BYOVA_HANDOFF_CONTEXT.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Passing a Virtual-Agent Handoff Summary to Webex Contact Center
2+
3+
This document defines a provider-neutral contract for passing a handoff summary from a
4+
BYOVA virtual agent to Webex Contact Center (WxCC) when the call transfers to a human agent.
5+
The goal is to let the receiving agent understand the caller's request without asking the
6+
caller to repeat it.
7+
8+
The contract applies to any virtual-agent provider. Each connector remains responsible for
9+
translating its provider's terminal response into the canonical gateway fields described
10+
below.
11+
12+
## Intended Agent Experience
13+
14+
When the virtual agent escalates a call, the human agent should receive a concise handoff
15+
summary:
16+
17+
- In the incoming-interaction popover before answering
18+
- In the Interaction Control pane after answering
19+
- Without depending on a provider-specific Agent Desktop widget
20+
21+
This document covers only the handoff summary behavior verified by this implementation.
22+
23+
## Data Flow
24+
25+
```text
26+
Virtual-agent provider
27+
|
28+
| provider-specific terminal event and generated summary
29+
v
30+
Provider connector
31+
|
32+
| canonical handoff summary
33+
v
34+
BYOVA gateway
35+
|
36+
| final VoiceVAResponse with TRANSFER_TO_AGENT
37+
v
38+
WxCC Virtual Agent V2 activity
39+
|
40+
| output-event metadata.summary
41+
v
42+
Agent-viewable flow variable
43+
|
44+
+--> incoming-interaction popover
45+
+--> Interaction Control pane
46+
```
47+
48+
The provider may generate the summary itself or return structured facts from which the
49+
connector builds a summary. The WxCC-facing response must not depend on which approach the
50+
provider uses.
51+
52+
## Canonical Gateway Handoff Summary
53+
54+
Provider connectors should normalize terminal handoff data into one internal shape before
55+
the gateway creates the BYOVA response:
56+
57+
```json
58+
{
59+
"message_type": "transfer",
60+
"handoff": {
61+
"summary": "Caller wants to change the delivery address. The virtual agent did not modify the order. Verify the caller and update the address.",
62+
"language_code": "en-US"
63+
}
64+
}
65+
```
66+
67+
`handoff.summary` contains the text intended for the receiving agent. `language_code` is
68+
optional and identifies the language used by the summary.
69+
70+
Connectors should not leak their provider's raw terminal payload into the gateway contract.
71+
They should extract only the approved fields and normalize them into this shape.
72+
73+
## BYOVA Transfer Response
74+
75+
The gateway should create one final `VoiceVAResponse` containing one
76+
`TRANSFER_TO_AGENT` output event. The following pseudocode shows the intended wire shape:
77+
78+
```json
79+
{
80+
"response_type": "FINAL",
81+
"session_summary": {
82+
"text": "Caller wants to change the delivery address. The virtual agent did not modify the order. Verify the caller and update the address.",
83+
"language_code": "en-US"
84+
},
85+
"output_events": [
86+
{
87+
"event_type": "TRANSFER_TO_AGENT",
88+
"name": "transfer_requested",
89+
"metadata": {
90+
"summary": "Caller wants to change the delivery address. The virtual agent did not modify the order. Verify the caller and update the address."
91+
}
92+
}
93+
]
94+
}
95+
```
96+
97+
The fields serve different purposes:
98+
99+
| Field | Purpose | Requirement |
100+
| --- | --- | --- |
101+
| `output_events[].metadata.summary` | Makes the summary available to the WxCC flow as transfer metadata | Required for the validated Agent Desktop path |
102+
| `session_summary` | Uses the dedicated BYOVA session-summary field | Recommended when a summary is available |
103+
104+
The summary is intentionally present in both `session_summary` and transfer metadata. The
105+
dedicated field preserves the BYOVA semantic model, while `metadata.summary` supports the
106+
current WxCC flow-variable and Agent Desktop path.
107+
108+
The relevant protocol definitions are:
109+
110+
- [`VoiceVAResponse.session_summary`](../proto/voicevirtualagent.proto)
111+
- [`OutputEvent.TRANSFER_TO_AGENT` and `metadata`](../proto/byova_common.proto)
112+
113+
## WxCC Flow Mapping
114+
115+
In Flow Designer, the Virtual Agent V2 activity exposes transfer-event metadata through its
116+
`MetaData` output. Map the normalized `summary` key to a custom String flow variable:
117+
118+
```text
119+
BYOVAHandoffSummary = {{BYOVA_Virtual_Agent.MetaData.summary}}
120+
```
121+
122+
The Virtual Agent activity name is flow-specific; replace `BYOVA_Virtual_Agent` with the
123+
actual activity name. Configure the custom variable as:
124+
125+
| Setting | Value |
126+
| --- | --- |
127+
| Type | String |
128+
| Desktop label | AI Handoff Summary |
129+
| Agent viewable | Enabled |
130+
| Agent editable | Disabled |
131+
132+
Add the variable to the incoming-interaction popover and the Interaction Control pane in the
133+
Agent Desktop layout. The transfer must continue even when the provider does not supply a
134+
summary; an absent summary is not a routing failure.
135+
136+
## Validated Agent Desktop Behavior
137+
138+
The following screenshots were captured in a nonproduction WxCC organization with synthetic
139+
handoff content. They prove the WxCC metadata-to-flow-variable-to-desktop path. They do not
140+
prove that any specific provider generates a summary automatically.
141+
142+
### Before the agent answers
143+
144+
The incoming-interaction popover includes **AI Handoff Summary** with the other request
145+
details. The narrow popover may truncate a long value, so the summary should lead with the
146+
caller's request and requested next action.
147+
148+
![Incoming interaction showing AI Handoff Summary](images/byova-handoff-summary-incoming-offer-redacted.png)
149+
150+
### After the agent answers
151+
152+
The full summary appears at the top of the active interaction, directly below the call
153+
controls.
154+
155+
![Active interaction showing AI Handoff Summary](images/byova-handoff-summary-active-interaction-redacted.png)
156+
157+
The synthetic marker in these screenshots was added by a development-only terminal insight
158+
probe. A production implementation must replace that probe with provider-neutral handoff
159+
normalization and pass-through.
160+
161+
## Gateway Requirements
162+
163+
The production gateway implementation should:
164+
165+
1. Accept a normalized handoff summary from every connector that can provide one.
166+
2. Create exactly one terminal `TRANSFER_TO_AGENT` output event.
167+
3. Copy the summary into that event's `metadata.summary` field.
168+
4. Populate `session_summary` with the same text and language when available.
169+
5. Allowlist supported metadata fields rather than forwarding an arbitrary provider payload.
170+
6. Enforce configured size limits and valid scalar types.
171+
7. Never write summary content to logs, metrics, traces, or error messages.
172+
8. Preserve transfer behavior when the summary is missing, malformed, or too large.
173+
174+
The gateway should log only safe operational facts such as whether a field was present, its
175+
character count, the selected language, and whether validation accepted or omitted it.
176+
177+
## Summary Content Guidance
178+
179+
A useful handoff summary should be factual, brief, and ordered for the receiving agent. It
180+
should include:
181+
182+
- Why the caller contacted the virtual agent
183+
- Important information the caller supplied
184+
- Actions the virtual agent completed or explicitly did not complete
185+
- The reason for escalation
186+
- The next action expected from the human agent
187+
188+
Do not include credentials, authentication tokens, payment data, unnecessary sensitive
189+
personal information, unsupported conclusions, or hidden provider diagnostics. Prefer plain
190+
text over Markdown because the Agent Desktop variable is rendered as text.
191+
192+
## Verification
193+
194+
Automated coverage should verify:
195+
196+
- A transfer with a summary creates one transfer event containing `metadata.summary`.
197+
- The same value appears in `session_summary`.
198+
- A transfer without a summary still succeeds.
199+
- Non-transfer responses do not receive handoff fields.
200+
- Oversized or invalid values are omitted or truncated according to configuration.
201+
- Summary text does not appear in logs.
202+
- Provider-specific fields do not escape the connector boundary.
203+
204+
End-to-end acceptance should verify:
205+
206+
1. The provider or test connector produces a synthetic handoff summary.
207+
2. The gateway emits a final response with one `TRANSFER_TO_AGENT` event.
208+
3. The WxCC flow assigns `MetaData.summary` to the agent-viewable variable.
209+
4. The incoming offer shows the summary before answer.
210+
5. The active interaction shows the full summary after answer.
211+
6. The call routes and completes normally when the summary is absent.
212+
213+
Use synthetic content for all nonproduction validation. Disable any terminal test probe after
214+
the test and restore the environment's approved gateway release.

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ code, not a managed connector or a production-ready service.
2424
connectors, including known sample-only placeholders.
2525
- [Testing Guide](TESTING.md): Automated tests, HTTP smoke tests, gRPC health checks, and
2626
end-to-end validation.
27+
- [BYOVA Handoff Summary](BYOVA_HANDOFF_CONTEXT.md): Provider-neutral summary metadata
28+
contract for human-agent transfer, including validated Agent Desktop behavior.
2729
- [Connector Guide](../src/connectors/README.md): Connector interface, available connectors,
2830
and extension pattern.
2931
- [Monitoring Interface](../src/monitoring/README.md): Dashboard behavior, Webex OAuth, APIs,

‎docs/images/byova-handoff-summary-active-interaction-redacted.png‎

974 KB
Loading

‎docs/images/byova-handoff-summary-incoming-offer-redacted.png‎

954 KB
Loading

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ A fully functional voice AI system where customers can:
4242
- **[Local Development](LOCAL_DEVELOPMENT.md)** - Install, run, and troubleshoot the sample locally
4343
- **[JWT Authentication](JWT_AUTHENTICATION.md)** - Configure Webex runtime token validation
4444
- **[Testing](TESTING.md)** - Run automated, HTTP, gRPC, and end-to-end tests
45+
- **[BYOVA Handoff Summary](BYOVA_HANDOFF_CONTEXT.md)** - Pass a provider-neutral handoff
46+
summary to the receiving WxCC agent
4547
- **[Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex)** - Complete step-by-step setup
4648
- **[AWS Test Deployment Considerations](AWS_TEST_DEPLOYMENT_CONSIDERATIONS.md)** - Sanitized ALB-to-EC2 test topology, Lex access, release flow, and validation boundaries
4749
- **[GECX Setup Guide](guides/byova-gecx-setup.md)** - Google CX Agent Studio integration walkthrough

0 commit comments

Comments
 (0)