> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmo.humanizing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playground

> Test your Chatbot, modify prompts, use templates, and preview the chat widget in real-time

## Overview

The Playground is your testing environment for fine-tuning your agent's behavior before deploying it to your website. Here you can modify the system prompt, select from pre-built templates, and see how your agent responds to questions in real-time.

<Tip>
  Always test your agent in the Playground before deploying. It's the fastest way to ensure your agent behaves as expected and provides accurate responses.
</Tip>

## Accessing the Playground

Navigate to the Playground by selecting your agent from the sidebar and clicking on **Playground** in the agent menu. The Playground opens with a split-view layout:

| Panel           | Purpose                                                  |
| --------------- | -------------------------------------------------------- |
| **Left Panel**  | Configuration controls for prompt editing and embed code |
| **Right Panel** | Live chat widget preview for testing                     |

***

## System Prompt (Instructions)

The system prompt, also called "Instructions," defines how your agent behaves, responds, and interacts with users. It's the core configuration that shapes your agent's personality and capabilities.

### What the System Prompt Controls

Your system prompt influences:

* **Personality**: Friendly, professional, technical, casual
* **Knowledge boundaries**: What topics the agent should or shouldn't discuss
* **Response format**: Length, structure, use of bullet points or paragraphs
* **Greeting behavior**: How the agent welcomes users
* **Escalation rules**: When to suggest contacting human support
* **Language and tone**: Formal vs informal communication style

### Editing the Prompt

The Playground provides a text editor for modifying your agent's system prompt:

1. Locate the **Instructions (System prompt)** section in the left panel
2. Edit the text directly in the textarea
3. Click **Save** to apply your changes

<Note>
  Changes are not saved automatically. You'll see the Save button enabled when you have unsaved modifications. A confirmation dialog will appear if you try to navigate away with unsaved changes.
</Note>

### Fullscreen Editor

For longer prompts or more comfortable editing, use the fullscreen editor:

1. Click the **Open in Editor** button below the textarea
2. Edit your prompt in the expanded modal view
3. Click **Apply Changes** to return to the main view
4. Click **Save** to persist your changes

The fullscreen editor provides more space and is particularly useful for complex system prompts with multiple sections.

### Widget Context Placeholders

When your agent is embedded as a chat widget, you can reference page and custom context directly in the system prompt. Add placeholders with double curly braces, such as `{{ page_path }}` or `{{ location }}`.

Built-in page placeholders are available automatically:

| Placeholder         | Description                                   |
| ------------------- | --------------------------------------------- |
| `{{ page_url }}`    | Current page URL without query string or hash |
| `{{ page_origin }}` | Current site origin                           |
| `{{ page_path }}`   | Current path on the site                      |

For example, on `https://example.com/products/widget?utm_source=newsletter#details`, `{{ page_url }}` resolves to `https://example.com/products/widget`, `{{ page_origin }}` resolves to `https://example.com`, and `{{ page_path }}` resolves to `/products/widget`.

For custom values, ask your website developer to pass a `context` object in the widget embed code:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch"
    }
  });
