> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get started with Suada in under 10 minutes

# 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](https://suada.ai) if you haven't already)
2. Your API key from the [dashboard](https://suada.ai/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:

```env theme={null}
# 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:

```env theme={null}
# 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:

<CodeGroup>
  ```bash npm theme={null}
  npm install @suada/node langchain
  ```

  ```bash pip theme={null}
  pip install suada langchain
  ```
</CodeGroup>

### Step 2: Create a LangChain Agent

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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?"
  );
  ```

  ```python Python theme={null}
  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?"
  )
  ```
</CodeGroup>

## Front-end Integration

### Step 1: Install the Front-end SDK

Choose your preferred front-end framework:

<CodeGroup>
  ```bash React theme={null}
  npm install @suada/core @suada/integrations-react
  ```

  ```bash React Native theme={null}
  npm install @suada/core @suada/integrations-react-native
  ```

  ```bash Vue theme={null}
  npm install @suada/core @suada/integrations-vue
  ```

  ```bash Angular theme={null}
  npm install @suada/core @suada/integrations-angular
  ```

  ```bash Vanilla theme={null}
  npm install @suada/core @suada/integrations-vanilla
  ```
</CodeGroup>

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:

<CodeGroup>
  ```tsx React theme={null}
  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`);
          }
        }}
      />
    );
  }
  ```

  ```tsx React Native theme={null}
  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}
      />
    );
  }
  ```

  ```vue Vue theme={null}
  <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>
  ```

  ```typescript Angular theme={null}
  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`);
    }
  }
  ```

  ```html Vanilla theme={null}
  <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>
  ```
</CodeGroup>

## 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:

* Email us at [hello@suada.ai](mailto:hello@suada.ai)