# Dfcx Framework Ingestor

> Parsing and Ingestion directives for the Dialogflow CX (DFCX) agent structure.

- Skill: `googlecloudplatform/dfcx-framework-ingestor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add googlecloudplatform/dfcx-framework-ingestor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/dfcx-framework-ingestor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlecloudplatform/dfcx-framework-ingestor

---


# Dialogflow CX Ingestor Skill

This skill standardizes the ingestion, parsing, and behavior extraction of
conversational agents exported in the official, public Dialogflow CX (DFCX)
format.

--------------------------------------------------------------------------------

## 1. DFCX Export Package Layout

An official Dialogflow CX agent export is packaged as a `.zip` archive. When
extracted, it conforms to the following public directory layout:

```
<agent_zip_root>/
├── agent.json                       # Global agent metadata (default language, timezone, display name)
├── intents/                         # Declared intents and training phrases
│   └── <intent_name>/
│       └── <intent_name>.json       # Intent configuration
├── entityTypes/                     # Custom entity declarations
│   └── <entity_name>/
│       └── <entity_name>.json       # Entity configuration and synonyms
├── transitionRouteGroups/           # Shared flow-level transition groups
├── webhooks/                        # Declared webhooks and backend REST integrations
│   └── <webhook_name>.json          # Webhook configuration (defining target URI and credentials)
└── flows/                           # Subfolders representing individual Flows
    └── <flow_name>/                 # Flow directory (e.g., Default Start Flow, Billing)
        ├── <flow_name>.json         # Flow configuration listing flow-level transition routes and entry points
        ├── transitionRouteGroups/   # Shared transition route groups specific to this flow
        └── pages/                   # Directory containing individual page configurations
            └── <page_name>.json     # Page definition containing entry prompts, form parameters, and transitions
```

--------------------------------------------------------------------------------

## 2. Ingestion & Flow Tracing Directives

The Ingestor Agent MUST parse the extracted file structures using standard
directory traversal and JSON parsing, mapping them to the primary coverage
checklist:

### A. CUJ Mapping

*   **CUJ Discovery**: Treat each **Flow folder** under `flows/` (e.g.,
    `flows/Default Start Flow/` or `flows/Billing Flow/`) as a high-level
    **Parent CUJ**. The folder's directory name represents the CUJ title.

### B. Sub-intent & Trigger Extraction

For each Flow, traverse `<flow_name>.json` and all `.json` files inside its
`pages/` subdirectory:

1.  **Flow-Level Transition Routes**:
    -   Parse the `"transitionRoutes"` array inside `<flow_name>.json`.
    -   Identify each transition triggered by an intent (where `"intent"` is
        declared, e.g., `projects/.../intents/<intent_id>`).
    -   Map each unique triggered transition as a **Sub-intent / Scenario**
        (using the target page/flow name to synthesize its name).
2.  **Page-Level Transition Routes**:
    -   For each page `.json` inside `pages/`, parse the `"transitionRoutes"`
        array to map conversational branches and trigger conditions.
3.  **Form Parameter nodes**:
    -   Parse the `"form.parameters"` array inside a page JSON.
    -   Each parameter collected (e.g., email_address, postal_code) represents a
        sub-intent step in the conversational walkthrough.
4.  **Fulfillment Webhooks**:
    -   Identify `"triggerFulfillment.webhook"` inside transition routes or page
        configs.
    -   Resolve the webhook's target endpoint destination URI by looking up its
        matching configuration file inside the global `webhooks/` directory
        (e.g. `webhooks/<webhook_name>.json`'s `"genericWebService.uri"`).
    -   **Note**: Webhooks represent standard REST integrations defined as
        **toolsets** (indexed via OpenAPI specifications `open_api_schema.yaml`
        under the `toolsets/` directory).

### C. Alignment with Canonical `cxas-agent-migration` Standards

When parsing Dialogflow CX layouts, the Ingestor Agent SHOULD align the
extracted behaviors with the open-source `cxas-agent-migration` topology (N->M
agents consolidation):

1.  **Playbook/Flow to Agent Persona**: Each extracted Flow directory represents
    a distinct sub-agent boundary. Treat the flow's transitions and event
    handlers as the sub-agent's private prompt limits and routing callbacks.
2.  **Deduplicate & Group Variables**: Consolidate intent parameters and page
    forms variables using `cxas-agent-migration` Stage 1 rules (variable
    deduplication) to avoid parameter bloat in transcripts.
3.  **Topological Rewiring**: Track the source dependency graph (parent flows ->
    children flows) using `cxas-agent-migration` Stage 3 rules, ensuring that
    transitions from steering accurately reflect the legacy DFCX intent routing.

--------------------------------------------------------------------------------

## 3. Dialogue Simulation & Transcript Guidelines

When simulating conversation transcripts based on parsed DFCX folder packages,
enforce the following rules:

### A. Verbatim Prompts Extraction

To guarantee the simulated agent speaks the exact developer-defined prompts,
parse the fulfillment blocks:

1.  **Page Entry Prompts**:
    -   Read `"entryFulfillment.messages"` inside `pages/<page_name>.json`.
    -   Extract speech variants under `"text": {"text": [...]}`. The simulated
        `Agent` turn MUST output this string verbatim.
2.  **Form Slot-Filling Prompts**:
    -   Read `"initialPromptFulfillment.messages"` inside
        `"form.parameters[].fillBehavior"` in the page JSON.
    -   The simulated `Agent` turn asking for the parameter MUST output these
        prompt strings verbatim.
3.  **Transition Prompts**:
    -   Read `"triggerFulfillment.messages"` inside transition routes.

### B. Programmatic Flow Traversal & Intent Discovery

To discover conversational paths and map execution sequences:

1.  **Flow Start Point**: Access `flows/<flow_name>/<flow_name>.json` and locate
    the `"transitionRoutes"` inside the root flow config. These define the entry
    intents (e.g. `"intent": "support_request"`).
2.  **State Traversal**:
    -   For each route, trace the target node: if the target is a sub-flow (e.g.
        `"targetFlow": "flows/Billing/"`), pivot to that sub-flow config.
    -   If the target is a page (e.g. `"targetPage": "Collect Email"`), load and
        parse the page configuration file `pages/Collect Email.json`.
3.  **Fulfillment Sequence Tracking**:
    -   Trace visited pages in chronological order along the path to extract the
        sequential webhook invocations (`triggerFulfillment.webhook`) and
        parameter mappings, mapping each valid end-to-end path as a scenario
        sequence.