How googlecloudplatform/cxas-scrapi works
1. Repository purpose
- This is a Python 3.10+ toolkit for CX Agent Studio (CXAS). It is not a single app; it is a library + CLI + docs + examples + agent skills repo centered on automating agent lifecycle tasks: create, inspect, lint, evaluate, migrate, trace, and report.
2. Primary runtime boundary
- The main packaged code lives under src/cxas_scrapi. That package is the product boundary consumed by notebooks, local scripts, Cloud Run / Cloud Functions jobs, and CLI commands.
- Authentication is externalized: the code relies on Google Cloud Application Default Credentials or an explicit service account key path.
3. Core SDK layer
- src/cxas_scrapi/core contains the resource-oriented API surface: apps, agents, tools, guardrails, deployments, sessions, variables, versions, evaluations, traces, conversation_history, and changelogs.
- These modules are the main integration layer with CXAS resources and likely map directly to remote API entities and operations.
4. Utility / platform integration layer
- src/cxas_scrapi/utils holds shared plumbing: pagination/flattening helpers, linting rules, report generation, dependency management, Google Sheets / GCS / Secret Manager helpers, Gemini-related helpers, and tracing helpers.
- This layer is where cross-cutting concerns live, so architecture-wise it sits between the core SDK and higher-level workflows.
5. CLI boundary
- src/cxas_scrapi/cli provides command-line entry points such as app management, local creation, migration, insights, and trace commands.
- The CLI is the operational façade over the SDK: it orchestrates core operations, runs validators, and emits reports rather than introducing separate business logic.
6. Evaluation subsystem
- src/cxas_scrapi/evals provides evaluation runners for different test types: callback_evals, guardrail_evals, simulation_evals, tool_evals, and turn_evals.
- Evals are data-driven and appear to consume YAML/JSON test definitions from the repo’s examples/assets. They generate metrics and reports for agent behavior, not just unit-test code.
7. Migration subsystem
- src/cxas_scrapi/migration is a focused pipeline for converting legacy Dialogflow CX artifacts into CXAS-compatible structures.
- It includes extract/transform/build stages: dependency analysis, parameter extraction, playbook/tool conversion, topology linking, visualization, artifact building, and report generation. This is a distinct architecture branch from runtime SDK usage.
8. Shared support utilities for analysis and reporting
- src/cxas_scrapi/utils/tracing handles trace configuration, cloud logging, audio analysis, and trace report generation.
- src/cxas_scrapi/utils/lint_rules defines the linting policy surface for instructions, callbacks, tools, structure, and evals. This is the repo’s validation boundary before artifacts are pushed or promoted.
9. Example and template artifacts
- examples/ contains complete reference projects such as bella_notte, including agent definitions, callback code, tool definitions, eval suites, and evaluation datasets/expectations.
- .agents/skills/cxas-agent-foundry/assets/project-template is a scaffolded template for generating new CXAS apps; it mirrors the same conceptual structure as the examples, which helps define the expected architecture of a CXAS project.
10. Agent Skills as an operational layer
- .agents/skills/... contains “skills” for AI-assisted workflows such as scaffolding, lint fixing, TDD writing, coverage analysis, and failure triage.
- These are not product runtime code; they are developer workflow accelerators that wrap repo conventions and scripts.
11. Documentation and reference architecture
- docs/ and diagrams/ are substantial and part of the architecture itself: they document API surfaces, CLI commands, design guidance, evaluation patterns, slot-filling workflows, and migration concepts.
- The repo is intentionally documentation-heavy, suggesting the package is meant to be operated by engineers and agent builders rather than end users only.
12. Verification and CI boundaries
- tests/ mirrors the package structure and validates core APIs, eval runners, migration flows, utilities, and tracing/reporting code.
- .github/workflows/ plus pre-commit and release tooling indicate a standard package lifecycle: linting, unit tests, docs build, and release automation.
13. High-level data flow
- A typical flow is: CXAS remote resources / local artifacts / eval inputs → core and utils → cli or evals or migration pipelines → reports, generated artifacts, or validation results.
- Authentication and external integrations are injected at the edges; most internal modules operate on structured resource data and generated files.
14. Architectural shape
- The repo is best diagrammed as a hub-and-spoke Python platform:
- hub: src/cxas_scrapi
- spokes: CLI, evals, migration, docs/examples, agent skills, tests
- external dependencies: Google Cloud / CX Agent Studio APIs, ADC credentials, optional Gemini/Sheets/GCS/Secret Manager integrations.
Main entry points: cxas_scrapi cxas_scrapi · utils Utilities · core Core API · migration Migration
Components 18
Runtime package
Packaged Python code under src/cxas_scrapi.
- cxas_scrapi · Top-level library boundary consumed by CLI, notebooks, scripts, and jobs.
src/cxas_scrapi - Core API · Resource-oriented client surface for CXAS entities and operations.
src/cxas_scrapi/core - Resources · Apps, agents, tools, guardrails, deployments, sessions, variables, versions.
src/cxas_scrapi/core - Observability · Evaluations, traces, conversation history, changelogs, insights, scorecards.
src/cxas_scrapi/core - Common auth · Shared API plumbing, auth handling, callbacks, GitHub integration, and audio helpers.
src/cxas_scrapi/core - Utilities · Cross-cutting helpers for pagination, reports, dependency handling, cloud integrations, and Gemini.
src/cxas_scrapi/utils - Lint rules · Rule set for instructions, callbacks, tools, structure, schemas, and evals.
src/cxas_scrapi/utils/lint_rules - Tracing utils · Trace config, cloud logging, audio analysis, and trace report generation.
src/cxas_scrapi/utils/tracing - Local create · Helpers for local project creation and template assembly.
src/cxas_scrapi/utils/local - Evals · Runner family for callback, guardrail, simulation, tool, and turn evals.
src/cxas_scrapi/evals - Migration · Dialogflow CX to CXAS conversion pipeline with analysis, conversion, linking, and reporting.
src/cxas_scrapi/migration - CLI · Command-line entry points for app operations, local creation, migration, insights, and trace workflows.
src/cxas_scrapi/cli - Prompts · Shared prompt text used by migration and agent workflows.
src/cxas_scrapi/prompts
Docs, examples, skills
Reference material, scaffolded projects, and agent workflow assets.
- Examples · Complete sample CXAS projects, eval suites, and exported artifacts.
examples - Agent skills · AI-assisted scaffolding, linting, TDD, coverage, and triage skills plus templates.
.agents/skills - Docs · API docs, guides, design notes, diagrams, tutorials, and CLI references.
docs
Verification and release
Tests, CI, packaging, and release automation.
- Tests · Mirrors package structure to validate core clients, evals, migration, utilities, and tracing.
tests - CI and release · Workflow automation, pre-commit, release-please, packaging, and repository policy files.
.github/workflows
Connections 32
- cxas_scrapi → Core API: exposes · Primary SDK boundary.
- cxas_scrapi → Utilities: depends on · Shared infrastructure used across the package.
- cxas_scrapi → Evals: includes · Evaluation runners are part of the packaged toolkit.
- cxas_scrapi → Migration: includes · Migration pipeline is a first-class subsystem.
- cxas_scrapi → CLI: serves · CLI wraps the library surface.
- Core API → Resources: covers · Resource clients for operational CXAS entities.
- Core API → Observability: covers · History, traces, insights, and reporting entities.
- Core API → Common auth: shares · Common request/response and integration helpers.
- CLI → Core API: orchestrates · Delegates business operations to the SDK layer.
- CLI → Utilities: emits · Uses reporting, linting, and local/project helpers.
- CLI → Evals: runs · Entry points for eval execution and reporting.
- CLI → Migration: drives · Migration commands execute the conversion pipeline.
- CLI → Tracing utils: traces · Trace commands and report generation.
- Utilities → Lint rules: validates · Linting policy is centralized here.
- Utilities → Tracing utils: supports · Trace/report helpers and logging integrations.
- Utilities → Local create: supports · Project scaffolding and local setup helpers.
- Migration → Core API: reads · Consumes resource models and client data.
- Migration → Utilities: uses · Analysis, reporting, visualization, and cloud helpers.
- Migration → Prompts: guides · Prompt templates steer conversion and augmentation.
- Evals → Core API: consumes · Eval runners operate on agent/app artifacts.
- Evals → Utilities: uses · Shared evaluation and reporting utilities.
- Examples → cxas_scrapi: demonstrates · Reference projects exercise the package conventions.
- Agent skills → Examples: templates · Skills include project templates and workflow assets.
- Docs → cxas_scrapi: documents · Documentation explains the main package and commands.
- Docs → Evals: documents · Evaluation guides and API references.
- Docs → Migration: documents · Migration concepts and workflow guidance.
- Tests → cxas_scrapi: verifies · Test suite mirrors the runtime package.
- Tests → Evals: verifies · Covers eval runners and YAML-driven execution.
- Tests → Migration: verifies · Covers conversion and reporting pipeline pieces.
- Tests → Utilities: verifies · Covers shared utilities and trace helpers.
- CI and release → Tests: runs · Workflows execute tests and checks.
- CI and release → Docs: builds · Docs workflow and publishing automation.