Inconvo: The Data Agent Platform Every Developer Needs

Build production-ready data agents that talk to your databases safely. No more query injection nightmares. No more manual permission logic. Just reliable, customer-facing AI that works.

Every modern application needs to answer complex data questions. But building secure, production-grade natural language interfaces is a nightmare. Developers waste weeks wrestling with SQL injection prevention, row-level security, and maintaining conversation state. Inconvo changes everything. This Y Combinator-backed open-source platform lets you deploy powerful data agents in minutes, not months. You get automatic query validation, enterprise-grade permissions, and structured outputs your application can trust. In this deep dive, you'll discover how Inconvo transforms database interactions, explore real code examples, and learn why teams are abandoning custom solutions for this sleek, modern approach.

What is Inconvo?

Inconvo is an open-source platform that builds data agents for production databases. Created by a Y Combinator S23 batch company, it solves the fundamental challenge of letting users ask natural language questions about live data without compromising security or performance.

A data agent is a specialized service that sits between your application and your database. It receives questions like "What is our best selling product this week?" and returns structured, actionable answers. Unlike traditional BI tools or simple LLM wrappers, Inconvo enforces explicit permissions, validates every query against allowed schemas, and maintains stateful conversations across multiple turns.

The platform is trending because it eliminates the biggest blocker to AI-powered data access: trust. Developers no longer need to choose between powerful functionality and security. Inconvo's semantic modeling layer lets you start immediately with auto-discovered schemas, then gradually add business context like custom metrics, computed fields, and join rules. With observability built-in, every query execution is traceable, inspectable, and debuggable.

Whether you're building customer-facing analytics, internal tools, or embedded reporting features, Inconvo provides the infrastructure that typically takes engineering teams months to build. The cloud offering gets you running in minutes, while the open-source version gives you complete control for self-hosted deployments.

Key Features That Make Inconvo Essential

Safe Query Execution is the cornerstone of Inconvo's architecture. Every generated SQL query undergoes rigorous validation against your explicitly defined schema permissions. The system constrains queries to allowed tables, columns, and joins before execution, eliminating SQL injection risks entirely. You define what's accessible, and Inconvo guarantees nothing else gets touched.

Permissions & Multi-Tenancy work automatically at runtime. Inconvo enforces row-level, table-level, and column-level security without requiring custom query logic. You provide tenant context once, and the platform applies it consistently across all interactions. This means a single agent can serve thousands of customers safely, each seeing only their authorized data slice.

Stateful Interactions revolutionize conversational data access. Agents remember filters, refinements, and context across conversation turns. When a user asks "Show me sales data" then follows up with "Just for the West region," Inconvo maintains the thread intelligently. No manual state management. No fragile session handling.

Observability & Monitoring provide complete transparency. Every agent run generates detailed traces showing the natural language input, generated SQL, execution logs, and final output. When things go wrong—and they will—you have everything needed to debug quickly. The dashboard reveals performance bottlenecks, common failure patterns, and usage analytics.

Semantic Modeling bridges the gap between business language and database structure. Start querying immediately using auto-discovered schemas, then progressively enhance the model with business metrics, domain terminology, computed fields, and intelligent join rules. This layered approach means your agents get smarter over time without breaking existing functionality.

Real-World Use Cases Where Inconvo Shines

Customer-Facing Analytics Dashboards become trivial to implement. Instead of building complex filter UIs and pre-computing every possible view, let users ask questions naturally. A SaaS platform can embed Inconvo to let clients query their own data: "Which marketing campaign had the highest ROI last quarter?" The agent returns structured JSON that your frontend renders beautifully, with full permission enforcement ensuring clients never see each other's data.

Internal Business Intelligence tools for non-technical teams. Sales operations, marketing managers, and executives need data but shouldn't write SQL or wait for analyst tickets. Deploy an internal Inconvo agent connected to your data warehouse. Now anyone can ask "How many enterprise deals closed above $50K this month compared to last?" and get instant, reliable answers. The observability features let data teams monitor usage and improve the semantic model based on real questions.

Embedded Reporting in SaaS Products differentiates your offering. Build a "Chat with Your Data" feature that becomes a competitive advantage. A project management tool could let users ask "Which team member completed the most tasks in sprint 12?" Inconvo handles the natural language processing, query generation, and permission boundaries automatically. You focus on the user experience; Inconvo handles the complexity.

Multi-Tenant Data Exploration at scale. For platforms serving thousands of customers with isolated datasets, Inconvo's runtime permission system is game-changing. Configure tenant isolation once, then scale infinitely. Each customer's questions execute against their data slice automatically. No code changes needed when onboarding new customers. The stateful conversation feature means users can drill down iteratively: "Show me orders" → "Filter by California" → "Group by product category" → "Export results."

Step-by-Step Installation & Setup Guide

Quick Start with Inconvo Cloud

The fastest path to production is Inconvo Cloud. Sign up for free at app.inconvo.ai and follow the interactive onboarding. The cloud version includes managed infrastructure, automatic updates, and enterprise SLAs. You'll be running queries within five minutes.

