AgentQ FAQ
Frequently asked questions about AgentQ, the AI assistant built into the Qualytics platform.
General
What is AgentQ?
AgentQ is the AI-powered assistant integrated into the Qualytics platform. It uses the Model Context Protocol (MCP) and your own LLM provider to interact with your data quality infrastructure through natural language. You can ask it to explore datastores, create quality checks, investigate anomalies, run operations, send notifications, create tickets, and more — without navigating complex interfaces.
How does AgentQ work?
AgentQ connects to your configured LLM provider and uses a set of MCP tools to interact with the Qualytics platform on your behalf. When you send a message:
- A lightweight topic classifier checks whether the request is related to data quality or the Qualytics platform.
- The main agent processes your request using the LLM.
- AgentQ selects the right tools for the task from the registered tool set.
- It executes those tools against the Qualytics API — calling them one at a time or in sequence as needed.
- Results are streamed back to you in real time with per-step progress indicators.
Is my data sent to the LLM?
AgentQ sends metadata about your data assets — table names, field names, quality check configurations, anomaly details — to the LLM to process your requests. It does not send actual row data to the model. The LLM provider you configure handles this data according to their own privacy and data processing policies.
Will AgentQ act on requests outside of data quality?
No. AgentQ includes an automatic topic guardrail. Before processing a request, a lightweight LLM classifier checks whether it relates to data quality, governance, databases, anomalies, transformations, or the Qualytics platform. Requests outside these topics are declined politely with a message explaining AgentQ's scope.
Setup
What LLM providers are supported?
AgentQ supports 22+ LLM providers including OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Groq, Mistral, DeepSeek, Cohere, Ollama, OpenRouter, Perplexity, and more. See the full list with example models in the Add Integration guide.
Do I need my own LLM API key?
Yes. AgentQ uses your own LLM API key to make calls to the language model. You choose the provider, select the model, and pay your own API costs. Qualytics does not supply LLM API keys.
Is my API key validated when I save it?
Yes. When you create or update the LLM configuration, Qualytics makes a minimal test call to verify the API key and confirms connectivity to the provider before saving. You will see an error if the key is invalid or the provider is unreachable.
What is the Base URL field for?
The Base URL is an optional custom endpoint for OpenAI-compatible providers that self-host or proxy models. Use it for providers like Ollama (local), OpenRouter, LiteLLM proxy, or any other provider that exposes an OpenAI-compatible API at a custom URL.
Can AgentQ search the web?
If your configured LLM provider supports web search (e.g., certain OpenAI or Anthropic configurations), AgentQ can optionally use it to search the Qualytics documentation (userguide.qualytics.io) and related resources to answer questions about platform capabilities and best practices. This is detected automatically when you configure the integration.
Can multiple users configure different LLM providers?
No. The LLM configuration is deployment-wide. A single Manager (or Admin) configures one provider, model, and API key, and all users with Member role or higher share that configuration. Only one active LLM configuration exists at a time per deployment.
What happens if a Manager changes the LLM provider?
Existing conversation history is preserved — sessions are stored independently of the LLM configuration. The new provider takes effect immediately for every user on their next message. Different models may behave differently for the same prompts, so results may vary across providers.
What happens if I don't configure an LLM?
Without an LLM configured, AgentQ displays a "No LLM Integration Configured" message with a Configure LLM button. The platform is fully functional otherwise — only AgentQ's chat capabilities are unavailable. Follow the Add Integration guide to get started.
Usage
How do I open AgentQ?
Two ways:
- Click AgentQ in the left sidebar for the full-page chat interface.
- Use the floating action button in the bottom-right corner of any page. Press the Q key to toggle it from anywhere on the page (except while typing in an input).
What are the smart suggestions?
When you start a new conversation, AgentQ generates 3 personalized prompt suggestions using the LLM, based on your actual containers and active anomalies. These highlight common workflows like investigating anomalies, creating quality checks, and analyzing trends. Click any suggestion to use it as your opening message.
Suggestions are hidden when you open AgentQ from a page where context is already injected (e.g., from an anomaly page).
How does context injection work?
When you open AgentQ from a page that has relevant data (a datastore, container, field, quality check, or anomaly), AgentQ automatically receives that asset's identity as context. This context appears as a badge above the input box (icon + asset name). You can then ask questions like "Explain this anomaly" or "What checks exist here?" without specifying which asset you mean.
The context is embedded in your first message using invisible Unicode markers and is visible to you via the Context action button on the message after it's sent.
Can I have multiple conversations?
Yes. AgentQ supports full session management. You can start new conversations at any time, switch between sessions from the history sidebar or the floating chat dropdown, search sessions by title, and rename, archive, restore, or delete sessions.
Does AgentQ remember previous conversations?
Yes. Each session maintains its full message history. For long sessions, AgentQ compresses context automatically:
- Mechanical compression: Recent messages (last 4 turns) are kept verbatim. Older messages are truncated to short summaries.
- LLM-generated summary: Once a session reaches 10 messages, the same LLM generates a structured summary capturing key topics, decisions, and context. This is stored with the session and used when resuming.
If you notice AgentQ losing context in a very long conversation, starting a new session for a fresh context window is the most reliable approach.
What happens if I navigate away while AgentQ is generating?
The response continues streaming in the background. When you return to that session, the completed (or in-progress) response is waiting for you. You can see which sessions are still generating from the loading indicators in the session list.
Can AgentQ make changes to my platform configuration?
Yes. AgentQ can create and update quality checks, create computed assets (tables, files, joins, fields), promote assets across datastores, trigger operations (sync, profile, scan, export, materialize), manage tags, send notifications, and create tickets. All changes are tracked in the audit trail and marked with AgentQ co-authorship alongside your user identity.
Can I export AgentQ responses?
Yes. Click the Export as PDF button below any assistant message to download a formatted PDF. You can also copy any response to your clipboard.
Can I upload files to AgentQ?
Yes, when your active LLM provider supports binary content. The chat input shows an Attach icon for PDF, Word (.doc, .docx), Excel (.xls, .xlsx), CSV, TSV, JSON, XML, plain text, and Markdown files. Limits: one file per message, up to 20 MB per file. The button is shown for Anthropic, Google Gemini, Amazon Bedrock (Claude models), OpenAI, Azure OpenAI, and Heroku. See Attach a File for full details.
Are there usage limits?
Yes. To ensure fair usage and predictable costs:
| Limit | Default |
|---|---|
| Requests per minute | 10 per user |
| Concurrent streaming responses | 2 per user |
| LLM requests per execution | 300 |
| Input tokens per execution | 15,000,000 |
| Output tokens per execution | 15,000,000 |
| Total tokens per execution | 30,500,000 |
If you hit the rate limit, wait a moment and try again. If you consistently exceed token limits on a single request, try breaking it into smaller focused steps.
What happens if AgentQ makes a mistake?
Ask it to fix the result in the same conversation. For example: "That check is wrong — the field should be not-null, not unique. Please update it." AgentQ will correct the action and update the platform accordingly.
If the change was already applied to the platform and you want to revert it, you can ask AgentQ to undo it (e.g., "Delete the check you just created") or manually reverse it in the platform interface.
How much does it cost to use AgentQ?
AgentQ uses your own LLM API key — you pay your LLM provider directly based on your usage. Qualytics does not charge separately for AgentQ. Costs depend on the model you choose and how many tool calls your requests generate.
To reduce costs, use specific, focused prompts and scope requests to a particular datastore or container rather than platform-wide queries. See Best Practices for detailed guidance.
Can I share a conversation with another user?
Not directly — conversations are private to your user account. To share findings, use the Export as PDF button below any assistant message to download a formatted PDF you can share externally.
How long are conversations stored?
Conversations persist indefinitely until you delete them. Archived conversations are also kept until explicitly deleted. See Delete a Conversation for instructions on permanent removal.
What languages does AgentQ support?
AgentQ can understand and respond in any language your configured LLM model supports. The platform interface is in English, but you can write prompts in your preferred language and AgentQ will respond in kind.
MCP Integration
What is MCP?
The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools. Qualytics implements an MCP server that exposes its data quality functionality to any compatible client.
Can I connect external AI clients to Qualytics?
Yes. Beyond the built-in AgentQ, you can connect ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, Amazon Q Developer, and any MCP-compatible client directly to the Qualytics MCP server using your Personal API Token. See the Connecting External AI Clients guide for step-by-step instructions for each client.
Which external AI clients are supported?
Qualytics provides step-by-step setup guides for the following MCP clients:
| Client | Transport |
|---|---|
| ChatGPT | Streamable HTTP (native MCP support) |
| Claude Desktop | Custom Connectors (native HTTP transport) |
| Claude Code | Streamable HTTP via CLI (claude mcp add) |
| Cursor | Streamable HTTP via ~/.cursor/mcp.json |
| VS Code (GitHub Copilot) | Streamable HTTP via .vscode/mcp.json |
| Windsurf | Streamable HTTP via ~/.codeium/windsurf/mcp_config.json |
| Amazon Q Developer | Streamable HTTP via ~/.aws/amazonq/mcp.json |
Any other MCP-compatible client that supports Streamable HTTP transport can also connect. See the Connecting External AI Clients guide for full instructions.
Do external clients have the same capabilities as AgentQ?
External MCP clients share the same tool set as AgentQ — they connect to the same MCP server and have access to the same tools for exploration, quality checks, transformations, anomalies, operations, and integrations. However, features specific to the Qualytics UI (context injection, smart suggestions, session management, PDF export) are only available in the built-in AgentQ chat.
What is the difference between AgentQ, the MCP server, and the agentic endpoints?
| Component | Purpose |
|---|---|
| AgentQ | The built-in chat UI inside Qualytics. Full session management, context injection, streaming, PDF export. |
| MCP Server | An open-protocol endpoint. External clients (Claude Desktop, ChatGPT, Cursor) connect to it directly with your API token. |
| Agentic endpoints | REST endpoints that use an agent to service the request, for integrating conversational AI capabilities into custom applications, scripts, and automation pipelines. |
All three use the same underlying MCP tools and capabilities — they differ only in how you access them.
What tools are available?
AgentQ and external MCP clients share the same tool set. Every tool is available on every session.
| Category | Tools |
|---|---|
| Exploration | list_datastores, list_containers, list_fields, global_search, preview_query |
| Transformations | create_computed_table, create_computed_file, create_computed_join, create_computed_field |
| Quality Checks | list_quality_check_specs, create_quality_check, update_quality_check, list_quality_checks |
| Anomalies | list_anomalies, anomaly_describe |
| Insights & Scores | quality_scores, get_insights, operation_insights |
| Operations | run_sync, run_profile, run_scan, run_export, run_materialize, get_operation_status |
| Promotion | promote_computed_table, promote_computed_file, promote_computed_field, promote_quality_check |
| Integrations | send_notification, create_ticket, list_integrations, manage_tags |
| Workflows | workflow_analyze_trends, workflow_investigate_anomaly, workflow_interpret_quality_scores, workflow_generate_quality_check, workflow_transform_dataset |
Security
Is AgentQ safe to use in production?
Yes. AgentQ includes multiple safety layers:
- Topic guardrail: A lightweight classifier rejects off-topic requests before they reach the main agent.
- SQL injection protection: Computed asset queries are validated — only
SELECTstatements and CTEs are permitted. INSERT/UPDATE/DELETE/DDL are blocked. - Prompt injection defense: Tool output is sanitized to strip control characters before being passed to the LLM.
- Token budget limits: Tool results are truncated if they exceed 8,000 characters to prevent context flooding.
- Co-authorship tracking: All platform changes are audited with AgentQ attribution.
- Rate limiting: Per-user limits prevent runaway usage.
- RBAC enforcement: AgentQ respects the same permission model as the rest of the platform. It can only access what your user account is authorized to use.
Troubleshooting
AgentQ is not responding
- Verify your LLM configuration is active in Settings > Integrations.
- Check that your API key is valid and has sufficient credits with your provider.
- You may have hit the rate limit (10 requests/minute). Wait briefly and try again.
- If you exceeded a token limit, try breaking the request into smaller steps.
I'm getting unexpected results
- Be specific about datastore and table names in your requests.
- Use the context injection feature — open AgentQ from the relevant page so it automatically knows which asset you mean.
- If AgentQ creates something incorrect, ask it to fix or update the result in the same conversation.
- For complex multi-step tasks, break them into sequential steps.
Tool calls are failing
- Some operations require specific permissions. Verify your Qualytics user has the necessary access rights.
- If a datastore operation fails, confirm the Qualytics service account has access to that datastore.
- Click the tool step in the response to expand it and read the specific error in the Output section.
The response was cut off mid-way
You may have hit a timeout (5-minute agent execution limit) or token limit for a single request. Try:
- Breaking the request into smaller, more focused prompts.
- Starting a fresh session and asking the same question with more specific context.
- Using a more capable model (e.g., GPT-4o or Claude Sonnet) if you're using a smaller model.
Computed table/file/join quality checks fail immediately after creation
Computed assets require a profiling operation to complete before quality checks can be created on them. AgentQ handles this automatically by triggering a profile operation and polling until it finishes. If you're creating checks programmatically via the API, wait for the profile operation to reach completed status before creating checks.
Smart suggestions are empty or not showing
Suggestions are generated based on your top 5 containers with active anomalies. If no anomalies exist in your datastores, suggestions may be generic or not appear. Run a scan on your datastores to generate anomalies, or simply type your request directly.
My request was declined as off-topic
AgentQ's topic guardrail occasionally misclassifies edge-case requests. If your request is genuinely related to data quality or the Qualytics platform, try rephrasing it with more explicit context — for example, mention a specific datastore, container, or quality check in your message.