Quickstart: From Agent to Chat Widget

Use this quickstart to create an Agent, configure its prompt, model, and tools, and embed it as a chat widget on your website.

At the end, you have a live chat widget powered by your Agent.

The examples use a website, but you can embed the widget anywhere that supports HTML or React, including a web app, a mobile app webview, an internal tool, or a documentation site.

Before you begin

Create a Runtype account before you start. Use the Runtype sign-up page.

Runtype includes platform keys for a curated selection of models, so you can start without adding provider API keys. For more information, see platform keys.

Create a product

On the Products page, click New Product.

In the create panel, select the Surface type that you want to use. Select Chat Widget.

Enter a product name and choose a capability option:

• New Agent: Create an Agent with a system prompt and tools.
• Use Existing: Select an existing Agent or Flow.
• Skip for now: Add capabilities later in the Product editor.

After you click Create, Runtype creates these items:

• A Product: a container for your Capabilities and Surfaces.
• An Agent: a Capability that powers the chat widget.
• A Chat Widget Surface: the widget that your users interact with.

The Product editor opens with the Surface panel ready for configuration.

A Product groups Capabilities and Surfaces. It can expose the same Agent through a chat widget, an API endpoint, or another Surface. For more information, see Creating a Product.

Configure an Agent

In the Product editor, open the Agent Capability. For help with the editor layout, see Understanding the Runtype UI.

Open the Agent configuration. The Settings tab displays the configuration fields.

Write a system prompt

In Settings, enter instructions in System Prompt. The system prompt controls how the Agent responds.

Use the following sample to configure an Agent for product support:

You are a support assistant for Acme Inc.
Help customers with questions about our products and services.
Be friendly and concise. If you don't know the answer, let the
customer know you'll escalate their question to a human.

After you save the prompt, the Behavior tab displays it.

To refine the prompt, return to System Prompt and edit the instructions after you review responses.

Choose a model

In Settings, select the model that powers your Agent. Runtype supports models from OpenAI, Anthropic, Google, xAI, and other providers through platform keys.

Open the model menu to review the models available to your account.

Add tools (optional)

To let your Agent call external services, open Capabilities and click Configure Tools. You can skip this step and add tools later.

The tool selection panel lists available platform tools:

• Exa: Search the web.
• Firecrawl: Scrape and extract content from web pages.

After you finish configuring the Agent, click Save.

Style your widget

After you save the Agent, click Save & Continue in the Surface panel. The Style Widget step opens.

Choose a theme preset or open Advanced Style Editor to change colors, fonts, and layout.

Use the theme generator in Advanced Style Editor to create a custom theme. Choose one of these sources:

• From a website URL: Enter your website URL. Runtype analyzes the site and uses its colors and design patterns to generate a theme.
• From a description: Enter a plain-language description, such as dark mode with purple accents. You can also attach reference images.

The editor previews the widget in collapsed, expanded, and fullscreen modes.

To keep the default theme, click Skip for now. To save your changes and continue, click Continue.

Embed the widget on your site

The Ship step displays the embed code. Select or create a client token for the widget. The client token authenticates the widget and scopes it to your Agent.

Use a script tag

Copy the script tag and paste it into your website’s HTML before the closing </body> tag:

1
<script
2
  src="https://cdn.runtype.com/persona/latest/install.global.js"
3
  data-runtype-token="YOUR_CLIENT_TOKEN"
4
></script>

Replace YOUR_CLIENT_TOKEN with the client token from the Ship step.

The widget launcher appears in the bottom-right corner. The installer loads the launcher first and can defer the full widget until a visitor opens the chat. For analytics or programmatic control, use the onChatReady callback or the persona:chat-ready DOM event. The onReady callback and persona:ready event are deprecated aliases. The widget sanitizes rendered message HTML by default.

Use React or a bundler app

If your app uses React or another bundler, install the package with this command:

$
npm install @runtypelabs/persona

After installation, initialize the widget with this code:

1
import '@runtypelabs/persona/widget.css'
2
import { initAgentWidget, markdownPostprocessor } from '@runtypelabs/persona'
3
4
initAgentWidget({
5
  target: 'body',
6
  config: {
7
    apiUrl: 'https://api.runtype.com',
8
    clientToken: 'YOUR_CLIENT_TOKEN',
9
    parserType: 'json',
10
    postprocessMessage: ({ text }) => markdownPostprocessor(text),
11
  },
12
})

Replace YOUR_CLIENT_TOKEN with the client token from the Ship step.

To test locally, use localhost. Test client tokens allow localhost automatically. Before production, restrict the token by adding your production origin to Allowed Origins.

After you embed the widget, the launcher appears on your site.

Test the widget

Send a message in the chat widget from the dashboard preview or your site. The Agent responds according to the system prompt.

To change the response, return to the Product editor and open the Agent Capability. Edit the system prompt, model, or tools. To inspect execution details, open What are Logs?.

A Product can contain multiple Capabilities and Surfaces. For example, add a knowledge base search Flow as a Capability and expose it through the chat widget and an API endpoint.

Next steps

Use these links to continue customizing and evaluating your widget:

• Creating and configuring Agents: add tools and capabilities to your Agent
• Runtime and client-side tools: extend the widget with server-side and browser tools
• Client tokens and domain restrictions: restrict the widget to approved origins
• Widget theming and customization: refine the widget’s appearance and behavior
• Running an Eval: compare prompts and models against test data