Skip to content

FlowDrop Playground

Interactive chat-based interface for testing and debugging workflows with real-time execution feedback.

Overview

The flowdrop_playground module provides an interactive testing environment for workflows. It presents a chat-like interface where you can send messages to a workflow, see real-time execution progress, handle interrupts inline, and inspect session state — all without setting up triggers or external integrations.

The playground uses the StateGraph orchestrator for execution and builds on sessions for multi-turn conversation tracking. It's the fastest way to test and iterate on workflow designs.

Optional

The Playground is an operator console over a run, not part of the engine. Nothing else in FlowDrop requires it: sessions, turns, messages and workflows work without it, and uninstalling it deletes only its own settings. What changes without it is what a session holds: the Playground's reporting rows (see Reporting rows) are not written, so a session keeps only what people and the workflow wrote.

Dependencies

Configuration

Admin Pages

Path Description
/admin/flowdrop/config/playground Playground settings
/admin/flowdrop/workflows/{workflow_id}/playground Open the playground for a specific workflow

Settings

flowdrop_playground.settings, edited at /admin/flowdrop/config/playground. Nothing outside the Playground reads these keys.

Key Type Default What it does
auto_run boolean false Run a workflow without a chat input as soon as its Playground page loads. Off by default: rendering a page should not start a run.
persist_job_logs boolean true Post one log row into the session per finished job. A storage lever: a loop of 500 iterations writes 500+ rows, and hiding log rows in the UI does not stop them being written.
notice_level full | outcome_only | none full Which notices the Playground posts. full: all of them. outcome_only: all but "started". none: no notices except error rows.

The notices are: "started" (progress); the run outcome notice, or a card for a failed, paused or cancelled run; "Workflow execution completed with no output."; "Execution stopped by user."; and the reset notice (all outcomes). Error rows are never filtered: the cron timeout notice, "Execution failed" and cron's stuck-session recovery notice are posted at every level. Changing a key affects new rows only.

Sites updated from an earlier release get persist_job_logs: true and notice_level: full, which is how they behaved before the keys existed.

drush config:set flowdrop_playground.settings notice_level outcome_only

Permissions

Permission Description
administer flowdrop_playground Edit the Playground settings. Also bypasses the ownership checks of the Playground session API. Restricted.

Using the Playground needs no permission of its own: sending a message checks execute session workflow (from flowdrop_session), and the session and message permissions decide which sessions a user sees. The former execute playground workflow permission was never checked and has been removed.

Reporting rows

The Playground's observers post what its console shows into the session, with origin: playground: the notices above, one log row per finished job, and the failure rows: "Execution failed" for a failed turn or a resume that failed or threw, and cron's "Session recovered from stuck '…' state by cron." (TurnFailureObserver, #3592467). They subscribe to JobCompletedEvent, PipelineCompletedEvent and the session events (SessionTurnStartedEvent, SessionTurnResultsEvent, SessionStoppedEvent, SessionResetEvent, SessionTurnFailedEvent); see Session Turns & Events. The two reporting keys filter them, except the failure rows, which are posted at every setting. Without the Playground a session gets none of these rows, failures included.

Tips and Tricks

Accessing the Playground

From the workflow list at /admin/flowdrop/workflows, each workflow has a "Playground" action link. You can also navigate directly to /admin/flowdrop/workflows/{workflow_id}/playground.

Session Management

Each playground interaction creates a session. You can:

  • Create multiple sessions for the same workflow to test different scenarios
  • View message history within a session
  • Reset a session to start over
  • Delete old sessions to clean up

Interrupt Handling

When a workflow triggers an interrupt (confirmation, choice, text input, or form), the playground UI renders the appropriate input inline in the chat. You can respond directly without leaving the page.

Debugging Workflows

The playground shows real-time execution status as nodes execute. Combined with the message history, this makes it easy to trace data flow and identify issues in your workflow logic.

Developer API

API Endpoints

Sessions for a workflow (the Playground's own):

Method Path Description
GET /api/flowdrop/workflows/{workflow_id}/playground/sessions List sessions for a workflow
POST /api/flowdrop/workflows/{workflow_id}/playground/sessions Create a new session

One session is served by flowdrop_session under /api/flowdrop/sessions/{uuid} (read, delete, messages, turn, stop, reset, interrupts); see the REST API reference. The Playground's per-session paths below are deprecated aliases, removed in 3.0. They answer as before, with access decided by the session entity, and every response carries a Deprecation header and a Link to its successor:

Method Path Successor
GET, DELETE /api/flowdrop/playground/sessions/{session_id} /api/flowdrop/sessions/{uuid}
GET /api/flowdrop/playground/sessions/{session_id}/messages /api/flowdrop/sessions/{uuid}/messages
POST /api/flowdrop/playground/sessions/{session_id}/messages /api/flowdrop/sessions/{uuid}/turn (202 + turn result instead of 200 + the user's row)
GET /api/flowdrop/playground/sessions/{session_id}/messages/{message_id} and …/status /api/flowdrop/sessions/{uuid}/messages
POST /api/flowdrop/playground/sessions/{session_id}/stop, …/reset /api/flowdrop/sessions/{uuid}/stop, …/reset

References