​
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:
  1. A Suada account (sign up at suada.ai if you haven’t already)
  2. Your API key from the dashboard
  3. Node.js 16+ or Python 3.8+ for back-end integration
  4. 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

​
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?"
);

​
Front-end Integration

​
Step 1: Install the Front-end SDK

Choose your preferred front-end framework: 
npm install @suada/core @suada/integrations-react
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`);
        }
      }}
    />
  );
}

​
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:
  1. Verify your API key is correctly set in environment variables
  2. Check if the API key has the correct permissions
  3. Ensure the environment variable is accessible in your application

​
Integration Connection Issues

If integrations aren’t connecting:
  1. Verify the OAuth callback URL is correctly configured
  2. Check if the integration is enabled in your Suada dashboard
  3. Ensure proper error handling is in place

​
LangChain Integration Issues

If the LangChain agent isn’t working:
  1. Verify OpenAI API key is correctly set
  2. Check if the model name is supported
  3. Ensure proper error handling for API calls

​
Need Help?

If you run into any issues: