Playground Section

Overview

The Playground is your testing and interaction environment where you can directly communicate with your AI agents, test their responses, and refine their behavior. This interface allows you to chat with agents from your team, view execution logs, and manage conversation history.

1. Playground Dashboard

Playground Main Interface - Central hub for agent testing and interaction

The playground interface provides:

Agent Selector: Dropdown to choose which agent to interact with from your team
Chat Interface: Real-time conversation with your selected agent
Chat History Sidebar: Access to previous conversations with search functionality
Worker Execution Logs: Detailed view of agent processing steps
Input Methods: Text, JSON, and file upload capabilities

2. Agent Selection and Configuration

Selecting an Agent

Playground Agent Selector Interface Playground Agent Selector - Choose and configure agents for testing

Click the Agent Selector Button: Located in the top-right of the playground interface
Choose from Available Agents: The dropdown shows all agents from your current team
Agent Selection: Click on any agent name to select it for testing

Available Agents:

Only agents belonging to your current team are displayed
Agents are loaded from the database and filtered by team_id
The selector shows the agent's title/name as configured in the flow designer

Agent State:

Agents run with their current configuration from the flow designer
No separate testing configuration - agents use their live settings
Supports both conversational and non-conversational agent types
Switching agents clears the current conversation and starts fresh

3. Chat Interface and Interaction

Message Input System

The chat interface uses the SearchInput component which provides multiple input methods:

Text Input:

Standard text area for typing natural language messages
Auto-resizing based on content length
Press Enter to send, Shift+Enter for new lines
Placeholder text guides user input

JSON Input Capabilities:

Automatic Detection: Input starting and ending with { } or [ ] is recognized as JSON
Validation: Real-time JSON parsing with error detection
Error Display: Red border and error message for invalid JSON
Monospace Font: Automatically applied for JSON input
Blue Indicator: Visual indicator when JSON input is detected

JSON Editor Mode:

Toggle Button: Click the JSON icon to switch to visual editor mode
Interactive Editor: Uses JsonEditor component for structured editing
Mode Switching: Converts between text and visual JSON representations
Error Prevention: Built-in validation prevents invalid JSON submission

File Upload (OCR):

