JavaScript SDK - AGO Documentation

The AGO JavaScript SDK (@useago/sdk) lets you integrate AGO agents into any web application. Use it to build fully custom chat interfaces, handle streaming responses, manage conversations, and register client-side functions that agents can invoke.

Installation

npm install @useago/sdk

For React applications, the SDK also exports hooks and pre-built components:

npm install @useago/sdk react react-dom

Quick Start

Vanilla JavaScript

import { AgoClient } from "@useago/sdk";

const client = new AgoClient({
  baseUrl: "https://YOUR-DOMAIN.useago.com",
  widgetId: "unique-user-id",
});

// Send a message and receive a streaming response
const response = await client.sendMessage("How do I reset my password?");
console.log(response.content);

Zero-Config Setup

If your page already includes the AGO widget script or meta tags, use createAgo to auto-detect configuration:

import { createAgo } from "@useago/sdk";

const client = createAgo(); // Detects config from page environment

The SDK looks for configuration in this order:

window.AGO.basepath global variable
<meta name="ago-base-url"> tag
data-ago-base-url attribute on the body or a script tag

Explicit options override the detected values:

const client = createAgo({ debug: true, widgetId: "user-123" });

React

import { AgoProvider } from "@useago/sdk/react";
import { ChatWidget } from "@useago/sdk/react";

function App() {
  return (
    <AgoProvider baseUrl="https://YOUR-DOMAIN.useago.com">
      <ChatWidget
        title="Support"
        welcomeMessage="Hello! How can I help you?"
      />
    </AgoProvider>
  );
}

Vue.js

import { createApp } from "vue";
import { AgoPlugin } from "@useago/sdk/vue";

const app = createApp(App);
app.use(AgoPlugin, { baseUrl: "https://YOUR-DOMAIN.useago.com" });
app.mount("#app");

Then use composables in your components:

<script setup>
import { useAgo, useMessages } from "@useago/sdk/vue";

const client = useAgo();
const { messages, sendMessage } = useMessages();
</script>

Angular

import { provideAgo, AgoService } from "@useago/sdk/angular";

bootstrapApplication(AppComponent, {
  providers: [
    provideAgo({ baseUrl: "https://YOUR-DOMAIN.useago.com" }),
  ],
});

Then inject in any component or service:

import { AgoService } from "@useago/sdk/angular";

@Component({ ... })
export class ChatComponent {
  constructor(private ago: AgoService) {}
}

Configuration

Create a client instance with the following options:

