Connectors

Connectors are dynamic integrations with external services defined in the Runflow backend. They support two modes of usage:

As Tools - For agent execution (LLM decides when to call)
Direct Invocation - For programmatic execution (you control when to call)

Key Features

🔄 Dynamic Schema Loading - Schemas are fetched from the backend automatically
🎭 Transparent Mocking - Enable mock mode for development and testing
🛣️ Path Parameter Resolution - Automatic extraction and URL building
⚡ Lazy Initialization - Schemas loaded only when needed, cached globally
🔐 Flexible Authentication - Supports API Key, Bearer Token, Basic Auth, OAuth2
🔄 Multiple Credentials - Override credentials per execution (multi-tenant support)
✅ Type-Safe - Automatic JSON Schema → Zod → LLM Parameters conversion

Usage Mode 1: As Agent Tool

Use connectors as tools that the LLM can call automatically

Resource Identifier: Use the resource slug (e.g., get-customers, list-users) which is auto-generated from the resource name. Slugs are stable, URL-safe identifiers that won’t break if you rename the resource display name.

import { createConnectorTool, Agent, openai } from '@runflow-ai/sdk';

// Basic connector tool (schema loaded from backend)
const getClienteTool = createConnectorTool({
  connector: 'api-contabil',      // Connector instance slug
  resource: 'get-customers',      // Resource slug
  description: 'Get customer by ID from accounting API',
  enableMock: true,               // Optional: enables mock mode
});

// Use with Agent
const agent = new Agent({
  name: 'Accounting Agent',
  instructions: 'You help manage customers in the accounting system.',
  model: openai('gpt-4o'),
  tools: {
    getCliente: getClienteTool,
    listClientes: createConnectorTool({
      connector: 'api-contabil',
      resource: 'list-customers',  // Resource slug
    }),
  },
});

// First execution automatically loads schemas from backend
const result = await agent.process({
  message: 'Get customer with ID 123',
  sessionId: 'session-123',
  companyId: 'company-456',
});

Usage Mode 2: Direct Invocation

Call connectors programmatically, without agent involvement. Works anywhere: standalone scripts, workflow steps, API handlers.

connector() is a function call, not a client factory. You must pass all 3 arguments (connector slug, resource slug, data) in a single call. It returns a Promise with the result.

// CORRECT
const result = await connector('hubspot-prod', 'create-contact', { email: 'john@example.com' });

// WRONG - connector() needs 3 args, not 1
const client = connector('hubspot-prod');
await client.execute('create-contact', data);  // TypeError!

Identifiers:

Connector: Use the instance slug (e.g., hubspot-prod) - recommended over display name
Resource: Use the resource slug (e.g., create-contact) - auto-generated from resource name

Response Format

The response is wrapped in a standard envelope:

const result = await connector('hubspot-prod', 'create-contact', { email: 'john@example.com' });

// result = {
//   success: true,
//   data: { id: 'contact_123', email: 'john@example.com', ... },  // actual API response
//   metadata: { connector: 'hubspot-prod', resource: 'create-contact', ... }
// }

// Access the actual data:
const contact = result.data;

Examples

import { connector } from '@runflow-ai/sdk';

// Direct connector call (using slugs - recommended)
const result = await connector(
  'hubspot-prod',      // connector instance slug
  'create-contact',    // resource slug
  {                    // data
    email: 'john@example.com',
    firstname: 'John',
    lastname: 'Doe'
  }
);

console.log('Contact created:', result);

With execution options:

const options: ConnectorExecutionOptions = {
  credentialId: 'cred-prod-123',  // Override credential
  timeout: 10000,                  // 10 seconds timeout
  retries: 3,                      // Retry 3 times on failure
  useMock: false,                  // Use real API
};

const result = await connector(
  'api-contabil',
  'get-customer',      // Resource slug
  { id: 123 },
  options
);

Multi-tenant example:

// Different credentials per customer
async function createContactForCustomer(customerId: string, contactData: any) {
  // Get customer's HubSpot credential
  const credentialId = await getCustomerCredential(customerId, 'hubspot');
  
  return await connector(
    'hubspot',
    'create-contact',   // Resource slug
    contactData,
    { credentialId }
  );
}

// Usage
await createContactForCustomer('customer-1', { email: 'john@acme.com' });
await createContactForCustomer('customer-2', { email: 'jane@techcorp.com' });

Authentication Priority:

Custom headers (highest - overrides everything)
credentialId override (runtime override)
Instance credential (default from connector instance)
No authentication

Public APIs — call a template directly (no instance)

For connector templates with authRequired = false (public APIs imported via OpenAPI, like JSONPlaceholder, public REST endpoints, etc.), you can skip the instance step entirely and pass the template slug as the first argument. The resolver tries an instance match first and transparently falls back to the template when no instance exists.

import { connector } from '@runflow-ai/sdk';

// Template slug (no instance created)
const todo = await connector(
  'jsonplaceholder',   // template slug — no `-prod` instance needed
  'get-todo',
  { id: 1 }
);

