Skip to main content

Conversational AI Agent

CLOUD

Multi-turn conversational AI assistant for data questions, metric definitions, asset explanations, query generation, and best practices guidance.

Overview​

The AI Agent provides conversational assistance for:

  • Data Discovery: Find assets, metrics, and terms
  • Metric Definitions: Explain how metrics are calculated
  • Asset Explanations: Understand what assets do
  • Query Generation: Generate SQL queries from questions
  • Best Practices: Get guidance on data engineering practices

Chatting with Agent​

Endpoint​

POST /api/msh/ai/agent

Chat with the AI agent.

Request:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "user_id": 1,
    "message": "How do I calculate customer lifetime value?",
    "conversation_id": null
  }' \
  https://api.msh.io/api/msh/ai/agent

Response:

{
  "success": true,
  "conversation_id": 123,
  "response": "To calculate customer lifetime value, you can use the 'metric.cltv' metric which is defined as...",
  "suggested_actions": [
    {
      "type": "view_metric",
      "label": "View CLTV Metric Definition",
      "metric_id": 5
    },
    {
      "type": "view_asset",
      "label": "View Customer Asset",
      "asset_id": 3
    }
  ]
}

Continuing Conversation​

Continue the conversation by providing the conversation_id:

Request:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "user_id": 1,
    "message": "What assets use this metric?",
    "conversation_id": 123
  }' \
  https://api.msh.io/api/msh/ai/agent

Response:

{
  "success": true,
  "conversation_id": 123,
  "response": "The CLTV metric is used by the following assets: 'customer_segments', 'retention_analysis'...",
  "suggested_actions": [
    {
      "type": "view_asset",
      "label": "View customer_segments",
      "asset_id": 7
    }
  ]
}

Suggested Actions​

The agent provides suggested actions to help you explore:

View Metric​

{
  "type": "view_metric",
  "label": "View CLTV Metric Definition",
  "metric_id": 5
}

View Asset​

{
  "type": "view_asset",
  "label": "View Customer Asset",
  "asset_id": 3
}

Execute Query​

{
  "type": "execute_query",
  "label": "Run Query",
  "query": "SELECT ..."
}

Example Conversations​

Finding Metrics​

User: "What metrics measure revenue?"

Agent: "There are several revenue metrics in your project:

  • Monthly Recurring Revenue (MRR)
  • Annual Recurring Revenue (ARR)
  • Customer Lifetime Value (CLTV)

Would you like to see the definition of any of these?"

Understanding Assets​

User: "What does the revenue asset do?"

Agent: "The revenue asset calculates monthly recurring revenue by aggregating active subscription amounts. It joins subscriptions with plans and groups by month.

Upstream assets: subscriptions, plans Downstream assets: revenue_dashboard, forecast_model

Would you like to see the SQL definition?"

Generating Queries​

User: "Show me revenue by region"

Agent: "I can help you query revenue by region. Here's the SQL:

SELECT region, SUM(amount) as revenue
FROM {{ ref('revenue') }}
GROUP BY region

Would you like me to execute this query?"

Best Practices​

  1. Be Specific: Ask specific questions for better responses
  2. Use Business Terms: Use glossary terms in questions
  3. Follow Suggestions: Use suggested actions to explore
  4. Continue Conversations: Build on previous responses
  5. Review Responses: Always review generated SQL before executing