cxas-loss-analysis

Name: cxas-loss-analysis
Author: GoogleCloudPlatform

24installs64forks

How to install cxas-loss-analysis?

googlecloudplatform/cxas-scrapi/cxas-loss-analysis

$npx -y skills add GoogleCloudPlatform/cxas-scrapi --skill cxas-loss-analysis

Installs into the current project.

Summary

Retrieves non-contained CCAI Insights conversations (losses), uses agent intelligence to cluster them into common failure patterns, and generates a markdown report. Use when you need to analyze failure patterns and build targeted regression/evaluation reports.

Files · 1

View on GitHub

SKILL.md

1	# Insights Loss Analysis & Report Generator
2
3	This skill instructs you (the AI Agent) to retrieve recent conversations from CCAI Insights, isolate escalated/non-contained sessions (losses), analyze their root causes to group them into failure patterns, and write a professional Markdown report.
4
5	---
6
7	## Execution Routine
8
9	Follow these steps in exact sequence:
10
11	### Step 1: Parameter Verification
12	Verify that the user has provided the following required parameters:
13	- `project_id`: GCP Project ID hosting Insights.
14	- `location`: Insights location (e.g., `us`).
15	- `app_id`: Target CXAS App ID (e.g., `db9ee866-28db-458b-b835-78137c974779`).
16	- `output_dir`: Directory where the final report and test cases will be saved.
17
18	And the following optional parameters if they wish to scope the analysis:
19	- `start_time`: RFC 3339 timestamp for start of time period (e.g., `2026-05-20T00:00:00Z`).
20	- `end_time`: RFC 3339 timestamp for end of time period (e.g., `2026-05-26T23:59:59Z`).
21	- `filter`: Custom API filter string to apply (overrides the default loss filter `-labels.sessionContained="true"`).
22	- `limit`: Maximum conversations to retrieve and process (default: 500).
23
24	### Step 2: Extract Loss Transcripts
25	Run the lightweight data-extraction script to dump the loss transcripts into chunked JSON files in your workspace.
26
27	Command Template:
28	```bash
29	python3 -P .agents/skills/cxas-loss-analysis/scripts/fetch_losses.py \
30	--project-id "{project_id}" \
31	--location "{location}" \
32	--app-id "{app_id}" \
33	--limit {limit} \
34	--output-file "{output_dir}/raw_losses.json" \
35	[--start-time "{start_time}"] \
36	[--end-time "{end_time}"] \
37	[--filter "{filter}"]
38	```
39
40	Note: Always run python using the virtual environment's executable with the `-P` flag (e.g., `.venv/bin/python -P`) to avoid path pollution.
41
42	### Step 3: Read Transcripts & Summarize Escalations
43	Use the `view_file` or other file-reading tools to read the generated `{output_dir}/raw_losses.json` file. Extract the list of `chunks` (which contains paths to the chunked JSON files).
44
45	For each chunk file in the `chunks` list:
46	1. Read the chunk file to load the batch of transcripts.
47	2. For each conversation transcript:
48	a. Analyze the conversation between the customer (`user`) and the virtual agent (`agent`).
49	b. Identify if the user displayed "AI aversion":
50	- Definition: Sessions where the user did not meaningfully engage with the agent or expressed a strong preference for a human agent (e.g., immediately asking for "human", "agent", "representative" in the first 1-2 turns without describing their issue, or explicitly stating they do not want to talk to an AI/robot).
51	- If "AI aversion" is detected, mark this session as ignored from the core loss analysis. Note the reason (e.g., "AI aversion: User demanded human agent immediately").
52	c. For non-ignored genuine losses:
53	- Identify why the conversation escalated or was not contained.
54	- Formulate a concise, 1-sentence primary reason for failure/escalation (max 20 words). E.g., "Virtual agent failed to authenticate the user due to repeated pin entry errors."
55
56
57	### Step 4: Cluster Failures into Loss Patterns
58	Review the complete list of genuine (non-ignored) failure reasons you generated in Step 3. Using your analytical capabilities, group these failure reasons into 8 to 10 distinct, mutually exclusive failure patterns to provide granular insights.
59
60	For each pattern, define:
61	1. Pattern ID: A simple key (e.g., `pattern_1`, `pattern_2`, ...).
62	2. Name: A short, descriptive name (e.g., "Authentication Loop", "Unsupported Customer Intent", "Agent Transfer on Disambiguation").
63	3. Description: A clear 1-2 sentence description explaining the pattern and what triggers it.
64
65
66	### Step 5: Categorize All Sessions
67	Map every analyzed `conversation_id` to either:
68	- One of the 8 to 10 defined failure patterns.
69	- `ignored_ai_aversion` if the user displayed AI aversion.
70
71	Keep track of this mapping for the final report.
72
73	### Step 6: Write the Markdown Report
74	Compile your analysis into a structured Markdown report and write it to `{output_dir}/loss_patterns_report.md`. Use the following structure:
75
76	```markdown
77	# Loss Patterns Analysis Report
78
79	Project: `{project_id}`
80	App ID: `{app_id}`
81
82	## Executive Summary
83
84	A sample of up to {limit} conversations matching the filter was selected for detailed manual analysis and clustering to identify key patterns.
85
86	## Loss Patterns Distribution
87
88	\| Pattern ID \| Name \| Count \| Percentage of Genuine Losses \|
89	\| --- \| --- \| --- \| --- \|
90	\| `pattern_1` \| Pattern Name \| Count \| Pct% \|
91	\| ... \| ... \| ... \| ... \|
92
93	*Note: Ignored AI aversion sessions

People who liked this also viewed

6 picks

Type

cxas-loss-analysis

24installs64forks

View on GitHub

How to install cxas-loss-analysis?

googlecloudplatform/cxas-scrapi/cxas-loss-analysis

$npx -y skills add GoogleCloudPlatform/cxas-scrapi --skill cxas-loss-analysis

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Insights Loss Analysis & Report Generator
2
3	This skill instructs you (the AI Agent) to retrieve recent conversations from CCAI Insights, isolate escalated/non-contained sessions (losses), analyze their root causes to group them into failure patterns, and write a professional Markdown report.
4
5	---
6
7	## Execution Routine
8
9	Follow these steps in exact sequence:
10
11	### Step 1: Parameter Verification
12	Verify that the user has provided the following required parameters:
13	- `project_id`: GCP Project ID hosting Insights.
14	- `location`: Insights location (e.g., `us`).
15	- `app_id`: Target CXAS App ID (e.g., `db9ee866-28db-458b-b835-78137c974779`).
16	- `output_dir`: Directory where the final report and test cases will be saved.
17
18	And the following optional parameters if they wish to scope the analysis:
19	- `start_time`: RFC 3339 timestamp for start of time period (e.g., `2026-05-20T00:00:00Z`).
20	- `end_time`: RFC 3339 timestamp for end of time period (e.g., `2026-05-26T23:59:59Z`).
21	- `filter`: Custom API filter string to apply (overrides the default loss filter `-labels.sessionContained="true"`).
22	- `limit`: Maximum conversations to retrieve and process (default: 500).
23
24	### Step 2: Extract Loss Transcripts
25	Run the lightweight data-extraction script to dump the loss transcripts into chunked JSON files in your workspace.
26
27	Command Template:
28	```bash
29	python3 -P .agents/skills/cxas-loss-analysis/scripts/fetch_losses.py \
30	--project-id "{project_id}" \
31	--location "{location}" \
32	--app-id "{app_id}" \
33	--limit {limit} \
34	--output-file "{output_dir}/raw_losses.json" \
35	[--start-time "{start_time}"] \
36	[--end-time "{end_time}"] \
37	[--filter "{filter}"]
38	```
39
40	Note: Always run python using the virtual environment's executable with the `-P` flag (e.g., `.venv/bin/python -P`) to avoid path pollution.
41
42	### Step 3: Read Transcripts & Summarize Escalations
43	Use the `view_file` or other file-reading tools to read the generated `{output_dir}/raw_losses.json` file. Extract the list of `chunks` (which contains paths to the chunked JSON files).
44
45	For each chunk file in the `chunks` list:
46	1. Read the chunk file to load the batch of transcripts.
47	2. For each conversation transcript:
48	a. Analyze the conversation between the customer (`user`) and the virtual agent (`agent`).
49	b. Identify if the user displayed "AI aversion":
50	- Definition: Sessions where the user did not meaningfully engage with the agent or expressed a strong preference for a human agent (e.g., immediately asking for "human", "agent", "representative" in the first 1-2 turns without describing their issue, or explicitly stating they do not want to talk to an AI/robot).
51	- If "AI aversion" is detected, mark this session as ignored from the core loss analysis. Note the reason (e.g., "AI aversion: User demanded human agent immediately").
52	c. For non-ignored genuine losses:
53	- Identify why the conversation escalated or was not contained.
54	- Formulate a concise, 1-sentence primary reason for failure/escalation (max 20 words). E.g., "Virtual agent failed to authenticate the user due to repeated pin entry errors."
55
56
57	### Step 4: Cluster Failures into Loss Patterns
58	Review the complete list of genuine (non-ignored) failure reasons you generated in Step 3. Using your analytical capabilities, group these failure reasons into 8 to 10 distinct, mutually exclusive failure patterns to provide granular insights.
59
60	For each pattern, define:
61	1. Pattern ID: A simple key (e.g., `pattern_1`, `pattern_2`, ...).
62	2. Name: A short, descriptive name (e.g., "Authentication Loop", "Unsupported Customer Intent", "Agent Transfer on Disambiguation").
63	3. Description: A clear 1-2 sentence description explaining the pattern and what triggers it.
64
65
66	### Step 5: Categorize All Sessions
67	Map every analyzed `conversation_id` to either:
68	- One of the 8 to 10 defined failure patterns.
69	- `ignored_ai_aversion` if the user displayed AI aversion.
70
71	Keep track of this mapping for the final report.
72
73	### Step 6: Write the Markdown Report
74	Compile your analysis into a structured Markdown report and write it to `{output_dir}/loss_patterns_report.md`. Use the following structure:
75
76	```markdown
77	# Loss Patterns Analysis Report
78
79	Project: `{project_id}`
80	App ID: `{app_id}`
81
82	## Executive Summary
83
84	A sample of up to {limit} conversations matching the filter was selected for detailed manual analysis and clustering to identify key patterns.
85
86	## Loss Patterns Distribution
87
88	\| Pattern ID \| Name \| Count \| Percentage of Genuine Losses \|
89	\| --- \| --- \| --- \| --- \|
90	\| `pattern_1` \| Pattern Name \| Count \| Pct% \|
91	\| ... \| ... \| ... \| ... \|
92
93	*Note: Ignored AI aversion sessions

People who liked this also viewed

6 picks

Type