Skip to main content
Glama

Conversational Insights DevKit (cxidk 2.0)

The Conversational Insights DevKit (cxidk) is an AI-native Python library, Model Context Protocol (MCP) server, and Google Agent Development Kit (ADK) integration for Google Cloud Conversational Insights (formerly Contact Center AI / CCAI Insights, part of Customer Engagement Suite).

Key Features

  • Read & Analytics APIs: Token-budgeted conversation listing (BASIC view by default), transcript retrieval with Cloud DLP / regex PII redaction, QA scorecard analysis inspection, calculate_stats, and query_metrics time-series slicing.

  • Guarded Configuration Promotion (ConfigOps): Atomic GCS bundle export, dry-run plan() with cryptographic HS256 plan_token binding, and create-only import_() across projects and regions.

  • Vendor Transcript Onboarding: Deterministic JSON Schema validation and conversion for AWS Transcribe and Genesys Cloud, plus Gemini speaker role classification (AGENT vs. CUSTOMER) via google-genai.

  • MCP Server (cxidk-mcp): Ready for Gemini CLI, Claude Code, Cursor, VS Code (stdio), and remote multi-user Cloud Run deployments (Streamable HTTP with IAP/OIDC auth, MCP elicitation confirmation, OpenTelemetry, and audit logging).

  • Google ADK Integration (cxidk.ai.adk): First-class FunctionTool (require_confirmation wired automatically), remote McpToolset, bundled SKILL.md Agent Skills, and reference agents (insights_analyst, config_promoter, qa_tuner).

Related MCP server: Teletype MCP Server

When to Use cxidk vs. google-cloud-contact-center-insights

google-cloud-contact-center-insights provides low-level auto-generated gRPC/Protobuf bindings. Use cxidk on top when building workflows, pipelines, or AI agents:

Developer / Agent Task

cxidk Python Entrypoint

MCP / ADK Tool

Aggregate call volume, sentiment, and QA metrics

cxidk.wrapper.insights.Stats

insights_calculate_stats, insights_query_metrics

Read conversations with PII masking & turn budgets

cxidk.wrapper.insights.Conversations

insights_list_conversations, insights_get_conversation

Export, dry-run plan, and promote Insights configs

cxidk.workflow.ops.ConfigOps

config_export_bundle, config_plan_import, config_apply_import

Convert AWS Transcribe or Genesys Cloud JSON

cxidk.workflow.format.Insights

transcript_validate, transcript_convert

Classify AGENT vs. CUSTOMER speaker roles

cxidk.workflow.role_recognizer.RoleRecognizer

transcript_recognize_roles

Evaluate & tune Quality AI (QAI) scorecards

cxidk.wrapper.insights.Scorecards, cxidk.workflow.insight_refinements

insights_list_scorecards, insights_get_scorecard, insights_list_scorecard_revisions, insights_list_analyses

Build confirmation-gated Google ADK agents

cxidk.ai.adk.insights_tools, cxidk.ai.skills

All 19 @cx_tool functions

Requirements & Installation

Requires Python 3.11+.

python3 -m venv .venv
source .venv/bin/activate

# Core SDK
pip install cxidk

# With MCP server + Google ADK + Speech + DLP extras
pip install "cxidk[mcp,adk,speech,dlp]"

# Local editable install for contributors
pip install -e ".[all,dev]"

Quickstart 1: Python SDK (CxContext & Read APIs)

from cxidk import CxContext
from cxidk.ai.tools import insights_calculate_stats, insights_list_conversations

cx = CxContext(project_id="my-gcp-project", location="us-central1")

stats = insights_calculate_stats(filter='medium="PHONE_CALL"', cx=cx)
print(stats.stats)

page = insights_list_conversations(page_size=10, cx=cx)
for convo in page.conversations:
    print(convo.get("name"))

Quickstart 2: Gemini CLI Extension & Local MCP Server (stdio)

Authenticate with Application Default Credentials:

gcloud auth application-default login

