Frontend Integration

The @culvii/kit SDK is designed for backend Node.js environments. You use it to define, orchestrate, and deploy your workflows and agents.

Your frontend application (like React, Vue, or Svelte) does not run the SDK directly. Instead, it interacts with the workflows you have already deployed to the Culvii platform.

How the architecture works

1. Build and deploy: You write your workflow using @culvii/kit on your backend and deploy it to Culvii.
2. Get the endpoint: Once deployed, Culvii provides a secure HTTP endpoint for that specific workflow.
3. Call from the frontend: Your client application sends a standard POST request to this endpoint, passing any required inputs.
4. Display results: The frontend receives the JSON response and updates the user interface.

This separation keeps your API keys secure and ensures heavy processing happens on the server.

React Example

Here is a practical example showing how a React component triggers a deployed workflow. It handles the loading state while waiting for the response and displays the final output or any errors.

import { useState } from 'react';

export default function WorkflowRunner() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const runWorkflow = async () => {
    setLoading(true);
    setError(null);

    try {
      // Replace with your actual deployed workflow endpoint
      const response = await fetch('https://api.culvii.com/v1/workflows/YOUR_WORKFLOW_ID/run', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          // Always proxy requests through your own backend in production 
          // to keep your API keys hidden from the browser.
          'Authorization': `Bearer ${process.env.NEXT_PUBLIC_CULVII_API_KEY}`
        },
        body: JSON.stringify({
          inputs: {
            prompt: "Analyze this data"
          }
        })
      });

      if (!response.ok) {
        throw new Error('Failed to run workflow');
      }

      const data = await response.json();
      setResult(data.result);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="workflow-container">
      <button onClick={runWorkflow} disabled={loading}>
        {loading ? 'Running...' : 'Run Workflow'}
      </button>

      {error && <p className="error-message">Error: {error}</p>}
      
      {result && (
        <div className="result-container">
          <h3>Result:</h3>
          <pre>{JSON.stringify(result, null, 2)}</pre>
        </div>
      )}
    </div>
  );
}

Security best practices

The example above uses a public environment variable for the API key to keep the code simple. In a real production app, you should never expose your Culvii API keys to the browser.

Create a route in your own backend (like a Next.js API route or an Express endpoint). Have your frontend call your backend, and let your backend attach the secret API key before forwarding the request to Culvii.