Soul Machines Experiments User Guide

Transform your AI agents into engaging, lifelike interactions with Soul Machines digital avatars. This guide will walk you through everything you need to know to get started with the Experiments playground.

? We want your feedback! Experiments is in beta and your input shapes what we build next. Found a bug? Have an idea? Something confusing? Tell us →

Table of Contents

1. Overview
2. Getting Started
3. Creating an Interaction
4. Supported AI Services
5. Managing Credentials
6. Advanced Configuration
7. Troubleshooting
8. Share Your Feedback

Overview

The Experiments playground allows you to create AI-powered conversational experiences featuring Soul Machines digital avatars. You can connect your existing AI agents from services like OpenAI, Google Gemini, Salesforce, and more to create real-time interactions.

Note: Experiments is currently in beta and is only available to select organizations.

What You Can Do

• Create Interactive AI Experiences: Connect your AI agents to lifelike digital avatars
• Test & Iterate: Quickly prototype and test different configurations
• Customize Avatars: Choose from various avatars and styles to match your use case

Don't see the integration you want? Request it here and let us know what you'd like to see next!

Getting Started

Creating Your Account

1. Navigate to the Experiments signup page at https://workforce.soulmachines.com/auth/signup-experiments
2. Fill in your details:
   • First name and last name
   • Work email address
   • Organization name
   • Password (must include uppercase, lowercase, number, and special character)
3. Click Create account
4. Verify your email address
5. You'll be automatically redirected to the Experiments playground

Already Have an Account?

If you already have a Soul Machines Digital Workforce account, you can sign in directly and access Experiments if your organization has the feature enabled.

Creating an Interaction

Follow these steps to create your first AI-powered interaction:

Step 1: Select an AI Service

Choose the AI service that powers your agent:

Coming Soon

Want one of these integrations sooner? Let us know! Your feedback helps us prioritize.

Step 2: Enter Your Agent ID

Enter your OpenAI Workflow ID (starts with wf...)

Step 3: Choose an Avatar

Select a digital avatar to represent your AI agent. Each avatar offers different style variants:

• Formal: Professional business attire
• Smart Casual: Relaxed professional look
• Scrubs: Medical/healthcare setting

Step 4: Configure Your Agent (Optional)

Customize your agent's personality and behavior:

Agent Features

A comma-separated list of capabilities that your AI agent can help users with. This helps the system understand what topics and tasks your agent is designed to handle, enabling smarter routing and more focused conversations.

How it works: When users ask questions, the system uses your features list to determine if the request matches your agent's capabilities. Well-defined features lead to more accurate and helpful responses.

Best practices:

• Be specific about what your agent can do
• Use action-oriented phrases (e.g., "Account lookups" not just "Accounts")
• Include both broad categories and specific tasks
• List 5-10 distinct capabilities for best results

Example features by use case:

Conversation Prompt

Provides context and purpose for your agent's conversations. This shapes how your agent understands its role and guides its responses throughout the interaction.

How it works: The conversation prompt acts as background context that influences every response. It helps the agent stay focused on its intended purpose and handle edge cases appropriately.

Best practices:

• Describe the primary purpose in 1-2 sentences
• Include any important constraints or boundaries
• Mention the target audience if relevant
• Keep it concise but informative

Example prompts:

Step 5: Create Your Interaction

1. Click Create Interaction
2. Wait for the interaction to be generated (this may take a few seconds)
3. Once complete, you'll see a success message with your interaction URL
4. Click Launch Interaction to open your AI experience in a new tab

Debugging Your Interaction

When launching your interaction, add ?debug=true to the URL. This enables debug mode which shows additional information useful for testing and development. Just don't forget to remove it from the URL before sharing it with others.

Supported AI Services

OpenAI Agent Builder

Connect agents created with OpenAI's platform.

Required Credentials:

• API Key

Configuration:

1. Go to Manage Credentials
2. Select "OpenAI" from the dropdown
3. Enter your OpenAI API Key
4. Click Save Credentials (credentials are validated before saving)

Managing Credentials

Access the Manage Credentials section from the sidebar to add, edit, or remove service credentials.

Adding New Credentials

1. Click Manage Credentials in the sidebar
2. Select a service from the dropdown
3. Fill in the required fields
4. Click Save Credentials
5. Credentials are automatically validated before saving

Credential Validation

All credentials are validated when you save them:

• ✅ Green checkmark: Credentials verified and working
• ❌ Red X: Validation failed (check your credentials)
• ?: Not yet validated

Testing Existing Credentials

Click the Test button next to any saved credential to verify it's still working.

Editing Credentials

1. Find the service in your Connected Services list
2. Click Edit
3. Update the fields as needed
4. Click Save Credentials (re-validation occurs)

Deleting Credentials

1. Find the service in your Connected Services list
2. Click Delete
3. Confirm the deletion

Security Note: Credentials are stored locally in your browser. They are never sent to Soul Machines servers except when creating interactions.

Advanced Configuration

Expand the Advanced Configuration section in the interaction form to access power-user settings.

Phatic Response System

Enable automatic "thinking" messages to improve user experience during processing delays.

Agent Settings