</script>
```

Then use the matching placeholder in your instructions:

```text theme={null}
You are answering for the {{ location }} location.
The visitor is currently on {{ page_path }}.
```

<Note>
  Context values are inserted only where your prompt contains matching placeholders. If a key is missing, the placeholder remains visible so you can spot the mismatch during testing.
</Note>

For the full setup, see [Widget Context](/chat-widget/context).

***

## Prompt Templates

Templates provide pre-configured system prompts optimized for common use cases. They're a great starting point that you can use as-is or customize further.

### Template Categories

The template selector organizes prompts into three groups:

| Category              | Description                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| **Base Instructions** | The default system prompt recommended for most use cases. Provides balanced, helpful responses.    |
| **Templates**         | Pre-built prompts optimized for specific scenarios (customer support, sales, technical help, etc.) |
| **Custom prompt**     | Your own custom instructions, either written from scratch or modified from a template              |

### Using Templates

<Steps>
  <Step title="Open Template Selector">
    Click the dropdown menu in the Instructions section to view available templates.
  </Step>

  <Step title="Select a Template">
    Choose a template from the list. The prompt textarea will immediately update with the selected template's content.
  </Step>

  <Step title="Customize (Optional)">
    Modify the template text to fit your specific needs. The selector will automatically switch to "Custom prompt" once you make changes.
  </Step>

  <Step title="Save Changes">
    Click Save to apply the new instructions to your agent.
  </Step>
</Steps>

### Reset to Default

If you've made changes and want to start fresh, click the **reset button** (circular arrow icon) next to the template selector. This restores the Base Instructions template.

<Warning>
  Resetting to default will replace your current instructions. Make sure to copy any custom text you want to preserve before resetting.
</Warning>

### Template Auto-Detection

The Playground intelligently detects when your instructions match a known template:

* If your text exactly matches a template, that template is shown as selected
* If you modify any character, the selector switches to "Custom prompt"
* Selecting "Custom prompt" restores your previously saved instructions

***

## Live Widget Preview

The right panel displays a fully functional preview of your chat widget. This is the same widget your website visitors will see.

### Testing Your Agent

Use the preview to test your agent's responses:

1. Type a question in the chat input
2. Send the message to see how your agent responds
3. Evaluate the response quality and accuracy
4. Adjust the system prompt if needed
5. Repeat until satisfied with the results

<Tip>
  Test with a variety of questions that your actual users might ask. Include edge cases and questions that might be outside your agent's intended scope to see how it handles them.
</Tip>

### What to Test

| Test Category            | Example Questions                                               |
| ------------------------ | --------------------------------------------------------------- |
| **Core knowledge**       | Questions your agent should definitely answer from your sources |
| **Edge cases**           | Ambiguous or unusual questions                                  |
| **Out of scope**         | Topics your agent shouldn't discuss                             |
| **Conversation flow**    | Multi-turn conversations with follow-up questions               |
| **Tone and personality** | Check that responses match your desired communication style     |

***

## Embed Code

The Playground provides the embed code snippet you'll use to add the chat widget to your website.

### Getting the Embed Code

The embed code section displays two script tags:

```html theme={null}
<script src="https://your-widget-url/embed.js"></script>
<script>humanizing.init("YOUR_PUBLIC_KEY");</script>
```

### Copying to Clipboard

1. Locate the **Embed Code** section at the bottom of the left panel
2. Click the **copy button** (clipboard icon) in the top-right corner of the code block
3. The code is copied to your clipboard, ready to paste into your website

<Note>
  The embed code includes your agent's unique public key. This key identifies your specific agent and loads its configuration.
</Note>

### Where to Add the Code

Add the embed code to your website's HTML, typically in one of these locations:

| Location            | Best For                                     |
| ------------------- | -------------------------------------------- |
| Before `</body>`    | Most websites - ensures page loads first     |
| Before `</head>`    | Sites that need widget available immediately |
| Through tag manager | Sites using Google Tag Manager or similar    |

For detailed deployment instructions, see the [Deployment guide](/agents/deployment).

***

## Saving Changes

The Playground tracks all modifications to your agent's configuration.

### Save Button States

| State        | Appearance       | Meaning                    |
| ------------ | ---------------- | -------------------------- |
| **Disabled** | Grayed out       | No changes to save         |
| **Enabled**  | Active           | Unsaved changes exist      |
| **Saving**   | "Saving..." text | Save in progress           |
| **Saved**    | "Saved" text     | Changes successfully saved |

### Unsaved Changes Warning

If you try to navigate away with unsaved changes:

1. A confirmation dialog appears
2. Choose **Leave without saving** to discard changes
3. Choose **Save and leave** to save first, then navigate
4. Choose **Cancel** to stay on the page

<Tip>
  Get into the habit of saving after each meaningful change. This way you can test incrementally and know exactly which change affected the agent's behavior.
</Tip>

***

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Start with a template">
    Begin with the Base Instructions or a relevant template. They're already optimized for common use cases and provide a solid foundation.
  </Accordion>

  <Accordion icon="flask" title="Test incrementally">
    Make one change at a time and test before making additional modifications. This helps you understand exactly what effect each change has.
  </Accordion>

  <Accordion icon="clipboard-list" title="Keep a testing checklist">
    Maintain a list of questions to test after each change. Include your most common customer questions and known edge cases.
  </Accordion>

  <Accordion icon="pen" title="Be specific in prompts">
    Vague instructions lead to inconsistent responses. Instead of "be helpful," specify "provide step-by-step instructions when explaining how to do something."
  </Accordion>

  <Accordion icon="shield" title="Set boundaries">
    Explicitly tell your agent what topics to avoid and when to suggest contacting human support. This prevents inappropriate responses.
  </Accordion>

  <Accordion icon="book" title="Reference your knowledge base">
    Remind your agent in the system prompt that it should answer from the provided knowledge base. This improves accuracy and reduces hallucination.
  </Accordion>
</AccordionGroup>

***

## Example System Prompts

### Customer Support Agent

```text theme={null}
You are a friendly customer support assistant for [Company Name].

