Open source · v0.6

Agent-ready chat,
for every interface.

A browser-safe runtime, headless APIs, and an ecommerce renderer for shipping secure, brandable agent conversations on any site.

Try the Demo View Docs

$ npm install @promptrails/ai-chat@0.7.5

Three Ways to Use

From zero-config script tag to fully custom React hooks — pick the level of control you need.

React Hooks

Build your own UI with useChat(), useStreaming(), useAgent(), and useApproval(). Full control over every pixel.

React Components

Ready-to-use <ChatWindow />, <MessageBubble />, <AgentSteps /> and more. Customize with Tailwind.

Embeddable Widget

One pinned <script> tag — no React or build tools. Shadow DOM isolation, token refresh, resumable sessions, and feedback.

Agent Step Tracking

Multi-step agent execution timeline with real-time status updates. Perfect for chain and workflow agents.

Human-in-the-Loop

Built-in approval flow UI — checkpoint name, payload preview, approve/reject buttons. No extra work needed.

Multi-Provider

PromptRails browser runtime, trusted PromptRails SDK, OpenAI, or a custom SSE/WebSocket backend. Keep provider secrets server-side.

Pick Your Layer

Same package, three integration levels.

index.html

<!-- Add to any website — no React needed -->
<script
  src="https://cdn.jsdelivr.net/npm/@promptrails/ai-chat@0.7.5/dist/widget.global.js"
  data-provider="promptrails"
  data-api-key="BROWSER_ONLY_CHAT_KEY"
  data-base-url="https://api.promptrails.ai"
  data-agent-id="AGENT_KSUID"
  data-workspace-id="WORKSPACE_KSUID"
  data-title="Support Chat"
  data-greeting="Hi! How can I help you today?"
  data-position="bottom-right"
  data-primary-color="#2563eb"
  data-persist-session="true"
  data-session-max-age="86400"
></script>

<!-- Or initialize programmatically -->
<script>
  PromptRailsChat.init({
    provider: {
      type: "promptrails",
      apiKey: "BROWSER_ONLY_CHAT_KEY",
      agentId: "AGENT_KSUID",
      baseUrl: "https://api.promptrails.ai",
    },
    workspaceId: "WORKSPACE_KSUID",
    title: "AI Assistant",
  });
</script>

App.tsx

import { ChatWindow, createPromptRailsBrowserProvider } from "@promptrails/ai-chat";
import "@promptrails/ai-chat/styles.css";

const provider = createPromptRailsBrowserProvider({
  baseUrl: "https://api.promptrails.ai",
  apiKey: "BROWSER_ONLY_CHAT_KEY",
  agentId: "AGENT_KSUID",
  workspaceId: "WORKSPACE_KSUID",
});

export default function App() {
  return (
    <ChatWindow
      provider={provider}
      title="Support Chat"
      showAgentSteps
      showApprovals
    />
  );
}

CustomChat.tsx

import { useChat, createCustomProvider } from "@promptrails/ai-chat";

const provider = createCustomProvider({
  sendUrl: "/api/chat",
  streamUrl: "/api/chat/stream",
});

export default function CustomChat() {
  const {
    messages, isLoading, input,
    setInput, handleSubmit
  } = useChat({ provider });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
        />
        <button disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}

One browser runtime. Any renderer.

Generic chat and ecommerce now share the same security, session, streaming, feedback and recovery layer.

Restricted key

A public browser key is limited to chat, exact origins and an explicit agent allowlist.

Short-lived runtime

The SDK exchanges it for a 15-minute memory-only bearer and refreshes before expiry.

Structured context

Visible customer text and untrusted page context travel in separate API fields.

Declarative UI

Typed resources and allowlisted actions render as text, product, order or custom cards.

Try It Live

Configure the widget and see the generated code.

Widget Configuration

Experience

Provider

Position

Browser-only Chat Key

Base URL

Agent ID

Chat Title

Primary Color

Greeting Message

Safe by design: use only a browser-only chat:write key here. Session history is read through the short-lived browser token plus that session’s resume capability, so the public key needs no management-level read permission. Provider keys and user JWTs never belong in frontend code.

Generated Code

How It Compares

Full-spectrum AI chat toolkit vs. alternatives.

Feature	@promptrails/ai-chat	Vercel AI SDK	Flowise Embed
React Hooks	✓	✓	✗
Ready-made Components	✓	✗	✗
Embeddable Widget	✓	✗	✓
Agent Step Tracking	✓	✗	✗
Human-in-the-Loop	✓	✗	✗
Shadow DOM Isolation	✓	N/A	✓
Multi-Provider	✓	✓	✗
No Build Tools Required	✓ (widget)	✗	✓

Ready to add AI chat to your app?

Start with a browser-only key restricted to chat, exact origins, and an explicit agent allowlist.

View on GitHub npm install

Agent-ready chat,for every interface.