ContentStack Agent SDK - Create Domain Specific AI Chatbots without any efforts

This SDK let's you add AI chatbot by just using a react hook. Yes, just install this package, setup some basic configurations and use hook to send user query to that function and get AI powered response back (AI will use your contentstack content to answer users query).

Installation

npm install contentstack-agent-sdk
# or
yarn add contentstack-agent-sdk

Usage

import { useAgent } from "contentstack-agent-sdk";
const { response, loading, error, askStream, isStreaming } = useAgent({
        baseUrl: 'http://localhost:8080/api/v1/ask', // Replace with your backend URL
        llmApiKey: process.env.GOOGLE_API_KEY!, // Replace with your LLM API key. Remove this "!" if you are not using Typescript
        contentstackApiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!, // Replace with your Contentstack API key. Remove this "!" if you are not using Typescript
        llmProvider: 'groq', // or 'google', depending on your LLM provider
    });

Quickstart

'use client';

import { useState } from "react";
import { useAgent } from "contentstack-agent-sdk";

export default function Chatbot() {
  const { response, loading, error, askStream, isStreaming } = useAgent({
    baseUrl: "http://localhost:8080/api/v1/ask", 
    llmApiKey: process.env.GOOGLE_API_KEY!, 
    contentstackApiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!, 
    llmProvider: "google", 
  });

  const [input, setInput] = useState("");

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!input.trim()) return;
    await askStream(input);
    setInput("");
  };

  return (
    <div style={{ maxWidth: 500, margin: "0 auto", padding: 20 }}>
      <h2>Chatbot</h2>

      {/* Messages */}
      <div style={{ border: "1px solid #ddd", padding: 10, minHeight: 200 }}>
        {loading && <p>Thinking...</p>}
        {error && <p style={{ color: "red" }}>{error.message}</p>}
        {response && (
          <p>
            <strong>Bot:</strong> {response}
            {isStreaming && <span style={{ opacity: 0.5 }}> ⌛</span>}
          </p>
        )}
      </div>

      {/* Input */}
      <form onSubmit={handleSubmit} style={{ marginTop: 10 }}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type your message..."
          style={{ width: "80%", padding: 8 }}
        />
        <button type="submit" disabled={loading} style={{ padding: 8 }}>
          Send
        </button>
      </form>
    </div>
  );
}

API Reference

useAgent(config)

Hook that connects your frontend to the backend AI service.

Config options:

Key	Type	Required	Description
baseUrl	string	✅	Backend endpoint to forward queries.
llmApiKey	string	✅	API key for your chosen LLM provider.
contentstackApiKey	string	✅	Contentstack API key used to fetch your content.
llmProvider	string	✅	LLM provider ("google" or "groq").

Note: Currently there are only 2 LLM providers google and groq.

Returns:

Variable	Type	Description
response	string	AI-generated response.
loading	boolean	Whether the request is in progress.
error	Error | null	Error object if the request fails.
askStream	(query: string) => Promise<void>	Function to send user input.
isStreaming	boolean	True if AI response is still streaming.