Create dataflow AI agent skill

Workflow

Follow these steps in order. Do not skip steps. Do not call creation tools until all required information is confirmed.

Step 1: Parse User Intent

Extract from the user’s request:

• Source type — what system they want to pull data from (e.g., HubSpot, Google Ads, Stripe)
• Data object / entity — what data they want (e.g., deals, campaigns, invoices)
• Filters — date ranges, status filters, or other constraints
• Fields — specific columns/properties requested, if any
• Destination type — where data should go (e.g., Google Sheets, BigQuery). If not mentioned, ask.

If the request is too vague to act on, ask one targeted clarifying question. Do not ask open-ended questions.

Step 2: Check Templates

Call list-templates filtered by the requested source/metric to see if a pre-built template exists.

If a relevant template matches the user’s request closely → take the fast path. Explain what the template covers and confirm with the user that it matches their intent. On confirmation, call create-dataflow-from-template with the template ID. The result is a pre-configured dataflow. Some follow-up may still be needed (destination credentials, target sheet/table) — handle those with update-dataflow-source / update-dataflow-destination, then jump to Step 13 to report. Skip Steps 3–12.

If a template exists but only partially matches (e.g., right source but wrong entity, or a dashboard template when user just wants raw data) → mention it briefly as an option, but default to proceeding with custom creation. Example: “There’s a HubSpot Sales Dashboard template that includes deal data — want me to start from that, or set up a custom dataflow for just the fields you need?”

If no relevant template → proceed to Step 3 without mentioning templates.

Step 3: Validate Source Integration

Call list-integrations(type: "source") to verify the requested source is available.

If source is not available → tell the user. List similar available sources if any exist. Stop.

If source is available → record the integration_key and proceed.

Step 4: Resolve Source Credentials

Call list-credentials filtered by the source provider/type.

Step 5: Get Source Configuration Details

Call get-integration(type: "source", key: <integration_key>) to retrieve the full parameter schema: entities/reports, required vs optional params, field options, date filters, defaults, validation rules, and conditional logic.

Use this schema to:

• Map the user’s requested entity/data object to the correct parameter value
• Identify which parameters are required and which are optional
• Determine available date filter macros
• Understand field selection options

Step 6: Configure Source Parameters

Based on the schema from Step 5 and the user’s request:

1. Set required parameters — map user intent to exact parameter values from the schema. If a required parameter can’t be inferred from the request and has no sensible default, ask the user.
2. Resolve dynamic dropdowns — for any parameter the schema flags resolve_options_with_tool: true, call get-integration-field-options and pass the values listed in options_depends_on. The response gives the actual valid options (Salesforce object names, Google Ads account IDs, Stripe entity types, etc.). Pick from those — do not invent values; the API will reject anything not on the list.
3. Set optional parameters — apply sensible defaults. If you set any non-obvious optional parameters, briefly explain what you chose and why.
4. Set date filters — if the source supports date filtering and the user specified a range, map it. Use macros when appropriate:
   • {{today}}, {{yesterday}}
   • {{7daysago}}, {{30daysago}}, {{60daysago}}, {{90daysago}}
   • {{startofweek}}, {{startofmonth}}, {{startofquarter}}, {{startofyear}}
   • If no date range specified and dates are optional, use a sensible default (typically last 30 days for analytics sources, or omit for CRM-type sources where users usually want all records or filtered not by date).

Step 7: Validate Destination Integration

Call list-integrations(type: "destination") to verify the requested destination is available.

If the user hasn’t specified a destination, ask. Present common options from the available list (e.g., Google Sheets, BigQuery, Snowflake).

If destination is not available → tell the user. List available destinations. Stop.

If destination is available → record the integration_key and proceed.

Step 8: Resolve Destination Credentials

Same logic as Step 4, but for the destination provider/type.

Step 9: Get Destination Configuration Details

Call get-integration(type: "destination", key: <integration_key>) to retrieve destination parameter schema.

Configure destination parameters based on the schema and user’s request (e.g., spreadsheet URL, sheet name, BigQuery dataset/table, write mode). For any parameter flagged resolve_options_with_tool: true (BigQuery dataset list, available Google Sheets, Snowflake schema list, etc.), call get-integration-field-options to fetch the valid options before picking a value.

Step 10: Generate Dataflow Name

Create a descriptive name: {Source} – {Entity/Report} → {Destination}

Examples:

• “HubSpot – Deals → Google Sheets”
• “Google Ads – Campaign Performance → BigQuery”
• “Stripe – Invoices → Google Sheets”

Step 11: Confirm or Create

Assess request clarity. A request is “clear” when: the source, entity, destination, and credentials are all unambiguous, and all required parameters could be set from the user’s request or sensible defaults.

If the request is clear → skip confirmation. Proceed directly to Step 12. After creation, report what you configured (Step 13) so the user can request changes if needed.

If the request is ambiguous — you made non-obvious choices, picked between multiple valid interpretations, or set unusual optional parameters — present a summary first:

**Dataflow:** {name}
**Source:** {source_name} (credential: {credential_name})
**Entity:** {entity_label}
**Parameters:** {key params summary — date range, filters, fields if specified}
**Destination:** {destination_name} (credential: {credential_name})
**Destination settings:** {key destination params}

Should I create this dataflow?

Wait for user confirmation before proceeding.

Step 12: Create Dataflow

Execute in sequence:

1. create-dataflow(name) → get dataflow_id
2. create-dataflow-source(dataflow_id, integration_key, credential_id, params) → get source id
3. create-dataflow-destination(dataflow_id, integration_key, credential_id, params) → get destination id

If any step fails, report the error clearly. Do not proceed to the next step on failure.

Step 13: Report Result

After successful creation, confirm:

• Dataflow name and ID
• Source and destination configured
• Key parameters applied
• Any defaults or assumptions made
• Remind the user they can run the dataflow when ready, or set up a schedule in Coupler.io

Do NOT automatically call run-dataflow. Let the user decide.

Handling Changes After Creation

If the user wants to modify source or destination configuration after the dataflow is created:

• Use update-dataflow-source or update-dataflow-destination with the relevant id and new params
• These tools merge new params with existing ones — you don’t need to resend the full configuration

Error Handling

Source not found:

Source “{name}” is not available in your Coupler.io account. Available sources include: {list top relevant matches}. Would you like to use one of these?

No credentials:

No credentials connected for {source_name}. Connect your account in Coupler.io → Settings → Connections, then try again.

Invalid parameter value:

The value “{value}” isn’t valid for {param_name}. Available options: {list from schema}. Which should I use?

Incompatible parameters:

{param_A} and {param_B} can’t be used together for this source. I’ll use {param_A} as specified. Let me know if you’d prefer {param_B}.

Tool call failure:

Failed to {action}: {error message}. {Suggested next step or workaround if applicable}.

Guidelines

• Be concise. Explain non-obvious decisions; don’t narrate obvious ones.
• When multiple valid interpretations exist, state your assumption and offer the alternative.
• Never fabricate parameter values, field names, or integration keys. Always use values returned by the discovery tools.
• If get-integration returns a complex schema, summarize the key choices for the user rather than dumping raw output.
• One targeted question at a time. Do not present walls of options.