Skip to main content
Connectors are dynamic integrations with external services defined in the Runflow backend. They support two modes of usage:
  1. As Tools - For agent execution (LLM decides when to call)
  2. 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:
  1. Custom headers (highest - overrides everything)
  2. credentialId override (runtime override)
  3. Instance credential (default from connector instance)
  4. No authentication

​
Using Connectors in Workflows

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

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

​
Next Steps

Workflows

Orchestrate complex processes

Tools

Learn more about tools