Agentic Endpoints

The Qualytics agentic endpoints bring the same conversational AI capabilities available through MCP directly into your applications and workflows. They use the AI provider configured for your deployment, which can be the Qualytics-managed provider or a supported external provider.

Overview

While the MCP integration is designed for interactive AI assistants like Claude Desktop, the agentic endpoints enable you to:

• Build custom applications that leverage natural language for data quality tasks
• Add AI-assisted data quality steps to existing workflows
• Create internal tools and chatbots that interact with your data infrastructure
• Use the AI provider and business context configured for your deployment

The agentic endpoints provide the same capabilities as MCP, including datastore exploration, data transformations, quality check creation, and anomaly investigation, through standard REST calls. Available actions still follow the authenticated user's Qualytics permissions.

Authentication

All agentic endpoints require authentication using your Qualytics Personal API Token (PAT) or a designated service account token.

Include the token in the Authorization header:

Authorization: Bearer YOUR_QUALYTICS_API_TOKEN

For instructions on generating a token, see Tokens.

LLM Configuration

Before using the agentic endpoints, configure an AI provider for the deployment. The Qualytics-managed provider does not require a separate model or API key. External providers require the credentials and provider-specific settings shown in the configuration form.

Supported Providers

The agentic endpoints support the Qualytics-managed provider and a range of external providers. For the current list, see Supported LLM Providers in the Add Integration guide.

Common providers include:

• Qualytics: managed provider with no separate model or API key to configure
• OpenAI: GPT-4o, GPT-4, o1, o3
• Anthropic: Claude Sonnet, Claude Opus, Claude Haiku
• Google Gemini: Gemini 2.0 Flash, Gemini 2.5 Pro
• Amazon Bedrock: Claude, Titan, and other models via AWS
• Google Vertex AI: Gemini models via GCP
• Groq: Llama and Mixtral models
• Mistral: Mistral Large and Codestral
• DeepSeek: DeepSeek-V3 and DeepSeek-R1
• Ollama: self-hosted open-source models that use a custom Base URL

Managing LLM Configuration

AI provider configuration is managed through the Qualytics UI:

1. Navigate to Settings > Integrations in your Qualytics instance
2. Click Connect next to AgentQ
3. Select the Qualytics provider or a supported external provider
4. Complete the model, credentials, and other fields that appear for the selected provider
5. Click Save to complete the configuration

For detailed setup instructions with screenshots, see Add Integration.

Capabilities

Chat with Agent

The chat endpoint provides a streaming conversational interface for exploring and managing data quality. This is the most flexible endpoint and supports free-form natural language interactions with streamed responses.

curl -X POST "https://your-instance.qualytics.io/api/agent/chat" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What tables are in our sales_db datastore and what quality checks do we have on them?"}
    ]
  }'

The response is delivered as a Server-Sent Events (SSE) stream following the Vercel AI Data Stream Protocol. Each event contains either text content, tool execution progress, or error information.

Multi-turn Conversations:

Pass the session_id returned in the X-Chat-Session-Id response header and send the next user message to continue an existing conversation:

curl -X POST "https://your-instance.qualytics.io/api/agent/chat?session_id=42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Set up quality checks on the orders table"}
    ]
  }'

Use Cases:

• Interactive Exploration: Build chatbots or conversational interfaces that let users explore data assets naturally
• Multi-step Workflows: Handle complex requests that require understanding context and making multiple decisions
• General Assistance: Answer questions about data quality status, anomaly patterns, or check configurations

Example Prompts:

• "Show me the schema for the customer_orders table in our PostgreSQL datastore"
• "What anomalies were detected in the last 24 hours?"
• "Which quality checks are failing most frequently across all our datastores?"
• "Help me understand why the order_total check keeps failing"

Execute Prompt

For simpler, single-turn interactions where you need a direct response without conversational context:

curl -X POST "https://your-instance.qualytics.io/api/agent/prompt" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_name": "Analyze Trends",
    "arguments": {
      "datastore_name": "analytics_warehouse",
      "timeframe": "month"
    }
  }'

Use Cases:

• Registered Workflows: Invoke a supported named prompt from an application or script
• Single-Turn Analysis: Run a supported analysis without maintaining conversation state
• Report Drafting: Generate a summary for a responsible owner to review

Transform Dataset

Create computed assets, including tables, files, or cross-datastore joins, through natural language descriptions:

curl -X POST "https://your-instance.qualytics.io/api/agent/transform-dataset" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "asset_name=daily_revenue_by_category" \
  --data-urlencode "source_description=transactions table in sales_db" \
  --data-urlencode "transformation_criteria=Aggregate daily revenue by product category, including only completed orders from the last 90 days"