Install in one command as a Gemini CLI Extension (wires cxidk-mcp, environment settings, and all 4 Agent Skills automatically):

gemini extensions install https://github.com/GoogleCloudPlatform/conversational-insights-devkit

Or add cxidk-mcp directly to Gemini CLI (~/.gemini/settings.json), Claude Desktop / Claude Code, VS Code, or Cursor via uvx (or an installed .venv):

{
  "mcpServers": {
    "cxidk": {
      "command": "uvx",
      "args": ["--from", "cxidk[mcp]", "cxidk-mcp", "--transport", "stdio"],
      "env": {
        "CXIDK_PROJECT_ID": "your-gcp-project",
        "CXIDK_LOCATION": "us-central1"
      }
    }
  }
}

Write tools are disabled by default. Pass "--allow-writes" (or set CXIDK_ALLOW_WRITES=true) to enable guarded promotion and ingestion tools with interactive MCP elicitation confirmation.

Quickstart 3: Google ADK Agents

from cxidk import CxContext
from cxidk.ai.adk import build_insights_analyst_agent, build_config_promoter_agent

cx = CxContext(project_id="my-gcp-project", location="us-central1")

# Read-only analyst agent with redacted transcript defaults
analyst = build_insights_analyst_agent(cx=cx)

# Guarded release agent (requires plan_token + ADK ToolConfirmation on writes)
promoter = build_config_promoter_agent(
    cx=cx,
    allowed_projects=["dev-insights", "prod-insights"],
)

Quickstart 4: Vendor Transcript Conversion & Ingestion

import json
import uuid
from cxidk.workflow import format as cx_format
from cxidk.workflow import role_recognizer as rr
from cxidk.wrapper import insights, speech, storage

project_id = "your-gcp-project"
location = "us-central1"
bucket_name = "your-insights-staging-bucket"
parent = f"projects/{project_id}/locations/{location}"

# Convert an AWS Transcribe JSON payload locally
with open("tests/integration/data/aws_transcript.json", "r", encoding="utf-8") as f:
    aws_payload = json.load(f)

insights_json = cx_format.Insights().from_aws(transcript=aws_payload)

# Upload to GCS and ingest into CCAI Insights
gcs = storage.Gcs(project_name=project_id, bucket_name=bucket_name)
blob_name = f"{uuid.uuid4()}.json"
gcs.upload_blob(file_name=blob_name, data=json.dumps(insights_json))

ingestor = insights.Ingestion(
    parent=parent,
    transcript_path=f"gs://{bucket_name}/{blob_name}",
)
operation = ingestor.single(language_code="en-US")
print(f"Ingestion operation started: {operation.name}")

Cloud Run & Terraform Deployment

Documentation for AI Systems

  • llms.txt: Concise machine-readable index of Python SDK modules, registered MCP/ADK tools, resources, prompts, and Agent Skills (also accessible offline via cxidk.get_llms_txt() or cxidk-mcp --print-llms-txt).

  • llms-full.txt: Self-contained full-context Markdown bundle inlining quickstarts, SDK & tool schemas, filter syntax, and SKILL.md playbooks.

  • AGENTS.md / GEMINI.md / CLAUDE.md: Contributor & coding-agent guardrails.

  • GEMINI_EXTENSION.md & gemini-extension.json: Gemini CLI Extension runtime context and configuration manifest.

  • src/cxidk/ai/skills/ (mirrored at skills/): Portable SKILL.md playbooks.

License

Distributed under the Apache 2.0 License. See LICENSE.txt for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants read-only access to Sprinklr data via MCP, allowing querying reports, searching cases, and calling Sprinklr API endpoints.
      8 npm
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to find and read customer conversations, look up profiles, send replies, manage workspace metadata, and handle daily support workflows. It also supports triage, drafting, escalation, and handover tasks through MCP tools, prompts, and resources.
      72 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to investigate stuck orders and billing issues, read customer conversations, connect telehealth support tools, review evidence, and prepare proposed actions for human approval through a hosted, OAuth-protected MCP endpoint.
      MIT