Connection Patterns

How you structure agents and connections depends on your customer’s data architecture. This guide covers two common patterns:

• Shared multi-tenant — One agent, one connection, many customers. Data isolation via context filters.
• Single-tenant (agent per customer) — One agent per customer, each with a linked connection to a shared database or their own dedicated database.

Shared multi-tenant

When to use: All customers share one database, with a tenant identifier column (e.g. organisation_id) on every table.

┌─────────────┐
│   Agent      │──── Connection ──── Shared Database
│              │                     (all tenants)
└─────────────┘
     │
     ├── Customer A  → userContext: { organisationId: 1 }
     ├── Customer B  → userContext: { organisationId: 2 }
     └── Customer C  → userContext: { organisationId: 3 }

This is the standard pattern covered in the Multi-Tenant Setup example. A single agent serves all customers, and context filters on each table ensure data isolation.

Single-tenant: Agent per customer with a linked connection

When to use: Each customer gets their own agent (with a tailored semantic model), but they all query the same shared database. A single connection is created once and linked to each customer’s agent.

                                    ┌─────────────────┐
┌── Agent (Customer A) ─── link ───►│                  │
│                                   │  Shared          │
├── Agent (Customer B) ─── link ───►│  Connection      │──── Database
│                                   │                  │
└── Agent (Customer C) ─── link ───►│  (owned by       │
                                    │   primary agent) │
                                    └─────────────────┘

Why use this pattern?

• Each customer can have a customised semantic model (different table prompts, visible columns, computed columns)
• You manage one database connection instead of duplicating credentials
• Context filters still apply — each agent can have its own userContext configuration

Setup

1. Create the primary agent and connection

   Create one agent (the “owner”) and connect your database to it via the dashboard. This agent owns the connection.

2. Mark the connection as shareable

   In the dashboard, go to the connection settings and enable sharing. This allows other agents in your organisation to link to it.

3. Create a customer agent

   For each customer, create a new agent in the dashboard. Configure its semantic model to match that customer’s needs — you can customise table visibility, prompts, and computed columns independently.

4. Link the shared connection

   Link the shared connection to the customer’s agent via the CLI:

   npx inconvo connection link --agent agt_customer_a --connection conn_shared

   Or list available shareable connections and select interactively:

   npx inconvo connection link --agent agt_customer_a

5. Configure context filters

   Even with separate agents, you should still set context filters if the database contains data for multiple customers:

   WHERE orders.organisation_id = userContext.organisationId;
   WHERE users.organisation_id = userContext.organisationId;

6. Create conversations using the customer’s agent

   import Inconvo from "@inconvoai/node";
   
   const inconvo = new Inconvo({
     apiKey: process.env.INCONVO_API_KEY,
   });
   
   // Use the customer-specific agent ID
   const conversation = await inconvo.agents.conversations.create(
     customerAgentId,
     {
       userIdentifier: req.user.id,
       userContext: {
         organisationId: req.user.organisationId,
       },
     },
   );

Single-tenant: Dedicated database per customer

When to use: Each customer has their own isolated database (e.g. separate RDS instances or schemas). Each agent gets its own connection.

┌── Agent (Customer A) ──── Connection A ──── Database A
│
├── Agent (Customer B) ──── Connection B ──── Database B
│
└── Agent (Customer C) ──── Connection C ──── Database C

Setup

1. Create an agent per customer

   Each customer gets their own agent in the Inconvo dashboard.

2. Connect each agent to its database

   Add a database connection for each agent pointing to that customer’s database.

3. Configure the semantic model

   Each agent’s semantic model can be configured independently. Since the database is already isolated to one customer, you typically don’t need context filters.

4. Create conversations

   // Map customer to their agent ID
   const agentId = getAgentIdForCustomer(req.user.customerId);
   
   const conversation = await inconvo.agents.conversations.create(agentId, {
     userIdentifier: req.user.id,
   });

   Tip

   Without context filters, all data in the connected database is queryable. This is the right behaviour when each database is fully isolated to one customer.

Choosing a pattern

Pattern	Agents	Connections	Context filters	Best for
Shared multi-tenant	1	1	Required on every table	SaaS with shared DB, uniform analytics needs
Linked connection	1 per customer	1 (shared)	Recommended	Shared DB, per-customer semantic models
Dedicated database	1 per customer	1 per customer	Optional	Isolated DBs, maximum data separation