Use Cases:

• Automated Data Preparation: Integrate dataset creation into ETL pipelines or data workflows
• Self-Service Analytics: Let business users create derived datasets without writing SQL
• Cross-System Integration: Build unified views across databases and data lakes programmatically

Example Descriptions:

• "Join the customers table from our Snowflake warehouse with the support_tickets table from PostgreSQL on customer_id, filtering to only active customers"
• "Create a computed file from our S3 landing zone that filters out test records and standardizes the date format"
• "Build a daily summary table that calculates average order value and order count by region"

Generate Quality Check

Create data quality checks by describing the business rule or validation requirement:

curl -X POST "https://your-instance.qualytics.io/api/agent/generate-quality-check" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -G \
  --data-urlencode "datastore_name=sales_db" \
  --data-urlencode "container_name=customers" \
  --data-urlencode "expectation=Ensure the email field is never null and matches a valid email format"

Use Cases:

• Bulk Check Creation: Programmatically establish quality checks across multiple datasets
• Rule Migration: Translate business rules from documentation into executable quality checks
• Policy-to-Check Drafting: Turn an approved policy requirement into candidate checks for subject matter review
• Data Contract Implementation: Create candidate checks from reviewed data contract specifications

Example Descriptions:

• "The order_total in the orders table should always be positive and less than 1,000,000"
• "ship_date must be after order_date for all records in the shipments table"
• "The status field should only contain 'pending', 'processing', 'shipped', or 'delivered'"
• "customer_id in transactions must exist in the customers table"

Investigate Anomaly

Get an AI-assisted interpretation of a data quality issue:

curl -X POST "https://your-instance.qualytics.io/api/agent/investigate-anomaly" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -G \
  --data-urlencode "anomaly_identifier=12345"

Use Cases:

• Alert Context: Add an AI-generated interpretation to an alert for review
• Incident Report Drafting: Draft a human-readable explanation for an incident owner to verify
• Triage Support: Suggest possible severity, contributing factors, and next steps
• Stakeholder Update Drafting: Prepare a plain-language summary for a responsible owner to review

What You Get:

• Clear explanation of what data quality rule was violated
• Context about the affected dataset and fields
• Count and pattern of affected records
• Suggested potential business impact
• Suggested investigation or remediation steps that require validation

Analyze Trends

Analyze data quality trends over time for a specific data asset:

curl -X POST "https://your-instance.qualytics.io/api/agent/analyze-trends" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -G \
  --data-urlencode "datastore_name=sales_db" \
  --data-urlencode "container_name=orders" \
  --data-urlencode "timeframe=month"

Use Cases:

• Quality Reporting: Generate trend reports for stakeholders and management
• Improvement Tracking: Measure the impact of quality initiatives over time
• Regression Detection: Identify when quality metrics started declining

Get Suggestions

Retrieve AI-generated contextual suggestions for the chat interface:

curl -X GET "https://your-instance.qualytics.io/api/agent/suggestions" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Returns a list of suggested prompts based on the available tools and data sources. Useful for building guided user experiences.

List Supported Models

Retrieve the list of supported LLM providers and their available models:

curl -X GET "https://your-instance.qualytics.io/api/agent/supported-models" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Returns provider metadata including display names, available models, whether the provider accepts arbitrary model names, whether it omits model selection, and whether it requires a custom Base URL. Use this endpoint to dynamically build provider selection interfaces.

Check LLM Configuration Status

Check whether an LLM provider is configured without retrieving the full configuration:

curl -X GET "https://your-instance.qualytics.io/api/agent/llm-config/status" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Returns is_configured (boolean) and model_name (if configured). This lightweight endpoint is useful for conditionally rendering UI elements.

Integration Patterns

Review-Assisted Quality Check Setup

When onboarding a new data source, use the chat endpoint to ask for candidate checks based on the available schema information. Present the candidates to a qualified reviewer, then call POST /api/agent/generate-quality-check only for approved business expectations. The endpoint accepts datastore_name, container_name, and expectation as query parameters.

AI-Assisted Anomaly Alerts

Call POST /api/agent/investigate-anomaly with anomaly_identifier as a query parameter to add AI-generated context to an alert. Label the interpretation as AI-generated and route it to the responsible owner for validation before treating suggested causes, impact, or next steps as confirmed.

Self-Service Data Preparation

Build an internal tool that lets analysts request datasets through natural language. Call POST /api/agent/transform-dataset with asset_name, source_description, and transformation_criteria as query parameters. Review the requested sources and transformation before the call, then validate the created asset before using it downstream.