Quickstart Guide

This guide will help you integrate Suada into your application. We’ll cover both back-end integration with LangChain and front-end UI components.

Prerequisites

Before you begin, make sure you have:

A Suada account (sign up at suada.ai if you haven’t already)
Your API key from the dashboard
Node.js 16+ or Python 3.8+ for back-end integration
A LangChain-compatible LLM (e.g., OpenAI API key)

Environment Setup

Back-end Environment Variables

Create a .env file in your project root:

# Required
SUADA_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# Optional
SUADA_BASE_URL=https://api.suada.ai
SUADA_DEBUG=true

Front-end Environment Variables

For React/Vue/Angular applications, create a .env file:

# React/Vue/Angular
VITE_SUADA_API_KEY=your_api_key_here
VITE_SUADA_BASE_URL=https://api.suada.ai

# Next.js
NEXT_PUBLIC_SUADA_API_KEY=your_api_key_here
NEXT_PUBLIC_SUADA_BASE_URL=https://api.suada.ai

# React Native
SUADA_API_KEY=your_api_key_here
SUADA_BASE_URL=https://api.suada.ai

Back-end Integration

Step 1: Install the SDK

Choose your preferred back-end language:

npm install @suada/node langchain

pip install suada langchain

Step 2: Create a LangChain Agent

Here’s how to use Suada as a tool in your LangChain agent:

import { SuadaClient } from '@suada/node';
import { ChatOpenAI } from 'langchain/chat_models/openai';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';

// Initialize Suada client
const suada = new SuadaClient({
  apiKey: process.env.SUADA_API_KEY
});

// Create Suada tool for LangChain
const suadaTool = suada.createTool({
  name: 'business_analyst',
  description: 'Use this tool to analyze business data and get insights. Input should be a specific business question.',
  externalUserIdentifier: 'user_123' // Your user's identifier
});

// Initialize LLM
const model = new ChatOpenAI({
  temperature: 0,
  modelName: 'gpt-4',
  openAIApiKey: process.env.OPENAI_API_KEY
});

// Create agent
const executor = await initializeAgentExecutorWithOptions(
  [suadaTool],
  model,
  {
    agentType: "openai-functions",
    verbose: true
  }
);

// Use the agent
const result = await executor.run(
  "What were our top performing products last month, and what insights can you provide about their performance?"
);

from suada import SuadaClient
from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent, AgentType

# Initialize Suada client
suada = SuadaClient(
    api_key='your_suada_api_key'
)

# Create Suada tool for LangChain
suada_tool = suada.create_tool(
    name='business_analyst',
    description='Use this tool to analyze business data and get insights. Input should be a specific business question.',
    external_user_identifier='user_123'  # Your user's identifier
)

# Initialize LLM
llm = ChatOpenAI(
    temperature=0,
    model_name='gpt-4'
)

# Create agent
agent = initialize_agent(
    tools=[suada_tool],
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

# Use the agent
result = agent.run(
    "What were our top performing products last month, and what insights can you provide about their performance?"
)

Front-end Integration

Step 1: Install the Front-end SDK

Choose your preferred front-end framework:

npm install @suada/core @suada/integrations-react

npm install @suada/core @suada/integrations-react-native

npm install @suada/core @suada/integrations-vue

npm install @suada/core @suada/integrations-angular

npm install @suada/core @suada/integrations-vanilla

Note: All front-end SDKs require the @suada/core package as a peer dependency.

Step 2: Add the Integration Manager

Add the integration manager component to your application:

import { IntegrationManager } from '@suada/integrations-react';

function App() {
  return (
    <IntegrationManager
      config={{
        apiKey: process.env.REACT_APP_SUADA_API_KEY,
        externalUserIdentifier: 'user_123',
        onIntegrationConnected: (type) => {
          console.log(`Integration ${type} connected`);
        }
      }}
    />
  );
}

import { IntegrationManager } from '@suada/integrations-react-native';

function App() {
  return (
    <IntegrationManager
      config={{
        apiKey: process.env.REACT_APP_SUADA_API_KEY,
        externalUserIdentifier: 'user_123',
        onIntegrationConnected: (type) => {
          console.log(`Integration ${type} connected`);
        }
      }}
      style={styles.container}
    />
  );
}

<template>
  <SuadaIntegrationManager
    :config="config"
    @integration-connected="onIntegrationConnected"
  />
</template>

<script setup>
import { SuadaIntegrationManager } from '@suada/integrations-vue';

const config = {
  apiKey: import.meta.env.VITE_SUADA_API_KEY,
  externalUserIdentifier: 'user_123'
};

const onIntegrationConnected = (type) => {
  console.log(`Integration ${type} connected`);
};
</script>

import { Component } from '@angular/core';
import { SuadaIntegrationsConfig } from '@suada/integrations-angular';

@Component({
  selector: 'app-root',
  template: `
    <suada-integration-manager
      [config]="config"
      (integrationConnected)="onIntegrationConnected($event)"
    ></suada-integration-manager>
  `
})
export class AppComponent {
  config: SuadaIntegrationsConfig = {
    apiKey: environment.suadaApiKey,
    externalUserIdentifier: 'user_123'
  };

  onIntegrationConnected(type: string) {
    console.log(`Integration ${type} connected`);
  }
}

<script>
import { IntegrationManager } from '@suada/integrations-vanilla';

// Register the web component
customElements.define('suada-integration-manager', IntegrationManager);
</script>

<suada-integration-manager
  id="integration-manager"
></suada-integration-manager>

<script>
// Configure the component
const manager = document.getElementById('integration-manager');
manager.config = {
  apiKey: 'your_api_key',
  externalUserIdentifier: 'user_123'
};

manager.addEventListener('integration-connected', (e) => {
  console.log(`Integration ${e.detail.type} connected`);
});
</script>

Best Practices

Security

Never commit API keys to version control
Use environment variables for sensitive data
Implement proper error handling
Validate user input
Use HTTPS for all API calls

Performance

Initialize SDK instances once and reuse them
Implement proper cleanup in component unmount
Handle offline scenarios gracefully
Use proper caching strategies
Optimize network requests

Development

Use TypeScript/type hints when available
Follow framework best practices
Write unit tests
Keep dependencies updated
Use proper error boundaries

Common Issues & Solutions

API Key Issues

If you’re getting authentication errors:

Verify your API key is correctly set in environment variables
Check if the API key has the correct permissions
Ensure the environment variable is accessible in your application

Integration Connection Issues

If integrations aren’t connecting:

Verify the OAuth callback URL is correctly configured
Check if the integration is enabled in your Suada dashboard
Ensure proper error handling is in place

LangChain Integration Issues

If the LangChain agent isn’t working:

Verify OpenAI API key is correctly set
Check if the model name is supported
Ensure proper error handling for API calls

Need Help?

If you run into any issues:

Email us at hello@suada.ai

​Quickstart Guide

​Prerequisites

​Environment Setup

​Back-end Environment Variables

​Front-end Environment Variables

​Back-end Integration

​Step 1: Install the SDK

​Step 2: Create a LangChain Agent

​Front-end Integration

​Step 1: Install the Front-end SDK

​Step 2: Add the Integration Manager

​Best Practices

​Security

​Performance

​Development

​Common Issues & Solutions

​API Key Issues

​Integration Connection Issues

​LangChain Integration Issues

​Need Help?