Overview
Connectors are the integration layer between agents and your business systems. When an agent is handling a live call, it may need to look up a customer record in your CRM, create a support ticket, send a confirmation email, or verify an identity against a database. Connectors make all of this possible without custom code in the conversation flow.
Every connector category exposes identical tool names regardless of the underlying vendor. This means you can migrate from Freshdesk to Zendesk - or from HubSpot to Salesforce - by changing the connector configuration. The agent's flow, prompts, and logic stay completely untouched. Provider abstraction is a first-class design principle, not an afterthought.
Credentials are validated at creation time: if you provide an invalid API key or misconfigured OAuth app, the connector is rejected immediately rather than failing silently at runtime. OAuth tokens are refreshed automatically before expiry. Every external call is wrapped in an OpenTelemetry span, giving you end-to-end traceability from the agent's tool call through to the external system response.
System families
The stable center carries more weight than the vendor logos around it - swap any vendor without touching the agent.
Connector Categories
| Category | Providers | Tools | What agents do with it |
|---|---|---|---|
| CRM | HubSpot, Salesforce (OAuth) | 7 | Look up contacts, update deals, sync records and notes |
| Ticketing | Freshdesk, Zendesk, Zoho Desk, ServiceNow | 7 | Create, update, search, and read support tickets |
| Resend, SendGrid, Mailgun | 2 | Send confirmation, follow-up, and transactional emails | |
| Documents | SharePoint, OneDrive (Microsoft Graph) | 6 | Search and retrieve documents for knowledge-base Q&A |
| Identity verification | Google Sheets, SQL DB (PostgreSQL, MySQL, MSSQL) | - | Verify caller identity against your own data sources |
| SMS | Twilio SMS | - | OTP codes and transactional messaging during or after a call |
| MCP servers | Any MCP-compliant server | Dynamic | Dynamic tool discovery and health sync - add any MCP-compliant capability |
How Dispatch Works
When an agent's LLM emits a tool call, the following path executes:
- The LLM emits a tool call (e.g.
create_ticketwith parameters). - MCPRegistry looks up the tool name and finds the connector instance and provider configured for this agent.
- The connector authenticates - either refreshing the OAuth token or reading the API key from the secrets vault.
- The connector calls the external API with the normalised parameters.
- The response is normalised to a standard contract (status values, priority levels, field names standardised across vendors).
- A
FunctionResultis returned to the LLM for the next reasoning step. - The entire hop is wrapped in an OpenTelemetry span, capturing authentication, API call duration, response status, and any errors.
Design Principles
| Principle | What it means in practice |
|---|---|
| Provider abstraction | Same tool names across vendors. Swap Freshdesk for Zendesk by changing the connector config - the agent flow stays untouched. |
| Credential validation | Credentials are tested against the provider API at creation time. Invalid credentials are rejected immediately - they never reach a production agent. |
| Normalised contracts | Status values, priority levels, and field names are standardised across all providers in a category. Agents work with canonical values, not vendor-specific enums. |
| Auto token refresh | OAuth access tokens are refreshed before expiry. Agents never fail mid-call because a token expired. |
| Pre-flight health | Connector health is monitored continuously. Authentication failures and API degradations trigger alerts before they affect live calls. |
| OTel-wrapped | Every external call gets its own trace span. End-to-end observability from the agent's tool call to the external system response, visible in Grafana Tempo. |
Related
- Core Engine - the runtime that issues tool calls to the MCPRegistry
- Security & Governance - how connector credentials and OAuth tokens are secured in the vault
- Architecture - where the Integration layer sits in the six-layer stack (Layer 04)
- Platform overview - all four engines and four trust pillars