# googlecloudplatform/cxas-scrapi architecture

> Architecture diagram of the GitHub repository googlecloudplatform/cxas-scrapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/cxas-scrapi
- Repository: https://github.com/googlecloudplatform/cxas-scrapi

## Overview

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: [`src/cxas_scrapi`](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi) (cxas_scrapi), [`src/cxas_scrapi/utils`](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils) (Utilities), [`src/cxas_scrapi/core`](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core) (Core API), [`src/cxas_scrapi/migration`](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/migration) (Migration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime package"]
  node_package_root["cxas_scrapi<br/>python package"]
  node_core_api["Core API<br/>resource clients"]
  node_core_resources["Resources<br/>entity clients"]
  node_core_observability["Observability<br/>history and trace clients"]
  node_core_common["Common auth<br/>shared client glue"]
  node_utils_layer["Utilities<br/>shared plumbing"]
  node_lint_rules["Lint rules<br/>validation policy"]
  node_tracing_utils["Tracing utils<br/>trace reporting"]
  node_local_utils["Local create<br/>project scaffolding"]
  node_evals_pkg["Evals<br/>evaluation runners"]
  node_migration_pkg["Migration<br/>dfcx pipeline"]
  node_cli_pkg["CLI<br/>command facade"]
  node_prompts_pkg["Prompts"]
end

subgraph group_content["Docs, examples, skills"]
  node_examples_dir["Examples<br/>reference projects"]
  node_skills_dir["Agent skills<br/>workflow assets<br/>[skills]"]
  node_docs_dir["Docs<br/>documentation site"]
end

subgraph group_quality["Verification and release"]
  node_tests_dir["Tests<br/>pytest suite"]
  node_ci_dir["CI and release<br/>repo automation<br/>[workflows]"]
end

node_package_root -->|"exposes"| node_core_api
node_package_root -->|"depends on"| node_utils_layer
node_package_root -->|"includes"| node_evals_pkg
node_package_root -->|"includes"| node_migration_pkg
node_package_root -->|"serves"| node_cli_pkg
node_core_api -->|"covers"| node_core_resources
node_core_api -->|"covers"| node_core_observability
node_core_api -->|"shares"| node_core_common
node_cli_pkg -->|"orchestrates"| node_core_api
node_cli_pkg -->|"emits"| node_utils_layer
node_cli_pkg -->|"runs"| node_evals_pkg
node_cli_pkg -->|"drives"| node_migration_pkg
node_cli_pkg -->|"traces"| node_tracing_utils
node_utils_layer -->|"validates"| node_lint_rules
node_utils_layer -->|"supports"| node_tracing_utils
node_utils_layer -->|"supports"| node_local_utils
node_migration_pkg -->|"reads"| node_core_api
node_migration_pkg -->|"uses"| node_utils_layer
node_migration_pkg -->|"guides"| node_prompts_pkg
node_evals_pkg -->|"consumes"| node_core_api
node_evals_pkg -->|"uses"| node_utils_layer
node_examples_dir -->|"demonstrates"| node_package_root
node_skills_dir -->|"templates"| node_examples_dir
node_docs_dir -->|"documents"| node_package_root
node_docs_dir -->|"documents"| node_evals_pkg
node_docs_dir -->|"documents"| node_migration_pkg
node_tests_dir -->|"verifies"| node_package_root
node_tests_dir -->|"verifies"| node_evals_pkg
node_tests_dir -->|"verifies"| node_migration_pkg
node_tests_dir -->|"verifies"| node_utils_layer
node_ci_dir -->|"runs"| node_tests_dir
node_ci_dir -->|"builds"| node_docs_dir

click node_package_root "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi"
click node_core_api "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core"
click node_core_resources "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core"
click node_core_observability "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core"
click node_core_common "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core"
click node_utils_layer "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils"
click node_lint_rules "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/lint_rules"
click node_tracing_utils "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/tracing"
click node_local_utils "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/local"
click node_evals_pkg "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/evals"
click node_migration_pkg "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/migration"
click node_cli_pkg "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/cli"
click node_prompts_pkg "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/prompts"
click node_examples_dir "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/examples"
click node_skills_dir "https://github.com/googlecloudplatform/cxas-scrapi/blob/main/.agents/skills"
click node_docs_dir "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/docs"
click node_tests_dir "https://github.com/googlecloudplatform/cxas-scrapi/tree/main/tests"
click node_ci_dir "https://github.com/googlecloudplatform/cxas-scrapi/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package_root,node_core_api,node_core_resources,node_core_observability,node_core_common,node_utils_layer,node_lint_rules,node_tracing_utils,node_local_utils,node_evals_pkg,node_migration_pkg,node_cli_pkg,node_prompts_pkg toneBlue
class node_examples_dir,node_skills_dir,node_docs_dir toneAmber
class node_tests_dir,node_ci_dir toneMint
```

## Components

### Runtime package

Packaged Python code under src/cxas_scrapi.

- [cxas_scrapi](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi): python package · Top-level library boundary consumed by CLI, notebooks, scripts, and jobs. · `src/cxas_scrapi`
- [Core API](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core): resource clients · Resource-oriented client surface for CXAS entities and operations. · `src/cxas_scrapi/core`
- [Resources](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core): entity clients · Apps, agents, tools, guardrails, deployments, sessions, variables, versions. · `src/cxas_scrapi/core`
- [Observability](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core): history and trace clients · Evaluations, traces, conversation history, changelogs, insights, scorecards. · `src/cxas_scrapi/core`
- [Common auth](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/core): shared client glue · Shared API plumbing, auth handling, callbacks, GitHub integration, and audio helpers. · `src/cxas_scrapi/core`
- [Utilities](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils): shared plumbing · Cross-cutting helpers for pagination, reports, dependency handling, cloud integrations, and Gemini. · `src/cxas_scrapi/utils`
- [Lint rules](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/lint_rules): validation policy · Rule set for instructions, callbacks, tools, structure, schemas, and evals. · `src/cxas_scrapi/utils/lint_rules`
- [Tracing utils](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/tracing): trace reporting · Trace config, cloud logging, audio analysis, and trace report generation. · `src/cxas_scrapi/utils/tracing`
- [Local create](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/utils/local): project scaffolding · Helpers for local project creation and template assembly. · `src/cxas_scrapi/utils/local`
- [Evals](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/evals): evaluation runners · Runner family for callback, guardrail, simulation, tool, and turn evals. · `src/cxas_scrapi/evals`
- [Migration](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/migration): dfcx pipeline · Dialogflow CX to CXAS conversion pipeline with analysis, conversion, linking, and reporting. · `src/cxas_scrapi/migration`
- [CLI](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/cli): command facade · Command-line entry points for app operations, local creation, migration, insights, and trace workflows. · `src/cxas_scrapi/cli`
- [Prompts](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/src/cxas_scrapi/prompts): llm 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](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/examples): reference projects · Complete sample CXAS projects, eval suites, and exported artifacts. · `examples`
- [Agent skills](https://github.com/googlecloudplatform/cxas-scrapi/blob/main/.agents/skills): workflow assets · AI-assisted scaffolding, linting, TDD, coverage, and triage skills plus templates. · `.agents/skills`
- [Docs](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/docs): documentation site · API docs, guides, design notes, diagrams, tutorials, and CLI references. · `docs`

### Verification and release

Tests, CI, packaging, and release automation.

- [Tests](https://github.com/googlecloudplatform/cxas-scrapi/tree/main/tests): pytest suite · Mirrors package structure to validate core clients, evals, migration, utilities, and tracing. · `tests`
- [CI and release](https://github.com/googlecloudplatform/cxas-scrapi/blob/main/.github/workflows): repo automation · Workflow automation, pre-commit, release-please, packaging, and repository policy files. · `.github/workflows`

## Connections

- 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.
