Skip to main content

# Connectors

Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.

## SQL Connectors​

SQL connectors enable agents to query and analyze database information using natural language. These connectors convert user questions into SQL queries, execute them against configured databases, and return results in a conversational format. This capability makes database information accessible through agent interactions without requiring users to write SQL code.

### Supported Databases​

SQL connectors support three database types:

- MySQL
- PostgreSQL
- MariaDB

Each database type follows the same configuration process but may have specific connection string requirements or authentication methods.

### Creating SQL Connectors​

You create SQL connectors in the Connectors section of the Enterprise web interface. This process must be completed before you can assign connectors to agents.

Each SQL connector configuration includes the database type selection, connection details (host address, port number, and database name), and authentication credentials (username and password). The connection configuration establishes a persistent connection pool that agents use to execute queries. You should verify that the database server allows connections from the Agent Mesh deployment and that any required firewall rules permit access.

Once you create a connector, it becomes available for assignment to any agent in your deployment. This reusability means you can connect multiple agents to the same database without duplicating connection configuration. All agents assigned to a connector share the same database connection pool and credentials.

### Security Considerations​

The framework implements a shared credential model that has significant implications for access control when planning your deployment architecture.

#### Shared Credential Architecture​

The framework does not sandbox database access at the agent level. All agents assigned to a connector share the same database credentials and permissions. This design means that any agent with the connector can access all data the connector's credentials permit. Security boundaries exist at the database level, not between agents.

#### Implementing Database-Level Security​

Database-level access control is your primary security mechanism. You should create database users with minimal necessary privileges, use database views or restricted schemas to limit what agents can access, and audit database queries to monitor what agents are accessing.

For example, if you have agents that should only read customer data and other agents that need full database access, you must create separate connectors with different database users. Each database user has appropriate permissions configured at the database level. You cannot restrict access by assigning the same connector to different agents because all agents sharing a connector have identical database permissions.

#### Natural Language Query Risks​

The natural language to SQL conversion capability makes databases accessible through conversation, but this also means users can potentially request any data the connector can access. You should plan your database permissions accordingly and consider what information should be available through agent interactions.

Users might phrase questions in ways that expose data you intended to restrict, or they might discover table and column names through exploratory questions. Database views that present only approved data columns, user accounts with read-only permissions on specific tables, and query result size limits all help mitigate these risks.

#### Best Practices​

Create separate connectors for different security boundaries. If agents require different levels of database access, configure multiple connectors with appropriately scoped database users rather than sharing a single connector across all agents.

Use read-only database accounts whenever possible. Many agent use cases only require reading data, and read-only permissions prevent accidental or malicious data modification.

Implement database views to present filtered data. Views can hide sensitive columns, join tables to present aggregated information, or implement row-level security logic at the database level.

Enable query logging and monitoring to track what agents access. Database audit logs help you detect suspicious query patterns or unauthorized data access attempts.

### Assigning Connectors to Agents​

You assign connectors to agents through Agent Builder. When creating or editing an agent, you select connectors from a list during agent configuration. You can assign connectors before or after deployment, and changes to connector assignments take effect when you deploy or update the agent.

### Managing Connectors​

Connector management operations require specific RBAC capabilities and follow particular patterns to prevent service disruptions.

#### Editing Connectors​

You can modify connector configurations at any time. Changes to connection details or credentials take effect immediately for new database connections. Existing connections in the pool may continue using previous credentials until they expire and reconnect.

If agents are actively using a connector when you modify it, query failures may occur during the transition period. You should plan connector updates during maintenance windows or coordinate with agent users to minimize disruptions.

#### Testing Connections​

The Connectors interface provides connection testing functionality that validates credentials and connectivity before you save the connector configuration. This testing helps identify configuration errors before agents attempt to use the connector.

#### Deleting Connectors​

You can delete connectors, but the system enforces restrictions to prevent breaking deployed agents. If any agents are assigned to a connector, you must first remove the connector from those agents or undeploy them before deletion succeeds.

The deletion process removes the connector configuration but does not affect the database itself. Database users and permissions remain in place, requiring separate cleanup if you no longer need them.

### Troubleshooting​

When connecting SAM to a PostgreSQL databases hosted on Supabase, you may encounter network errors like:

`{ "detail": "Invalid token", "error_type": "invalid_token" }`

This is because Supabase's direct connection endpoint uses IPv6, however most Kubernetes clusters are IPv4 by default. The solution is to use the Session Pooler endpoint as it is IPv4 compatible.

## Access Control​

Connector operations require specific RBAC capabilities. The table below shows the capabilities and what they control:

Capability | Purpose
--- | ---
`sam:connectors:create` | Create new connectors in the Connectors section
`sam:connectors:read` | View connector configurations and list available connectors
`sam:connectors:update` | Modify connector configurations and credentials
`sam:connectors:delete` | Remove connectors from the system

For detailed information about configuring role-based access control, see Setting Up RBAC.