Your role:
- Answer questions about our products and services
- Help customers troubleshoot common issues
- Guide users to relevant documentation

Guidelines:
- Always be polite and patient
- If you don't know the answer, say so and suggest contacting support@company.com
- Keep responses concise but thorough
- Use bullet points for step-by-step instructions

Never:
- Make promises about refunds or compensation
- Share internal company information
- Discuss competitors
```

### Technical Documentation Assistant

```text theme={null}
You are a technical documentation assistant for [Product Name].

Your expertise:
- API documentation and usage examples
- Configuration and setup guides
- Troubleshooting common errors

Communication style:
- Use technical terminology appropriate for developers
- Provide code examples when relevant
- Be precise and accurate

When users ask about features not in the documentation:
- Clearly state that the feature isn't documented
- Suggest they check the changelog or contact the dev team
```

### Sales Pre-Qualification Agent

```text theme={null}
You are a sales assistant for [Company Name].

Your goals:
- Answer questions about our products and pricing
- Help visitors understand which solution fits their needs
- Qualify leads by understanding their requirements

Guidelines:
- Be enthusiastic but not pushy
- Ask clarifying questions to understand needs
- Highlight relevant features based on their use case

For pricing questions:
- Provide general pricing tiers if available
- Encourage scheduling a demo for detailed quotes
- Offer to connect them with a sales representative
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="Changes not reflecting in preview">
    The preview widget may use cached responses. Try:

    1. Refresh the page
    2. Clear the conversation in the widget
    3. Ask a completely new question
  </Accordion>

  <Accordion icon="floppy-disk" title="Save button stays disabled">
    The Save button only enables when changes are detected. Ensure you've actually modified the text, not just clicked in the textarea.
  </Accordion>

  <Accordion icon="list-check" title="Template not loading">
    If templates don't appear in the selector:

    1. Refresh the page
    2. Check your internet connection
    3. Contact support if the issue persists
  </Accordion>

  <Accordion icon="robot" title="Agent gives incorrect responses">
    If responses are inaccurate:

    1. Check that your knowledge base contains the relevant information
    2. Review your system prompt for conflicting instructions
    3. Try being more specific in your prompt about response accuracy
    4. Add relevant Q\&A sources for common questions
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Add Knowledge Sources" icon="database" href="/sources/overview">
    Expand your agent's knowledge by adding more web pages, text, and Q\&A content.
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/customization/styling">
    Match your agent's visual style to your brand with colors, backgrounds, and widget settings.
  </Card>

  <Card title="Deploy to Website" icon="code" href="/agents/deployment">
    Learn how to embed your agent on your live website.
  </Card>

  <Card title="View Conversations" icon="messages" href="/agents/conversations">
    Monitor how users interact with your deployed agent.
  </Card>
</CardGroup>