Local Development Setup

For evaluation and development, run Inconvo locally using the official CLI:

# Install and start Inconvo in development mode
npx inconvo@latest dev

This command downloads the latest version, starts all necessary services, and opens the dashboard at http://localhost:26686. The local instance includes the full feature set: query validation, permission engine, and observability tools.

Environment Configuration

Create a .env file in your project root to store your API credentials:

# .env file
INCONVO_API_KEY="your_api_key_here"
INCONVO_ENVIRONMENT="development"
DATABASE_URL="postgresql://user:password@localhost:5432/production"

Connect Your Database

In the dashboard, navigate to Data Sources and add your database connection. Inconvo supports PostgreSQL, MySQL, and BigQuery out of the box. The system automatically discovers your schema and suggests initial permissions.

Define Permissions

Use the visual permission editor to specify:

• Allowed tables (e.g., orders, products, customers)
• Accessible columns (e.g., orders.total, customers.email)
• Row-level filters (e.g., organisation_id = ${userContext.organisationId})
• Join rules (e.g., allow orders JOIN products but not orders JOIN internal_audit_logs)

Create Your First Agent

Click New Agent, select your data source, and choose the permission profile. The agent is immediately ready to test in the playground. Ask a question, inspect the generated SQL, and verify the output structure.

REAL Code Examples from the Repository

Example 1: Basic Agent Conversation

This exact code from the Inconvo README shows the complete flow of creating a conversation and getting a response:

import "dotenv/config";
import Inconvo from "@inconvoai/node";

// Initialize the Inconvo client with your API key
const inconvo = new Inconvo({
  apiKey: process.env.INCONVO_API_KEY, // Load from environment variables
});

// Create a new conversation with a specific agent and user context
const agentConvo = await inconvo.agents.conversations.create("agt_123", {
  userIdentifier: "user_123", // Unique identifier for the user
  userContext: {
    organisationId: 1, // Tenant context applied at runtime
  },
});

// Send a natural language question to the agent
const agentResponse = await inconvo.agents.conversations.response.create(
  agentConvo.id,
  {
    message: "What is our best selling product this week?",
    stream: false, // Set to true for streaming responses
  },
);

console.log(agentResponse);

/**
{
  "type": "text",
  "message": "Your most popular product (by total units ordered, to date) is iPhone 15 (Smartphone)."
}
**/

How this works: The client initializes with your API key, creates a stateful conversation tied to a specific agent (agt_123), and includes multi-tenant context (organisationId). The response.create method sends the natural language question, and Inconvo handles everything else: parsing the intent, generating validated SQL, executing against your database with row-level filters applied, and returning a structured JSON response. The stream: false parameter requests a complete response; set it to true for real-time token streaming.

Example 2: Streaming Responses for Real-Time UX

For better user experience, stream responses as they're generated:

const responseStream = await inconvo.agents.conversations.response.create(
  agentConvo.id,
  {
    message: "Show me revenue trends for the last 6 months",
    stream: true, // Enable streaming
  },
);

// Handle streaming chunks
for await (const chunk of responseStream) {
  if (chunk.type === "text_delta") {
    process.stdout.write(chunk.content); // Write partial response
  } else if (chunk.type === "query") {
    console.log("Generated SQL:", chunk.sql); // Log the validated query
  } else if (chunk.type === "error") {
    console.error("Agent error:", chunk.message); // Handle execution errors
  }
}

Key insight: Streaming reveals the agent's reasoning process. You can display partial answers while showing the generated SQL for transparency. This builds user trust and helps debug issues.

Example 3: Handling Structured Data Outputs

Inconvo agents return typed responses perfect for programmatic consumption:

interface ProductSalesResponse {
  type: "structured_data";
  data: {
    productName: string;
    unitsSold: number;
    revenue: number;
    trend: "up" | "down" | "stable";
  }[];
  summary: string;
}

const structuredResponse = await inconvo.agents.conversations.response.create(
  agentConvo.id,
  {
    message: "Top 5 products by revenue this month with trends",
    format: "structured_data", // Request structured output
  },
) as ProductSalesResponse;

// Directly use the data in your application
structuredResponse.data.forEach(product => {
  console.log(`${product.productName}: $${product.revenue} (${product.trend})`);
});

Powerful pattern: By requesting structured_data format, you get machine-readable JSON that bypasses natural language parsing. Your frontend can render tables, charts, or export buttons directly from the response.

Example 4: Local Development Server Initialization

The exact command from the README to start local development:

# This single command starts the entire Inconvo platform locally
npx inconvo@latest dev

# Expected output:
# ✔ Inconvo Engine started on port 26686
# ✔ Dashboard available at http://localhost:26686
# ✔ API documentation at http://localhost:26686/docs
# ✔ Press Ctrl+C to stop

What happens: The CLI downloads the Inconvo engine, starts the query validation service, permission manager, and observability dashboard. It auto-discovers local databases and suggests schema configurations. The @latest tag ensures you always run the newest stable version.

Advanced Usage & Best Practices