Option	Required	Description
`baseUrl`	Yes	Your AGO instance URL (e.g., `https://YOUR-DOMAIN.useago.com`)
`widgetId`	No	A unique identifier for the current user (auto-generated if omitted)
`agent`	No	Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`.
`defaultAgentId`	No	Default agent for new conversations. Prefer `agent`.
`permission`	No	Permission name to apply to all requests (sent as `X-Widget-Permission`). Same value the widget reads from `window.AGO.permission`.
`userEmail`	No	User email for identification
`userJwt`	No	JWT token for authenticated users (see Widget Authentication)
`debug`	No	Enable debug logging in the console

const client = new AgoClient({
  baseUrl: "https://YOUR-DOMAIN.useago.com",
  widgetId: "user-12345",
  defaultAgentId: "agent-uuid",
  userEmail: "user@example.com",
  debug: true,
});

You can update configuration after initialization:

client.updateConfig({
  userJwt: "new-jwt-token",
  defaultAgentId: "another-agent-uuid",
});

Sending Messages

Basic Message

const response = await client.sendMessage("What are your business hours?");

console.log(response.content);    // The agent's reply
console.log(response.sources);    // Knowledge sources cited
console.log(response.agent);      // Agent info (name, id)

Message with Options

const response = await client.sendMessage("Follow-up question", {
  conversationId: "existing-conversation-uuid",  // Continue a conversation
  agentId: "specific-agent-uuid",                // Override default agent
  files: [fileObject],                           // Attach files
});

Speech to Text

Use the audio transcription endpoint to turn a recording into an editable draft. This endpoint works with the SDK’s message flow; the example below uses fetch for the audio upload. Speech to text is off by default and must be enabled in the tenant configuration. Read permissions[].speech_to_text_enabled from GET /api/sdk/v1/config to decide whether to show a microphone. Audio uploads return 403 while the setting is disabled. Use the same user identifier and authentication as your SDK client:

import { AgoClient } from "@useago/sdk";

const baseUrl = "https://YOUR-DOMAIN.useago.com";
const widgetId = "unique-user-id";
const client = new AgoClient({ baseUrl, widgetId });

async function transcribeAudio(file) {
  const body = new FormData();
  body.append("file", file);
  const response = await fetch(`${baseUrl}/api/sdk/v1/audio/transcriptions`, {
    method: "POST",
    headers: { "X-User-Anon-Id": widgetId },
    body,
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error.message);
  return result; // { text, transcription_id }
}

// Put result.text into your editable composer and keep result.transcription_id.
// When sending through POST /messages, include the reviewed content and
// transcription_ids: [result.transcription_id] to retain the dictation marker.

For JWT authentication, include Authorization: Bearer <token> as you do for other SDK requests. Keep permission headers consistent with your message requests. Do not manually set Content-Type when uploading FormData. Record audio on HTTPS (or localhost) after the user grants microphone access. WebM, MP4/M4A, OGG, WAV, MP3, MPEG/MPGA, and FLAC files up to 25 MB are accepted. For an iframe, delegate access with allow="microphone" and check that the host page’s Permissions Policy permits it.

Streaming Events

Listen to events for real-time updates as the agent responds:

// Content arrives in chunks for live display
client.on("message:chunk", (data) => {
  updateUI(data.content);  // Append this chunk to the displayed text
});

// Fires when streaming starts
client.on("message:start", (data) => {
  console.log("Response started:", data.messageId);
});

// Fires when the complete message is ready
client.on("message:complete", (message) => {
  displayFinalMessage(message.content, message.sources);
});

// Handle errors
client.on("message:error", (data) => {
  showError(data.error);
});

// Send the message (events fire during processing)
await client.sendMessage("Hello!");

Conversations

List Conversations

const { data: conversations } = await client.getConversations();

conversations.forEach((conv) => {
  console.log(conv.id, conv.title, conv.lastMessageDate);
});

Load a Conversation

const conversation = await client.getConversation("conversation-uuid");

conversation.messages.forEach((msg) => {
  console.log(`${msg.role}: ${msg.content}`);
});

Get Messages

const messages = await client.getMessages("conversation-uuid");

Feedback

Submit thumbs-up or thumbs-down feedback on agent responses:

await client.submitFeedback("message-uuid", "positive");
await client.submitFeedback("message-uuid", "negative");

Tool Call Interactions

When an agent invokes a tool that requires user input (such as a form or a confirmation), the SDK emits events you can handle:

// A tool call with a form was received
client.on("toolCall:form", (toolCall) => {
  // Display the form to the user using toolCall.formSchema
  showForm(toolCall.formSchema, async (formData) => {
    await client.submitToolCallForm(toolCall.id, formData);
  });
});

// Any tool call received (forms, confirmations, status messages, etc.)
client.on("toolCall:received", (toolCall) => {
  console.log("Tool call:", toolCall.type, toolCall.toolName);
});

Events Reference

Event	Payload	Description
`message:start`	`{ conversationId, messageId }`	Streaming response started
`message:chunk`	`{ content, conversationId, messageId }`	A chunk of the response content
`message:complete`	Full message object	Response is fully received
`message:error`	`{ error, conversationId?, messageId? }`	An error occurred
`toolCall:received`	Tool call data	Any tool call was received
`toolCall:form`	Tool call data with form schema	A form tool call requires user input
`function:invoke`	`{ invocationId, functionName, arguments, conversationId }`	A client function is being invoked
`function:result`	`{ invocationId, result, error? }`	A client function execution completed

// Subscribe
client.on("message:complete", handler);

// Unsubscribe
client.off("message:complete", handler);

Defining Reusable Functions

Use defineFunction to create reusable function definitions that agents can invoke on the client side:

import { defineFunction } from "@useago/sdk";

export const lookupOrder = defineFunction({
  name: "lookupOrder",
  description: "Look up an order by ID",
  parameters: {
    type: "object",
    properties: { id: { type: "string" } },
    required: ["id"],
  },
  handler: async (args) => fetchOrder(args.id),
});

// Register with the client
client.registerFunction(lookupOrder);

In React, use the useAgoFunction hook:

import { useAgoFunction } from "@useago/sdk/react";

useAgoFunction(lookupOrder);

See Client Functions for more details on how agents invoke client-side functions.

Page Context

Give the agent awareness of what the user is currently looking at — the active order, the visible dashboard filter, the open ticket. Context entries are attached to every message and surfaced to the agent as a structured prompt section.

Vanilla JavaScript

client.setContext("order-page", {
  name: "Order detail",
  description: "The user is viewing a specific order",
  data: { orderId: "12345", status: "shipped" },
});

// Remove when the view is no longer relevant
client.removeContext("order-page");

For context that lives outside your application state (global stores, refs, computed values), register a provider function that runs at each message send so the agent always receives the freshest value:

client.addDynamicContext("app-shell", () => ({
  name: "App shell",
  data: { userId: currentStore.getState().auth.userId },
}));

React

Use the useAgoContext hook to attach context declaratively. It registers when the component mounts and cleans up on unmount:

import { useAgoContext } from "@useago/sdk/react";

function OrderPage({ order }) {
  useAgoContext({
    name: "Order detail",
    description: "The user is viewing a specific order",
    data: { orderId: order.id, status: order.status },
  });

  return <OrderView order={order} />;
}

Pass a function instead of an object for values that aren’t captured in React state:

useAgoContext(() => ({
  name: "App shell",
  data: { userId: storeRef.current.getState().auth.userId },
}));

Each entry carries three optional fields:

Field	Description
`name`	Short label for the context slice (e.g., “Order detail”)
`description`	One-sentence explanation of what this context represents
`data`	JSON object containing the structured data the agent should know about

SSE Streaming Helpers

The SDK provides helper functions for working with streaming responses:

import {
  onMessage,
  onMessageChunk,
  onMessageStart,
  onMessageError,
  onToolCall,
  createMessageStream,
} from "@useago/sdk";

// Subscribe to complete messages
const unsub = onMessage(client, (message) => {
  console.log("Complete:", message.content);
});

// Subscribe to streaming chunks for real-time display
onMessageChunk(client, ({ content }) => {
  appendToUI(content);
});

// Advanced: async generator for full stream control
for await (const event of createMessageStream(client, "Hello!")) {
  if (event.type === "chunk") {
    console.log(event.data.content);
  }
}

Helper	Description
`onMessage`	Subscribe to complete finished messages
`onMessageChunk`	Subscribe to streaming text chunks
`onMessageStart`	React to message start events
`onMessageError`	Handle message errors
`onToolCall`	React to tool invocations
`onFunctionInvoke`	React to client function invocations
`createMessageStream`	Async generator for full stream control

React Components

The SDK provides pre-built React components for common use cases.

AgoProvider

Provides the AgoClient to your entire React app via context:

import { AgoProvider } from "@useago/sdk/react";

function App() {
  return (
    <AgoProvider baseUrl="https://YOUR-DOMAIN.useago.com" widgetId="user-123">
      <MyChat />
    </AgoProvider>
  );
}

Access the client from any child component:

import { useAgoClient } from "@useago/sdk/react";

function MyChat() {
  const client = useAgoClient();
  // ...
}

Prop	Type	Required	Description
`baseUrl`	string	When `client` is omitted	Your AGO instance URL
`client`	AgoClient	No	Pass a pre-built client instead of config props such as `baseUrl`
`widgetId`	string	No	User identifier (auto-generated if omitted)
`agent`	string	No	Default agent (shorthand for `defaultAgentId`)
`defaultAgentId`	string	No	Default agent for new conversations
`permission`	string	No	Permission name to apply to all requests
`userEmail`	string	No	User email for identification
`userJwt`	string	No	JWT token for authenticated users
`debug`	boolean	No	Enable debug logging

ChatWidget

A complete, ready-to-use chat interface:

import { ChatWidget } from "@useago/sdk/react";

<ChatWidget
  client={client}
  title="Support Chat"
  welcomeMessage="Hello! How can I help you?"
  placeholder="Type a message..."
  allowFiles={true}
  height={600}
  onMessageSent={(content) => console.log("Sent:", content)}
  onMessageReceived={(msg) => console.log("Received:", msg.content)}
/>

Prop	Type	Default	Description
`client`	AgoClient	From provider	The SDK client instance; optional inside an `AgoProvider`
`conversationId`	string	—	Resume an existing conversation
`title`	string	`"Chat"`	Header title
`welcomeMessage`	string	`"Hello! How can I help you today?"`	Empty state text
`placeholder`	string	`"Type a message..."`	Input placeholder
`allowFiles`	boolean	`false`	Enable file attachments
`height`	string or number	`500`	Widget height (px or CSS value)
`logoUrl`	string	—	Logo shown in the header
`showAgentName`	boolean	`false`	Show the agent name above assistant replies when enabled
`className`	string	—	Additional CSS class
`onMessageSent`	function	—	Called when the user sends a message
`onMessageReceived`	function	—	Called when an agent response is complete

Message

Renders a single message with markdown formatting and sources. For the last message, enable follow-up suggestions and provide your click handler:

import { Message } from "@useago/sdk/react";

<Message
  message={agoMessage}
  className="my-message"
  showAgentName={true}
  isLast={true}
  onFollowUpClick={handleFollowUpClick}
/>

The Message component supports:

Markdown rendering, including GitHub-flavored markdown: bold, italic, headings, lists, code blocks, links, blockquotes, tables, task lists, and strikethrough
Agent name display for assistant messages when showAgentName={true}; names are hidden by default
Knowledge source citations with links
Follow-up reply buttons when the message has suggestions and isLast={true}; onFollowUpClick receives the selected reply text, and buttons are disabled when this handler is omitted
Streaming indicator while a response is in progress

Markdown

Renders a raw markdown string the same way Message renders assistant content. Use it when you build a fully custom chat UI but still want consistent markdown output:

import { Markdown } from "@useago/sdk/react";

<Markdown content="**Bold**, a [link](https://useago.com), and a | table |" />

React Hooks

useAgo

Creates and manages the SDK client lifecycle:

import { useAgo } from "@useago/sdk/react";

const { client, isReady } = useAgo({
  baseUrl: "https://YOUR-DOMAIN.useago.com",
  widgetId: "unique-user-id",
  defaultAgentId: "agent-uuid",
});

The hook handles client creation, cleanup on unmount, and dynamic config updates.

useMessages

Manages messages within a conversation:

import { useMessages } from "@useago/sdk/react";

const {
  messages,          // Array of messages
  isLoading,         // True while sending
  error,             // Current error (if any)
  sendMessage,       // (content: string, files?: File[]) => Promise
  clearMessages,     // Reset the conversation
  conversationId,    // Current conversation ID
} = useMessages({ client, conversationId: "optional-uuid" });

useConversation

Manages the conversation list and selection:

import { useConversation } from "@useago/sdk/react";

const {
  conversations,         // List of conversations
  currentConversation,   // Currently selected conversation
  isLoading,
  error,
  selectConversation,    // (id: string) => Promise
  startNewConversation,  // () => void
  refreshConversations,  // () => Promise
} = useConversation({ client, autoLoad: true });

Custom Chat UI Example

Build a fully custom interface using hooks:

import { useState } from "react";
import { useAgo, useMessages, useConversation } from "@useago/sdk/react";
import { Message } from "@useago/sdk/react";

function CustomChat() {
  const { client, isReady } = useAgo({
    baseUrl: "https://YOUR-DOMAIN.useago.com",
    widgetId: "user-123",
  });

  const { messages, sendMessage, isLoading } = useMessages({ client });
  const [input, setInput] = useState("");

  const handleSend = async () => {
    if (!input.trim()) return;
    const content = input;
    setInput("");
    await sendMessage(content);
  };

  return (
    <div>
      <div className="messages">
        {messages.map((msg) => (
          <Message key={msg.id} message={msg} />
        ))}
      </div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => e.key === "Enter" && handleSend()}
        placeholder="Ask a question..."
      />
      <button onClick={handleSend} disabled={isLoading}>
        Send
      </button>
    </div>
  );
}

Cleanup

Always destroy the client when it is no longer needed to free resources:

client.destroy();

In React, the useAgo hook handles cleanup automatically on unmount.

Client Functions — SDK API reference
Widget Configuration — Widget settings
Widget & SDK Authentication — Authentication setup
Deploy the Chat Widget — Deployment guide

​Installation

​Quick Start

​Vanilla JavaScript

​Zero-Config Setup

​React

​Vue.js

​Angular

​Configuration

​Sending Messages

​Basic Message

​Message with Options

​Speech to Text

​Streaming Events

​Conversations

​List Conversations

​Load a Conversation

​Get Messages

​Feedback

​Tool Call Interactions

​Events Reference

​Defining Reusable Functions

​Page Context

​Vanilla JavaScript

​React

​SSE Streaming Helpers

​React Components

​AgoProvider

​ChatWidget

​Message

​Markdown

​React Hooks

​useAgo

​useMessages

​useConversation

​Custom Chat UI Example

​Cleanup

​Related

Installation

Quick Start

Vanilla JavaScript

Zero-Config Setup

React

Vue.js

Angular

Configuration

Sending Messages

Basic Message

Message with Options

Speech to Text

Streaming Events

Conversations

List Conversations

Load a Conversation

Get Messages

Feedback

Tool Call Interactions

Events Reference

Defining Reusable Functions

Page Context

Vanilla JavaScript

React

SSE Streaming Helpers

React Components

AgoProvider

ChatWidget

Message

Markdown

React Hooks

useAgo

useMessages

useConversation

Custom Chat UI Example

Cleanup

Related