---
title: "JavaScript SDK: AI Agent UI component"
description: "Embed AI agent conversations in your application with the Gleap JavaScript SDK. Follow the integration code examples."
url: https://docs.gleap.ai/en/articles/433-javascript-sdk-ai-agent-ui-component
collection: "UI components"
updated: 2026-11-01
language: en
---

# JavaScript SDK: AI Agent UI component

Embed AI agent conversations in your application with the Gleap JavaScript SDK. Follow the integration code examples.

Embed an AI agent conversation directly into your web app. Choose the level of control that fits your needs — drop-in component, headless state manager, or a single API call.

## Drop-in component

One HTML tag, everything handled — input, streaming, scrolling.

```html
<gleap-agent-conversation agentId="YOUR_AGENT_ID"></gleap-agent-conversation>
```

With context and a custom placeholder:

```html
<gleap-agent-conversation
  agentId="YOUR_AGENT_ID"
  context='{"page": "/billing", "plan": "pro"}'
  placeholder="Ask about your billing..."
></gleap-agent-conversation>
```

### Attributes

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Attribute</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Default</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>agentId</code></p></td><td colspan="1" rowspan="1"><p>string</p></td><td colspan="1" rowspan="1"><p><strong>required</strong></p></td><td colspan="1" rowspan="1"><p>The agent ID</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>conversationId</code></p></td><td colspan="1" rowspan="1"><p>string</p></td><td colspan="1" rowspan="1"><p>—</p></td><td colspan="1" rowspan="1"><p>Resume an existing conversation</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>context</code></p></td><td colspan="1" rowspan="1"><p>string (JSON)</p></td><td colspan="1" rowspan="1"><p>—</p></td><td colspan="1" rowspan="1"><p>Additional context passed to the agent</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>placeholder</code></p></td><td colspan="1" rowspan="1"><p>string</p></td><td colspan="1" rowspan="1"><p><code>"Type a message..."</code></p></td><td colspan="1" rowspan="1"><p>Input placeholder</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>emptyText</code></p></td><td colspan="1" rowspan="1"><p>string</p></td><td colspan="1" rowspan="1"><p><code>"How can I help you today?"</code></p></td><td colspan="1" rowspan="1"><p>Empty-state text</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>agentColor</code></p></td><td colspan="1" rowspan="1"><p>string</p></td><td colspan="1" rowspan="1"><p>primary color</p></td><td colspan="1" rowspan="1"><p>Override accent color</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>dark</code></p></td><td colspan="1" rowspan="1"><p>boolean</p></td><td colspan="1" rowspan="1"><p>false</p></td><td colspan="1" rowspan="1"><p>Dark mode</p></td></tr></tbody></table>

### Events

The component dispatches DOM events you can listen to:

```js
const el = document.querySelector("gleap-agent-conversation");

el.addEventListener("gleap-agent-conversation-created", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-message-sent", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-reply-received", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-error", (e) => { /* e.detail */ });
```

The same events also fire on `Gleap.on(...)` without the `gleap-` prefix:

```js
Gleap.on("agent-reply-received", (data) => { /* ... */ });
Gleap.on("agent-error", (data) => { /* ... */ });
Gleap.on("agent-conversation-created", (data) => { /* ... */ });
```

* * *

## Headless with `Gleap.createAgentChat()`

Manage state and streaming yourself, render any UI you want.

```js
const chat = Gleap.createAgentChat({
  agentId: "YOUR_AGENT_ID",
  context: { page: "/billing" },
  onChange: ({ messages, isExecuting, error, conversationId }) => {
    renderMessages(messages);
    toggleSpinner(isExecuting);
  },
});

chat.sendMessage("What is my current plan?");
```

**Options**

-   `agentId` – the agent to talk to (defaults to `"kai"`).
    
-   `context` – arbitrary object passed to the agent.
    
-   `conversationId` – resume an existing conversation.
    
-   `onChange({ messages, isExecuting, error, conversationId })` – called whenever state changes.
    
-   `onToken`, `onReplyReceived`, `onError`, `onConversationCreated` – optional lifecycle callbacks.
    

**Returned instance**

-   `sendMessage(content)` – send a user message (streams the reply).
    
-   `setContext(context)` – update the context for future messages.
    
-   `clearMessages()` – clear messages and start a new conversation.
    
-   `cancelStream()` – abort the in-flight stream.
    
-   `getState()` – `{ messages, isExecuting, error, conversationId }`.
    
-   `destroy()` – tear down listeners. Always call when unmounting.
    

Each message is `{ id, role, content, createdAt, isStreaming? }`. `isStreaming` is `true` while tokens are still arriving.

To clear cached conversation state across the page (e.g. on logout):

```js
Gleap.clearAgentConversation();
```

* * *

## Raw API

One call, you handle everything else.

```js
const result = await Gleap.sendAgentMessage("YOUR_AGENT_ID", "Hello!", {
  conversationId: previousConversationId,
  additionalContext: { page: "/billing" },
  onToken: (data) => { /* progressive streaming */ },
});

console.log(result.response);        // full reply
console.log(result.conversationId);  // for follow-up calls
```

Returns a Promise that resolves to `{ runId, status, response, conversationId }`.

* * *

## TypeScript

The `gleap` package ships JSX type definitions for the `<gleap-agent-*>` elements, so they work in TSX without a manual declaration. This requires `@types/react` 18.2.6 or newer (17.0.51+ / 16.14.41+ on older React lines). If your project shows errors like `Type '"span"' is not assignable to type 'ElementType'` after installing, run `npm i -D @types/react@latest`.

## Custom styling

The drop-in component renders inside an iframe and accepts `agentColor` / `dark` for basic theming. For full control over the UI, use the headless `createAgentChat()` API and render your own components.

## Related

- [JavaScript SDK: Checklist UI component](https://docs.gleap.ai/en/articles/432-javascript-sdk-checklist-ui-component.md)
- [JavaScript SDK setup](https://docs.gleap.ai/en/articles/393-javascript-sdk-setup.md)
- [JavaScript SDK: Code snippet](https://docs.gleap.ai/en/articles/394-javascript-sdk-code-snippet.md)
- [JavaScript SDK: User identity](https://docs.gleap.ai/en/articles/395-javascript-sdk-user-identity.md)
- [JavaScript SDK: Callbacks](https://docs.gleap.ai/en/articles/396-javascript-sdk-callbacks.md)