Progressive Semantic Enhancement is the key to long-term success. Start with auto-discovered schemas to get immediate value. Then iteratively add business logic: define custom metrics like customer_lifetime_value, create friendly aliases for cryptic column names, and specify join rules that reflect your business model. This approach avoids big upfront modeling projects while continuously improving agent accuracy.

Permission Composition enables complex security models. Combine row-level filters (tenant_id = ${userContext.tenantId}) with column-level restrictions (hide: [users.ssn, users.salary]). Use permission profiles to create reusable sets of rules for different user roles: admin_profile, manager_profile, customer_profile. Apply profiles dynamically at runtime based on userContext.

Conversation Management at scale requires cleanup strategies. While Inconvo maintains state automatically, implement conversation TTLs (time-to-live) for inactive sessions. Use the inconvo.agents.conversations.list() method to find stale conversations and inconvo.agents.conversations.delete() to free resources. For long-running analytics workflows, persist conversation IDs in your database and restore them when users return.

Observability-Driven Development treats agent logs as first-class metrics. Monitor query_generation_time, execution_success_rate, and user_satisfaction_signals. Set alerts for sudden increases in query failures—these often indicate schema changes or permission misconfigurations. Review the Query Inspector weekly to find commonly asked questions that return poor results, then enhance your semantic model accordingly.

Caching Strategies dramatically improve performance. Cache frequently asked questions at the application level using the conversation ID as a key. For dashboard scenarios, pre-warm agents with common queries during off-peak hours. Inconvo's structured output format makes caching particularly effective since you can invalidate cache based on data freshness rather than complex query matching.

Comparison with Alternatives

Why Inconvo Wins: Unlike LangChain SQL agents that require extensive prompt engineering and lack production guardrails, Inconvo was designed for production from day one. The permission system isn't an afterthought—it's core to every query execution. Compared to custom GPT wrappers, you get observability, state management, and semantic modeling out of the box. Traditional BI tools can't match the natural language flexibility or developer integration experience.

Frequently Asked Questions

Q: How does Inconvo prevent SQL injection attacks? A: Inconvo uses a multi-layer validation engine. First, it generates queries using a constrained LLM with schema awareness. Then, a separate validation service checks every query against your explicit permission rules before execution. The database never receives unvalidated SQL. This is fundamentally more secure than string concatenation or even prepared statements with dynamic table names.

Q: Can Inconvo handle complex joins across multiple databases? A: Yes. The semantic modeling layer lets you define join rules between tables, even across database boundaries. Specify which joins are allowed, how they should be performed, and what business logic applies. Inconvo's query planner optimizes the generated SQL for performance while respecting your constraints.

Q: What databases are supported? A: Currently PostgreSQL, MySQL, and BigQuery are officially supported with full feature parity. The team is actively working on Snowflake, Redshift, and SQL Server connectors. The open-source nature means you can contribute adapters for other databases by implementing the DataSource interface.

Q: How does multi-tenancy work with row-level security? A: You define row-level filters using template variables like ${userContext.organisationId}. When your application calls the agent, you pass the userContext object. Inconvo automatically injects these values into the query filters at runtime. No custom SQL rewriting needed. This works for thousands of tenants with zero performance degradation.

Q: Is the cloud version required, or can I self-host? A: Both options are fully supported. The open-source version (Apache 2.0 license) can be self-hosted on any infrastructure. Inconvo Cloud offers managed hosting, automatic backups, and enterprise support. Start with cloud for speed; migrate to self-hosted for complete control. The API is identical between both.

Q: How do I handle schema changes in my database? A: Inconvo's schema discovery runs continuously. When you add tables or columns, they appear in the dashboard as "pending approval." You explicitly allow new schema elements before agents can use them. This prevents unexpected behavior and gives you control over the rollout. The Query Inspector highlights queries affected by schema changes.

Q: What's the performance overhead compared to direct SQL? A: Typically 50-150ms overhead for query generation and validation. The execution time is identical to direct SQL since Inconvo runs the validated query against your database. For high-traffic scenarios, enable query result caching in the dashboard to cache frequently run queries. The semantic modeling layer actually improves performance by encouraging optimized join patterns.

Conclusion

Inconvo represents a paradigm shift in how developers build data-powered applications. By solving the hard problems—security, permissions, state management, and observability—it lets you focus on delivering value to users. The progressive semantic modeling approach means you start simple and grow sophisticated without rewrites. The Apache 2.0 license and active open-source community ensure you're never locked in.

After testing the platform extensively, the combination of automatic query validation and runtime permission enforcement is genuinely revolutionary. No other tool provides this level of production readiness out of the box. Whether you're a startup embedding analytics into your product or an enterprise modernizing internal tools, Inconvo deserves a serious evaluation.

Ready to build your first data agent? Visit the GitHub repository to star the project and access the source code. Sign up for free at app.inconvo.ai to be running in minutes. Join the Discord community to connect with other developers and get support from the core team. The future of data access is conversational, secure, and developer-friendly—Inconvo is leading the charge.