> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/assistant/adapters.md).

# Adapters

Adapters are a crucial component of the Assistant architecture, serving as the bridge between the user interface and the back-end services that power the assistant's functionality. They are responsible for sending user messages to the back-end and receiving responses, as well as handling conversation history and providing additional context to the back-end when necessary.

`@ibexa/ai-assistant-ui` package provides several built-in Adapters, including the Echo Adapter for testing purposes, the Ibexa Agentic Marketing Platform Adapter for connecting to the Ibexa Agentic Marketing Platform, and the Open AI Adapter for integrating with OpenAI's language models. Each adapter has its own set of options and configuration requirements, allowing you to choose the one that best fits your use case.

You can also implement a custom Adapter to connect the Assistant to your own back-end or third-party services. This flexibility allows you to tailor the assistant's functionality to your specific needs and integrate it with a wide range of services and platforms.

## Echo Adapter

Adapter repeats the user's message. Its main purpose is testing without requiring a real-life implementation. Supported options:

| Option | Type                 | Required | Description                        |
| ------ | -------------------- | -------- | ---------------------------------- |
| `data` | `ConversationData[]` | No       | Snapshot of the conversation data. |

To instantiate the Echo adapter, simply create a new instance of the `EchoAdapter` class:

```javascript
import { EchoAdapter } from '@ibexa/ai-assistant-ui';

const adapter = new EchoAdapter();
```

To initialize the Echo adapter with predefined conversation data, use the `fromConfig` static method and pass the conversation data as an option:

```javascript
import { EchoAdapter } from '@ibexa/ai-assistant-ui';

const adapter = EchoAdapter.fromConfig({
    data: [
        {
            id: '1',
            subject: 'Example',
            messages: [
                {
                    id: '1',
                    serverId: '',
                    type: 'text',
                    text: 'Hello, how can I assist you today?',
                    role: 'assistant',
                    status: 'done',
                },
            ],
        },
    ],
});
```

## Ibexa Agentic Marketing Platform Adapter

