# Creating An Agent (New Cell)
Source: https://docs.opensesame.dev/Designing-Cell
Creating a new interface using OpenSesame
When you log in to OpenSesame, you are taken to your workspace. This is where all Cells are managed. A Cell represents our version of an embeddable AI native interface.
By default, you will see a newly created blank Cell that you can begin customizing.\
If you prefer to start fresh, select **“Create New Cell”** at the top of the screen.
From there, you can either:
* **Start blank and define your own Cell configuration**
* **Paste a link to import a pre-built Cell or an OpenAPI definition**
The workspace is interactive and acts as the main place where you define what your Cell can do, connect integrations, and design the experience users will see when they interact with it.
Once created, your Cell becomes a programmable agent that can be embedded into your product or accessed through an API.
## Designing Your Agent
Once your Cell is created, you can customize how it looks and feels. The design tab lets you adjust every visual aspect of the Cell so that it matches your product or brand.
You can modify colors, layout, typography, and logos directly from the left panel. The preview on the right updates in real time so you can see exactly how your Cell will appear once embedded.
Use the Colors section to adjust the primary, secondary, and accent tones. You can also set options like glow and border to match your desired style. The Layout and Typography tabs allow you to refine structure and text appearance for a seamless visual fit.
This flexibility ensures that your Cell blends naturally into your existing interface and feels like part of your product experience.
## Adding Context
Context allows your Cell to respond with greater accuracy and relevance. You can provide it with background information about your company, product, or services directly from this panel.
You can add **URLs**, **files**, or **materials** that contain reference data your Cell should understand. Each source you include expands the Cell’s ability to answer questions using your specific content.
If you want your Cell to reflect a particular tone or set of instructions, select **Customize Personality**. This option lets you define how your Cell communicates and behaves.
By combining context and personality, your Cell becomes a true reflection of your product knowledge and brand voice. This ensures that responses stay aligned with the information and style you want customers to experience.
# Embedding Your Cell
Source: https://docs.opensesame.dev/Embedding
Embed your agent via a single script tag
Once your Cell is built and tested, you can embed it directly into your product using the configuration tools provided. OpenSesame supports both **Automatic** and **Manual Configuration** modes, along with three framework options: **HTML**, **Next.js**, and **React Native**.
> **Important:**\
> The variables `{userId}` and `{authToken}` shown in the examples below are **runtime values**. Your app must dynamically replace them before loading the Cell.
>
> * `userId` identifies the active user session.
> * `authToken` must be valid and refreshed as needed to prevent authentication errors during use.
### Automatic Configuration Snippet
### 1. Automatic Configuration
Automatic configuration provides a pre-generated code snippet that includes your **Cell ID**, placeholders for **user data**, and an **auth token**.
**Steps:**
1. Select **Automatic Configuration**.
2. Choose your preferred framework (**HTML**, **Next.js**, or **React Native**).
3. Copy the provided code and paste it into your application file (for example, `index.html`).
4. Replace placeholders such as `{userId}` and `{authToken}` with live values from your app before deployment.
**Example:**
```
```
> **Note:**\
> Make sure that the `authToken` you pass is valid and accessible at runtime. If your app uses expiring tokens (for example, short-lived JWTs), refresh them dynamically before initializing the Cell.
This method is the fastest way to get a Cell running. Once embedded, your Cell appears at the bottom of your interface and can be used by your users immediately.
### Manual Configuration Snippet
### 2. Manual Configuration
Manual configuration allows you to fine-tune how your Cell looks and behaves. You can adjust colour themes, layout, and size directly in the configuration object.
You can edit fields such as:
* `primaryColor`, `secondaryColor`, and `accentColor`
* `placeholderText` (for example “What can I do for you?”)
* `borderRadius`, `defaultWidth`, and `bottomMargin`
* `dictation`, `glowEnabled`, and `borderEnabled`
This gives you full control over the appearance and placement of your Cell within your application.
### 3. Additional Parameters — Simple Guide
#### What It Is
**Additional Parameters** let you automatically include required values—like customer IDs, company IDs, or region codes—in every API call your Cell makes. This ensures your Cell always operates in the correct data context without the user having to specify those details.
#### How It Works
You can define key-value pairs in the configuration UI or directly within your configuration object (for example, `customer_id: 12345`). These parameters are then automatically appended to all API calls your Cell makes to connected services.
#### Example
* **Without additional parameters:**\
The user must say, “Show me invoices for customer 12345.”
* **With additional parameters:**\
You define `customer_id: 12345` in your configuration. Now the user can simply say, “Show me my invoices,” and the Cell automatically includes the correct ID.
This approach is especially useful for maintaining the correct `userId`, `accountId`, or `companyId` context across all API interactions.
> **Note:** Additional Parameters are optional but recommended if your Cell connects to multi-tenant or user-specific APIs. It helps prevent context mismatches and reduces the need for repetitive user input.
***
### 4. Deployment
Once configured, save and redeploy your application. The Cell loads automatically wherever you include the snippet. You can test the integration in **Preview Mode** to confirm that your Cell connects correctly and displays as expected.
#### Authentication Token
When embedding your Cell, ensure your **auth token (**`authToken`**) is valid and refreshed** at runtime. The embed script uses this token to authorize all Cell requests.
If your tokens expire (for example, short-lived JWTs), refresh them dynamically before initializing or reloading the Cell to avoid authentication failures.
**Example:**
```
"auth": {
"Authorization": ${authToken}
}
```
> **Tip:** If your application renews tokens automatically, reinitialize the `OpenSesameCellConfig` object or reload the widget after the new token is issued.
Your Cell is now live and fully embedded into your product. Once deployed, your users can interact with it immediately.
***
# Extra Features & Testing
Source: https://docs.opensesame.dev/Extras-Testing
Description of your new file.
### Testing
Testing allows you to verify how your Cell performs before deployment. You can automatically generate test questions based on your uploaded context, endpoints, and materials. These questions help you evaluate whether the Cell responds accurately and uses the connected APIs correctly.
Select **Generate Questions** to create sample prompts or add your own under **Add a Test Question**. Once ready, click **Test All Requests** to run them together and review the responses. This helps ensure the Cell is functioning as expected across all available endpoints.
### Preview Mode
Preview Mode lets you see exactly how your Cell will appear and behave once embedded into your product. The preview is displayed at the bottom center of your screen, allowing you to experience the agent as your end users will.
The Cell has context of what it sees on the page, enabling it to understand and describe on-screen elements. This is useful for applications where the Cell assists users in navigating or explaining what they are viewing.
### Analytics
Analytics gives you visibility into how users interact with your Cell after deployment. You can review message activity, user counts, and response statistics directly from the dashboard.
The **Messages Analytics** view provides metrics such as total users, most active users, and average messages per user. You can also drill down into individual user activity using their user ID to view message histories and engagement levels.
These insights help you understand usage patterns, identify improvement opportunities, and measure the real impact of your deployed agent.
# Importing Endpoints
Source: https://docs.opensesame.dev/Implementing-API
Integrate your endpoints inside a Cell.
Cells can connect directly to your APIs. When you upload an API specification, OpenSesame automatically builds an MCP server behind the scenes. This allows your users to interact with your API through natural language.
To add your endpoints:
1. Click **Upload OpenAPI Spec**.
2. Choose your `.yaml` or `.json` file. This file can come from your existing Swagger or OpenAPI documentation.
* If you do not have a spec file, contact our team and we can generate one for you.
* You can also enrich your file with additional endpoint descriptions to improve response quality.
3. **Add your Base URL, authentication tokens, or additional parameters if required.**
> **Note:**\
> When setting up for testing, you may use a single static auth token. This is fine for quick verification.\
> However, this **should not be used in your live embed**, since auth tokens often expire.\
> For production, replace the static token with a **runtime variable** (for example `${authToken}`) so your application dynamically injects a fresh token whenever the Cell loads. This ensures users remain authenticated and prevents token expiry issues during use.
4. Once uploaded, OpenSesame automatically detects your endpoints and lists them in the panel.
You can review each endpoint, view its details, and **import** the ones you want your Cell to use. Imported endpoints become part of the Cell’s knowledge and action set.
We also support **GraphQL** endpoints. Simply provide the schema in the same upload flow.
After importing, your Cell can call these endpoints in real time, turning your existing API into an interactive agent that your users can chat with or embed directly into your product.
## Designing Your Agent
Once your Cell is created, you can customize how it looks and feels. The design tab lets you adjust every visual aspect of the Cell so that it matches your product or brand.
You can modify colors, layout, typography, and logos directly from the left panel. The preview on the right updates in real time so you can see exactly how your Cell will appear once embedded.
Use the Colors section to adjust the primary, secondary, and accent tones. You can also set options like glow and border to match your desired style. The Layout and Typography tabs allow you to refine structure and text appearance for a seamless visual fit.
This flexibility ensures that your Cell blends naturally into your existing interface and feels like part of your product experience.
## Adding Context
Context allows your Cell to respond with greater accuracy and relevance. You can provide it with background information about your company, product, or services directly from this panel.
You can add **URLs**, **files**, or **materials** that contain reference data your Cell should understand. Each source you include expands the Cell’s ability to answer questions using your specific content.
If you want your Cell to reflect a particular tone or set of instructions, select **Customize Personality**. This option lets you define how your Cell communicates and behaves.
By combining context and personality, your Cell becomes a true reflection of your product knowledge and brand voice. This ensures that responses stay aligned with the information and style you want customers to experience.
# Embedding Your Cell
Source: https://docs.opensesame.dev/Embedding
Embed your agent via a single script tag
Once your Cell is built and tested, you can embed it directly into your product using the configuration tools provided. OpenSesame supports both **Automatic** and **Manual Configuration** modes, along with three framework options: **HTML**, **Next.js**, and **React Native**.
> **Important:**\
> The variables `{userId}` and `{authToken}` shown in the examples below are **runtime values**. Your app must dynamically replace them before loading the Cell.
>
> * `userId` identifies the active user session.
> * `authToken` must be valid and refreshed as needed to prevent authentication errors during use.
### Automatic Configuration Snippet
### 1. Automatic Configuration
Automatic configuration provides a pre-generated code snippet that includes your **Cell ID**, placeholders for **user data**, and an **auth token**.
**Steps:**
1. Select **Automatic Configuration**.
2. Choose your preferred framework (**HTML**, **Next.js**, or **React Native**).
3. Copy the provided code and paste it into your application file (for example, `index.html`).
4. Replace placeholders such as `{userId}` and `{authToken}` with live values from your app before deployment.
**Example:**
```
```
> **Note:**\
> Make sure that the `authToken` you pass is valid and accessible at runtime. If your app uses expiring tokens (for example, short-lived JWTs), refresh them dynamically before initializing the Cell.
This method is the fastest way to get a Cell running. Once embedded, your Cell appears at the bottom of your interface and can be used by your users immediately.
### Manual Configuration Snippet
### 2. Manual Configuration
Manual configuration allows you to fine-tune how your Cell looks and behaves. You can adjust colour themes, layout, and size directly in the configuration object.
You can edit fields such as:
* `primaryColor`, `secondaryColor`, and `accentColor`
* `placeholderText` (for example “What can I do for you?”)
* `borderRadius`, `defaultWidth`, and `bottomMargin`
* `dictation`, `glowEnabled`, and `borderEnabled`
This gives you full control over the appearance and placement of your Cell within your application.
### 3. Additional Parameters — Simple Guide
#### What It Is
**Additional Parameters** let you automatically include required values—like customer IDs, company IDs, or region codes—in every API call your Cell makes. This ensures your Cell always operates in the correct data context without the user having to specify those details.
#### How It Works
You can define key-value pairs in the configuration UI or directly within your configuration object (for example, `customer_id: 12345`). These parameters are then automatically appended to all API calls your Cell makes to connected services.
#### Example
* **Without additional parameters:**\
The user must say, “Show me invoices for customer 12345.”
* **With additional parameters:**\
You define `customer_id: 12345` in your configuration. Now the user can simply say, “Show me my invoices,” and the Cell automatically includes the correct ID.
This approach is especially useful for maintaining the correct `userId`, `accountId`, or `companyId` context across all API interactions.
> **Note:** Additional Parameters are optional but recommended if your Cell connects to multi-tenant or user-specific APIs. It helps prevent context mismatches and reduces the need for repetitive user input.
***
### 4. Deployment
Once configured, save and redeploy your application. The Cell loads automatically wherever you include the snippet. You can test the integration in **Preview Mode** to confirm that your Cell connects correctly and displays as expected.
#### Authentication Token
When embedding your Cell, ensure your **auth token (**`authToken`**) is valid and refreshed** at runtime. The embed script uses this token to authorize all Cell requests.
If your tokens expire (for example, short-lived JWTs), refresh them dynamically before initializing or reloading the Cell to avoid authentication failures.
**Example:**
```
"auth": {
"Authorization": ${authToken}
}
```
> **Tip:** If your application renews tokens automatically, reinitialize the `OpenSesameCellConfig` object or reload the widget after the new token is issued.
Your Cell is now live and fully embedded into your product. Once deployed, your users can interact with it immediately.
***
# Extra Features & Testing
Source: https://docs.opensesame.dev/Extras-Testing
Description of your new file.
### Testing
Testing allows you to verify how your Cell performs before deployment. You can automatically generate test questions based on your uploaded context, endpoints, and materials. These questions help you evaluate whether the Cell responds accurately and uses the connected APIs correctly.
Select **Generate Questions** to create sample prompts or add your own under **Add a Test Question**. Once ready, click **Test All Requests** to run them together and review the responses. This helps ensure the Cell is functioning as expected across all available endpoints.
### Preview Mode
Preview Mode lets you see exactly how your Cell will appear and behave once embedded into your product. The preview is displayed at the bottom center of your screen, allowing you to experience the agent as your end users will.
The Cell has context of what it sees on the page, enabling it to understand and describe on-screen elements. This is useful for applications where the Cell assists users in navigating or explaining what they are viewing.
### Analytics
Analytics gives you visibility into how users interact with your Cell after deployment. You can review message activity, user counts, and response statistics directly from the dashboard.
The **Messages Analytics** view provides metrics such as total users, most active users, and average messages per user. You can also drill down into individual user activity using their user ID to view message histories and engagement levels.
These insights help you understand usage patterns, identify improvement opportunities, and measure the real impact of your deployed agent.
# Importing Endpoints
Source: https://docs.opensesame.dev/Implementing-API
Integrate your endpoints inside a Cell.
Cells can connect directly to your APIs. When you upload an API specification, OpenSesame automatically builds an MCP server behind the scenes. This allows your users to interact with your API through natural language.
To add your endpoints:
1. Click **Upload OpenAPI Spec**.
2. Choose your `.yaml` or `.json` file. This file can come from your existing Swagger or OpenAPI documentation.
* If you do not have a spec file, contact our team and we can generate one for you.
* You can also enrich your file with additional endpoint descriptions to improve response quality.
3. **Add your Base URL, authentication tokens, or additional parameters if required.**
> **Note:**\
> When setting up for testing, you may use a single static auth token. This is fine for quick verification.\
> However, this **should not be used in your live embed**, since auth tokens often expire.\
> For production, replace the static token with a **runtime variable** (for example `${authToken}`) so your application dynamically injects a fresh token whenever the Cell loads. This ensures users remain authenticated and prevents token expiry issues during use.
4. Once uploaded, OpenSesame automatically detects your endpoints and lists them in the panel.
You can review each endpoint, view its details, and **import** the ones you want your Cell to use. Imported endpoints become part of the Cell’s knowledge and action set.
We also support **GraphQL** endpoints. Simply provide the schema in the same upload flow.
After importing, your Cell can call these endpoints in real time, turning your existing API into an interactive agent that your users can chat with or embed directly into your product.
