integration-advisor（整合顾问）

Integration Advisor

Purpose

Guides users from "I want to connect X" to a fully configured, running integration. Goes beyond basic CRUD to advise on which workflow to use, how to map fields intelligently, and how to configure the integration for their specific use case. Lytics has 110+ providers with different auth methods, config shapes, and field mapping patterns -- the advisor navigates this complexity.

Supports:

• Exports: "Export my high-value audience to Facebook Custom Audiences"
• Imports: "Import contacts from Salesforce"
• Enrichment: "Enrich profiles with Clearbit data"

Environment

Requires authenticated API access. See ../references/auth.md for credential resolution.

Integration Architecture

Integrations follow a three-layer model:

Provider -- what platform
  → Auth -- how to authenticate
    → Connection -- optional, for data source integrations
      → Job -- what to do, runs a specific workflow

Flow

Step 1: Understand the Goal

Classify the user's intent:

• Platform name (Facebook, Salesforce, Google, etc.)
• Direction: import, export, or enrichment
• Data type: audiences, events, profiles, conversions
• Any specific segment references

Step 2: Discover Provider

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/provider" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Find the matching provider by name. If ambiguous, show matching providers and ask user to select. Note whether the provider shows is_connected: true (auth already exists).

Step 3: Check Existing Auth and Connections

# Check for existing auth credentials
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/auth" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Check for existing connections
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

• If valid auth exists for this provider, plan to reuse it
• If a connection exists, check if it's suitable
• If no auth exists, guide the user based on auth method:

Important: OAuth flows cannot be completed in the CLI. Always direct users to the Lytics UI for OAuth authorization, then pick up the created auth_id via the API.

Step 4: Recommend Workflow

Each provider may have multiple workflows. Recommend the right one based on the user's goal:

If multiple workflows could apply, explain the tradeoffs:

"Facebook has two export options: 1. Custom Audiences -- syncs a segment as a Facebook audience for ad targeting 2. Conversion API -- sends conversion events for attribution For your goal of retargeting lapsed users, Custom Audiences is the right choice."

Step 5: Analyze Field Mappings

For exports -- cross-reference Lytics schema against the target platform's accepted fields:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Suggest mappings based on field name similarity and type compatibility. Check field coverage in the target segment to predict match rates:

"I'll map these Lytics fields to Facebook: - email -> EMAIL (92% coverage -- good for match rates) - first_name -> FN (85% coverage) - last_name -> LN (85% coverage) - phone -> PHONE (45% coverage -- supplementary matches)"

For imports -- scan the external data source schema:

# List tables in the connection
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Get column schema for a specific table
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/schema/${TABLE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Sample data to verify
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection/${CONNECTION_ID}/scan" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM table LIMIT 5", "primary_keys": ["user_id"]}'

Suggest field mappings from external columns to Lytics schema fields:

• Auto-match by name similarity (e.g., email_address -> email)
• Flag potential identity fields (email, user_id, phone)
• Warn about unmapped fields and suggest whether to include them

Step 6: Check Segment (for exports)

If the user mentioned a segment, verify it exists:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

If no segment specified for an export, suggest:

"You'll need a segment to export. Would you like me to help you build one? I can analyze your data and recommend the best audience for your goal." Then hand off to audience-advisor skill or audience-builder skill.

Step 7: Build Job Config and Confirm

Assemble the complete job configuration and present using the confirmation-gate pattern:

## Proposed Integration: Export High-Value Users to Facebook Custom Audiences

**Workflow**: facebook_custom_audiences
**Auth**: Facebook OAuth (connected as marketing@acme.com)
**Segment**: High Value Customers (12,400 users)

**Field Mappings**:
  email -> EMAIL
  first_name -> FN
  last_name -> LN

**Schedule**: Continuous sync

Then show the raw API payload:

{
  "name": "Export High Value to Facebook",
  "workflow": "facebook_custom_audiences",
  "config": {
    "segment_id": "abc123",
    "field_mappings": { ... }
  },
  "auth_ids": ["auth_456"]
}

Step 8: Execute on Approval

Create resources in dependency order:

# Create job
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${WORKFLOW}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... approved config ... }'

For imports that need a new connection, create the connection first:

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/connection" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... connection config ... }'

Step 9: Verify

After creation, check job status:

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Report initial status and suggest monitoring:

"Job created and running. Initial status: active. Check back in a few minutes for first sync results, or ask me to check job status later."

Common Integration Patterns

Field Mapping Heuristics

Common Lytics-to-platform field mappings:

Error Handling

• Provider not found: List similar providers, ask user to clarify
• No auth exists: Guide to Lytics UI for OAuth, or help create API key auth
• Auth expired: Suggest re-authorizing in the Lytics UI
• No matching workflow: List available workflows for the provider
• Segment not found: Suggest creating one with audience-builder or audience-advisor
• Connection scan fails: Check auth credentials, network access to external system
• Job creation fails: Parse error, check required config fields

Dependencies

• Composes: connection-manager skill, job-manager skill, schema-discovery skill, ../references/confirmation-gate.md
• References: ../references/auth.md
• Related: audience-advisor skill, audience-builder skill (for creating segments to export)