Ibexa Agentic Marketing Platform adapter connects Assistant to [Ibexa Agentic Marketing Platform](https://www.ibexa.co/orchestration), the heart of the European agentic marketing platform made to help brands perform at scale.

| Option         | Type             | Required | Description                                                                                                                                                                                                                                                                      |
| -------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiUrl`       | `string`         | Yes      | URL of the Ibexa Agentic Marketing Platform API, e.g. `https://api.ibexa.ai/`.                                                                                                                                                                                                   |
| `accessToken`  | `string`         | Yes      | Access token for the Ibexa Agentic Marketing Platform API.                                                                                                                                                                                                                       |
| `refreshToken` | `string`         | Yes      | Refresh token for the Ibexa Agentic Marketing Platform API.                                                                                                                                                                                                                      |
| `agentId`      | `number \| null` | No       | Identifier of the agent to connect to. You can find it in the agent's settings in the Ibexa Agentic Marketing Platform dashboard. Pass `null` to operate without a specific agent — the adapter will skip agent-list fetching and create conversations without an agent binding. |
| `context`      | `object`         | No       | Free-form context the assistant works within, forwarded to the conversation-create endpoint (e.g. `{ report_id: 67 }`).                                                                                                                                                          |
| `tenantKey`    | `string`         | No       | Experimental Tenant Key sent as the `X-Tenant-Key` HTTP header on every API request and passed to MCP Tool Calls.                                                                                                                                                                |

To instantiate the Ibexa Agentic Marketing Platform adapter, use a static method `fromConfig` and pass the required options:

```javascript
import { IbexaAdapter } from '@ibexa/ai-assistant-ui';

const adapter = IbexaAdapter.fromConfig({
    apiUrl: 'https://api.ibexa.ai/',
    accessToken: 'demo_access_token',
    refreshToken: 'demo_refresh_token',
    agentId: 1,          // pass null to operate without a specific agent
    context: { report_id: 67 }, // optional
    tenantKey: 'my-tenant', // optional — sent as X-Tenant-Key header
});
```

### Connecting to the Environment

To connect to the Ibexa Agentic Marketing Platform **environment**, use the following configuration:

* **`apiUrl`**: `https://api.ibexa.ai`
* **`accessToken` & `refreshToken`**: Retrieve them by sending a `POST /api/v1/login/access-token` request through a **backend proxy** (direct browser calls are not supported due to CORS and credential security). REST API documentation is available on <https://api.ibexa.ai/docs>.
* **`agentId`**: Log in to <http://app.ibexa.ai>, create an assistant agent, and use its ID. Pass `null` to operate without a specific agent.

```javascript
import { IbexaAdapter } from '@ibexa/ai-assistant-ui';

// accessToken and refreshToken must be fetched server-side via:
// POST https://api.ibexa.ai/api/v1/login/access-token
const adapter = IbexaAdapter.fromConfig({
    apiUrl: 'https://api.ibexa.ai',
    accessToken: '<token_from_backend_proxy>',
    refreshToken: '<refresh_token_from_backend_proxy>',
    agentId: 1, // find this in http://app.ibexa.ai after creating an agent; pass null to skip agent binding
});
```

## Open AI Adapter

Adapter provides native integration with OpenAI.

{% hint style="danger" %}
Open AI Adapter communicates directly with Open AI endpoints and the provided API Key appears in the Network panel. Use only when you don't need to protect the API key, e.g. the API key is provided by the user.
{% endhint %}

The Open AI Adapter supports the following options:

| Option         | Type     | Required | Description                                                                                                             |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `apiKey`       | `string` | Yes      | API key for the Adapter. Generate the key at <https://platform.openai.com/api-keys>.                                    |
| `model`        | `string` | No       | Model used by the adapter, e.g. `gpt-5-nano`. Available models are listed at <https://platform.openai.com/docs/models>. |
| `instructions` | `string` | No       | System instructions for the model.                                                                                      |

To instantiate the Open AI Adapter, use a static method `fromConfig` and pass the required options:

```javascript
import { OpenAIAdapter } from '@ibexa/ai-assistant-ui';

const adapter = OpenAIAdapter.fromConfig({
    apiKey: 'your_openai_api_key',
    model: 'gpt-5-nano',
});
```

To instantiate the Open AI Adapter with system instructions, pass the `instructions` option:

```javascript
import { OpenAIAdapter } from '@ibexa/ai-assistant-ui';

const adapter = OpenAIAdapter.fromConfig({
    apiKey: 'your_openai_api_key',
    model: 'gpt-5-nano',
    instructions: 'You are a helpful assistant that translates user messages to Polish.',
});
```

## Custom Adapter

You can implement a custom Adapter to connect Assistant to your own back-end or third-party services. There are two key interfaces to implement when creating a custom Adapter: `AdapterInterface` and `ConversationInterface`.

`AdapterInterface` is responsible for managing conversations and context, while `ConversationInterface` represents a single conversation and is responsible for sending / receiving messages within that conversation.

Here are the sequence diagrams illustrating key interactions between the Assistant component and an Adapter:

### Initialization with Existing Conversation

When the Assistant component is mounted, we load the conversation with the given `conversationId` from the Adapter, after that we load its history and render it.

<figure><img src="https://425560932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXUxFaOBKWZtV3arMJDqu%2Fuploads%2Fgit-blob-8127216b24172843b9f2e6404e6186e8a2412fa1%2Fadapter-init.png?alt=media" alt="Custom Adapter Sequence Diagram — initialization with existing conversation"><figcaption><p>Initialization with an existing conversation</p></figcaption></figure>

### Initialization with New Conversation

If `conversationId` is not provided during the Assistant initialization, we create a new conversation using the Adapter (`createConversation` method) and start with an empty history (after sending the first message).

{% hint style="info" %}
Some backends may require an initial message to be provided when creating a new conversation. In such cases, it's recommended to use a [Proxy pattern](https://refactoring.guru/design-patterns/proxy) to initialize the conversation when the first user message is sent.
{% endhint %}

### Post Initialization

After the initialization and retrieval of the conversation, Assistant connects to the message stream by registering a callback using the `onMessage` method of the `ConversationInterface`. This allows the Assistant to receive new messages in real-time.

In order to send a message, Assistant calls the `send` method of the `ConversationInterface`, which sends the message to the backend and triggers the message stream callback with the new message.

<figure><img src="https://425560932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXUxFaOBKWZtV3arMJDqu%2Fuploads%2Fgit-blob-9d5042823162c24d881e8194aad6f89c4f4d18a5%2Fadapter-post-init.png?alt=media" alt="Custom Adapter Sequence Diagram — post initialization"><figcaption><p>Post initialization message flow</p></figcaption></figure>