Progress Threads

Display progress indicators to users showing conversation milestones.

Configuration:

1. Set a Group Title (e.g., "Progress")
2. Add Steps that describe each milestone (e.g., "Processing request", "Analyzing data")
3. Steps appear as the conversation progresses

Content Cards

Define interactive cards that appear during the conversation at key moments.

For each card, configure:

Example:

• Goal: "Order Confirmed"
• Milestone: "The user has completed their order"
• Card Type: Info
• Instructions: "Show order summary with confirmation number and estimated delivery date"

Troubleshooting

Common Issues

"Please select a service"

You must choose an AI service before creating an interaction.

"Please enter a workflow/agent ID"

Enter the identifier for your AI agent from the service provider.

Credentials Validation Failed

• Double-check your API keys and credentials
• Ensure your service subscription is active
• Verify the endpoint/instance URLs are correct

Interaction Creation Failed

• Check that all required fields are filled
• Verify your credentials are valid (use the Test button)
• Ensure your AI service is responding correctly

Getting Help

If you continue to experience issues:

1. Check the browser console for error messages
2. Clear your browser cache and try again
3. Contact us — we're here to help and want to hear about any issues you encounter

Best Practices

Setting Up Your OpenAI Agent

Before creating an interaction in Experiments, you'll need to set up your agent in OpenAI's platform. Here's how to configure it for optimal results with Soul Machines avatars.

Step 1: Create Your Agent in OpenAI

1. Go to OpenAI Platform and sign in
2. Navigate to Agent Builder
3. Create a new agent/workflow and note the Workflow ID (starts with wf...)

Step 2: Design for Real-Time Conversation

This is not a chatbot. Unlike async messaging where users send a message and wait, Soul Machines creates a real-time, synchronous interaction — like a video call with an AI. Users are actively watching and listening, expecting immediate engagement.

What this means for your agent:

• Response time matters. Users are present and waiting. While our platform smooths over delays with natural "thinking" responses, your agent should still aim for quick, focused replies.
• Conversation flows naturally. Think of it as a phone call, not a support ticket. Users expect back-and-forth dialogue, not long monologues.
• Ideally, have multiple capabilities. Your agent should ideally be able to handle a variety of tasks and questions, not just one. This way, if a task is taking longer than expected, the agent can switch to a different task and keep the user engaged.

Our platform handles the rest. Soul Machines automatically:

• Converts your agent's text responses into natural speech
• Manages formatting (you don't need to worry about markdown)
• Provides "thinking" responses during longer processing times
• Handles the real-time streaming and synchronization

Step 3: Tips for Your Agent Instructions

When configuring your agent in OpenAI, keep in mind another our agent is handling the conversation, so you don't need to worry about the real-time nature. You do however want your agent to be clear about its role and capabilities, and provide clear and concise responses to our conversation agent. You can use the following example as a guide:

You are an assistant designed to assist busy executives with Calendar administration. You can access their calendar and take actions within it. Make assumptions to be proactive and helpful.

Our system will connect to you agent and determine what it's instructions are, and what tools/capabilities it has.

Step 4: Test Your Agent

Before connecting to Experiments:

1. Test your agent directly in OpenAI's playground
2. Verify responses are appropriately concise
3. Check that the agent handles edge cases gracefully
4. Ensure the tone matches your intended use case

For Better Interactions

1. Write clear welcome messages that set user expectations
2. List specific features your agent can help with
3. Choose appropriate tone for your audience
4. Test thoroughly using the debug mode

Getting Your Experience to Flow Smoothly

If conversations feel disconnected or the avatar isn't responding as expected, here's how to diagnose and fix common issues:

1. Use debug mode to see what's happening under the hood

   Add ?debug=true to your interaction URL. This shows you what our conversation agent is passing to your backend agent, and what it's returning. Look for mismatches between what's being asked and what's being answered.

2. Inspect your backend agent's logs

   Check the logs in your OpenAI dashboard (or whichever service you're using). This helps you see exactly what prompts your agent is receiving and how it's responding — before our system processes the response.

3. Make sure Agent Features accurately describes your agent's capabilities

   Our system uses the Agent Features field to understand what your agent can do. If this doesn't match your agent's actual tools and capabilities, the conversation agent may ask for things your agent can't deliver, or miss capabilities it has.

4. Add context to the Conversation Prompt if needed

   If your agent needs specific context to function well (industry terminology, company-specific information, behavioral guidelines), add it to the Conversation Prompt field. This context is passed to our conversation agent.

5. Review your backend agent's instructions

   Sometimes the issue is in your agent's base configuration. Make sure its instructions are clear about its role, what it can and can't do, and how it should respond. Vague instructions lead to vague responses.

Still stuck? Send us details about what you're seeing in debug mode and we'll help you troubleshoot.

For Credentials

1. Use service accounts where possible
2. Rotate API keys periodically
3. Test credentials after any service changes
4. Don't share your browser with others (credentials are stored locally)

Share Your Feedback

Experiments is built for you, and we're actively developing based on your input. We'd love to hear from you:

Your feedback directly influences our roadmap. Thank you for helping us improve!

Glossary

Last updated: December 2025