Supported Formats: Images (image/*) and PDFs (application/pdf)
OCR Processing: Uses Tesseract technology for text extraction
Progress Indication: Shows "Extracting..." status during processing
Auto-Send: Extracted text is automatically sent to the agent
Error Handling: Displays OCR failure messages when processing fails

Message Display:

User Messages: Blue bubbles on the right side with copy functionality
Agent Responses: Bordered containers on the left with agent name header
JSON Formatting: Special formatting for JSON messages with indicators
Response Rendering: Uses AgentJsonView for structured display of agent outputs

Agent Execution Process

Conversation Handling: The playground handles two types of agents differently:

Conversational Agents (isConversational: true):

Input Format: Uses message and history structure
History Management: Previous messages passed as conversation context
Context Preservation: Full conversation history maintained across interactions

Non-Conversational Agents (isConversational: false):

Input Format: Uses question and conversation_history structure
History Format: Previous messages formatted as "User: message\nBot: response"
JSON Support: Spreads JSON input directly into agent parameters

Agent Execution Flow:

Load Agent: Retrieves agent configuration using agents.loadAgent(id, teamId)
Prepare Parameters: Formats input based on agent type and input format
Execute: Calls agent.execute(parameters) with logWriter callback
Handle Response: Displays agent output and captures execution logs
Save History: Stores conversation in database for later retrieval

4. Chat History and Management

Accessing Chat History

Playground Chat History Interface Playground Chat History - View and manage conversation history

Click the History Button: Located in the top-right corner (History icon)
Sidebar Opens: Chat history appears in a collapsible sidebar panel
Search Functionality: Search bar at the top allows filtering conversations

Chat History Features

Database Storage:

Conversations are stored in chat_history table in the database
Each message is saved with user_id, agent_id, team_id, and conversation_id
Messages are grouped by conversation_id to reconstruct full conversations

Search and Filter:

Text Search: Search through conversation content using the search input
Real-time Filtering: Results update as you type
Highlight Matches: Search terms are highlighted in yellow
Content Search: Searches through all message content, not just titles

Conversation Display:

First Message Preview: Shows the first message as conversation title
Timestamp Display: Shows time for today's conversations, date for older ones
Agent Names: Displays which agent was used in each conversation
Click to Load: Click any conversation to load it back into the chat interface

History Management:

Automatic Saving: All conversations are automatically saved during chat
Per-User Storage: Each user sees only their own conversation history
Team Filtering: Only shows conversations with agents from the current team
Conversation Restoration: Loading a conversation restores messages and selects the agent

5. Worker Execution Logs

Execution Log Display

The playground includes an ExecutionLogDisplay component that shows detailed information about agent processing:

Log Interface:

Collapsible Panel: Click to expand/collapse the execution log section
Step Counter: Shows total number of worker executions (e.g., "Execution Log (5 steps)")
Auto-Clear: Logs are cleared when starting a new conversation
Visibility Toggle: Use showExecutionLogs state to show/hide details

Log Entry Format: Each execution entry displays:

Green Checkmark: Success indicator for completed workers
Worker Type: Extracted from execution.worker?.config?.type
Timestamp: Shows local time when worker completed execution
Error Display: Red text showing any worker errors
State Data: First 100 characters of JSON-formatted state data

Captured Information:

Worker Configuration: Type and settings of each executed worker
Execution Timing: Precise timestamp using Date.now()
State Information: Worker input/output data and processing results
Error Details: Any errors encountered during worker execution

Log Writer Integration:

Uses onWorkerExecuted callback passed to agent.execute()
Automatically captures all worker executions during agent processing
Saves logs to database via addLog() function for persistence
Updates UI state with setWorkerExecutions() for real-time display

Database Logging:

Logs are saved to logs table with team_id, agent, worker, state, and execution fields
Includes worker handles array for additional debugging context
Associates logs with specific execution sessions using unique IDs

Debugging Capabilities

Available Debug Information: The playground provides debugging through the execution logs rather than interactive debugging tools:

Worker State Analysis:

State Data Review: Examine the JSON state data captured from each worker
Error Message Analysis: View detailed error messages when workers fail
Execution Timing: Compare timestamps between workers to identify slow operations
Worker Type Identification: See which specific workers are executing in sequence

Console Logging:

Worker executions are logged to browser console with format:
```
[Worker Executed] type="worker_type", state=
```
Includes full state object for detailed inspection during development
Error handling and debugging can be done through browser developer tools

6. Error Handling and User Experience

Error States

Agent Selection Errors:

No Agent Selected: Shows "Select an agent to start chatting" message when no agent is chosen
Agent Loading Failures: Displays "Agent not found or not accessible for current team" errors
Team Access Issues: Handles cases where user doesn't have access to selected team's agents

Input Validation:

JSON Errors: Invalid JSON shows red border with "Invalid JSON format" message
OCR Failures: File processing errors display as "❗️ OCR failed: [error message]"
Send Button State: Automatically disabled when input is invalid or agent is processing

Agent Execution Errors:

Generic Error Response: Shows "Error processing request." when agent execution fails
Network/API Issues: Handled through try-catch blocks in agent execution
Worker Failures: Individual worker errors shown in execution logs with red text

7. User Interface Features

Visual Design Elements

Loading States:

Typing Animation: Three animated dots with gradient colors during agent processing
OCR Processing: "Extracting..." text shown during file processing
Send Button Disabled: Button becomes inactive during processing to prevent duplicate sends

Message Styling:

User Messages: Blue gradient bubble with right alignment and copy functionality
Agent Messages: Left-aligned with border, agent name header, and structured JSON display
JSON Indicators: Special blue header for JSON input messages with "JSON" badge
Copy Functionality: Copy button appears for all messages with success feedback

Interface Responsiveness:

Auto-scroll: Automatically scrolls to bottom when new messages arrive
Resizable Sidebar: Chat history panel can be toggled open/closed
Auto-resize Input: Text area grows with content up to maximum height
Responsive Layout: Interface adapts to different screen sizes

8. Technical Implementation Details

Component Architecture

Main Playground Component (Chat):

State Management: Uses useMultiState for agent selection and UI state
Agent Loading: Filters agents by current team ID from database
Message Management: Handles conversation state with AgentChatMessage[] array
History Integration: Connects to ChatHistory component for conversation persistence

Key State Variables:

selectedAgent: Currently selected agent ID for testing
messages: Array of conversation messages (user and agent)
workerExecutions: Array of worker execution logs for debugging
showExecutionLogs: Boolean controlling execution log visibility
chatHistory: Array of saved conversation sessions

Database Integration:

Agent Selection: Queries agents table filtered by team_id
Chat Persistence: Saves to chat_history table with user, agent, and team associations
Execution Logging: Stores worker execution data in logs table

On this page