This works for both connector(...) and createConnectorTool({ connector: 'slug', ... }). The shortcut only kicks in when the template has no auth — anything requiring a credential still needs an instance.

Using Connectors in Workflows

Inside `.step()` (recommended)

Call connector() directly inside a workflow step:

import { flow, connector } from '@runflow-ai/sdk';
import { z } from 'zod';

const workflow = flow({
  id: 'crm-pipeline',
  inputSchema: z.object({ cpf: z.string(), name: z.string() }),
  outputSchema: z.any(),
})
  .step('check-eligibility', async (input) => {
    const result = await connector(
      'api-elegibilidade',          // connector slug
      'consulta-por-cpf',           // resource slug
      { path: { cpf: input.cpf } }  // data (path params, query, body)
    );
    return { eligible: result.status === 'active', data: result };
  })
  .step('create-contact', {
    handler: async (input, ctx) => {
      const contact = await connector('hubspot-prod', 'create-contact', {
        email: `${ctx.input.cpf}@example.com`,
        firstname: ctx.input.name,
        properties: { eligibility: input.eligible ? 'approved' : 'denied' },
      });
      return { contactId: contact.id, eligible: input.eligible };
    },
    when: (ctx) => ctx.results['check-eligibility'].eligible,
  })
  .build();

Using `.connector()` step (native)

The FlowBuilder also has a native .connector() method for simple cases:

flow({ id: 'simple', inputSchema, outputSchema })
  .connector('create-ticket', 'hubspot', 'tickets', 'create', {
    subject: 'New Support Request',
    content: '{{input.description}}',
    priority: 'medium',
  })
  .build();

The native .connector() step uses template interpolation ({{input.field}}) for parameters. For dynamic logic (conditionals, transformations), use connector() inside a .step() instead.

Using loadConnector Helper

For connectors with many resources, use the loadConnector helper:

import { loadConnector } from '@runflow-ai/sdk';

const contabil = loadConnector('api-contabil');

const agent = new Agent({
  name: 'Accounting Agent',
  instructions: 'You manage accounting data.',
  model: openai('gpt-4o'),
  tools: {
    // Using resource slugs
    listClientes: contabil.tool('list-customers'),
    getCliente: contabil.tool('get-customer'),
    createCliente: contabil.tool('create-customer'),
    updateCliente: contabil.tool('update-customer'),
  },
});

Path Parameters

Connectors automatically resolve path parameters from the resource URL:

// Resource defined in backend with path: /clientes/{id}/pedidos/{pedidoId}
const getClientePedidoTool = createConnectorTool({
  connector: 'api-contabil',
  resource: 'get-customer-order',  // Resource slug
  description: 'Get specific order from a customer',
});

// Agent automatically extracts path params from context
const result = await agent.process({
  message: 'Get order 456 from customer 123',
  sessionId: 'session-123',
  companyId: 'company-456',
});

// Backend automatically resolves: /clientes/123/pedidos/456

Mock Execution

Enable mock mode for development and testing:

const tool = createConnectorTool({
  connector: 'api-contabil',
  resource: 'list-customers',  // Resource slug
  enableMock: true,            // Adds useMock parameter
});

// Use mock mode in development
const result = await agent.process({
  message: 'List customers (use mock data)',
  sessionId: 'dev-session',
  companyId: 'dev-company',
  // Tool will automatically include useMock=true if mock data is configured
});

How It Works

Tool Creation: createConnectorTool creates a tool with a temporary schema
Lazy Loading: On first agent execution, schemas are fetched from the backend in parallel
Schema Conversion: JSON Schema → Zod → LLM Parameters (automatic)
Caching: Schemas are cached globally to avoid repeated API calls
Execution: Tool/API executes with authentication, path resolution, and error handling

Next Steps

Workflows

Orchestrate complex processes

Tools

Learn more about tools

Channels

WhatsApp, Telegram and more — replies are sent through connectors

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Key Features

Usage Mode 1: As Agent Tool

Usage Mode 2: Direct Invocation

Response Format

Examples

Public APIs — call a template directly (no instance)

Using Connectors in Workflows

Inside `.step()` (recommended)

Using `.connector()` step (native)

Using loadConnector Helper

Path Parameters

Mock Execution

How It Works

Next Steps

Workflows

Tools

Channels

​Key Features

​Usage Mode 1: As Agent Tool

​Usage Mode 2: Direct Invocation

​Response Format

​Examples

​Public APIs — call a template directly (no instance)

​Using Connectors in Workflows

​Inside .step() (recommended)

​Using .connector() step (native)

​Using loadConnector Helper

​Path Parameters

​Mock Execution

​How It Works

​Next Steps

Workflows

Tools

Channels

Key Features

Usage Mode 1: As Agent Tool

Usage Mode 2: Direct Invocation

Response Format

Examples

Public APIs — call a template directly (no instance)

Using Connectors in Workflows

Inside `.step()` (recommended)

Using `.connector()` step (native)

Using loadConnector Helper

Path Parameters

Mock Execution

How It Works

Next Steps