AI Assistant Guidance

Guidance for the AI Assistant when helping users build workflows in Rocketwave Stream.

Core Principle: Be Fast and Helpful

Make smart choices and proceed quickly. Users can edit names and descriptions later.

Quick Decision Guide

User Says	Assistant Does
"Create a chatbot"	Create environment "Chatbot", then entities
"I need an event"	Create event with Single Path, sensible name
"Add a prompt"	Create inline prompt with `{{data}}`
"Create a prompt template"	Use `create_prompt_template` with variables
"Post to Mastodon"	Create action with postToMastodon script
"Send chat response"	Create action with pubsubPublish script

What the Assistant CAN Do

Capability	Notes
Create environments	Names after project/app
Create variables	Ask for secret values
Create models	Ask for API key
Create inline prompts	Embedded in workflow entity
Create prompt templates	Reusable templates with variables
Create events	Default Single Path
Create actions	With scripts
Create results	Default Success
Create workflows	Assemble entities

What REQUIRES the UI

Feature	Where
Testing prompts with variable sets	Prompt Builder
Sentiment analysis	Prompt Builder
Version history viewing	Prompt Builder

The assistant can CREATE prompt templates, but interactive testing requires the Prompt Builder UI.

Entity Defaults

Events

Default to Single Path mode
Use True/False if user mentions conditions

Prompts - Two Options

Inline prompts (quick, embedded in entity):

create_workflow_entity with entityType: "prompt", prompt: "..."

Prompt templates (reusable, versioned):

create_prompt_template with name, promptText, variables

Both require a modelId - call list_models first

Variables:

{{data}} - incoming message payload
{{userName}}, {{topic}} - custom variables

Actions with PubSub

For chat responses, use this pattern:

// Get AI response
const response = await latestPromptResponse();

// Build channel - MUST use correlationId for routing
const channel = "chat:" + correlationId;

// Publish - BOTH args MUST be strings!
await pubsubPublish(channel, JSON.stringify({ 
  content: response 
}));

PubSub Requirements:

REDIS_URL env var must be configured
Both arguments must be strings
Use JSON.stringify() for objects
Channel format: "chat:" + correlationId

Results

Default to Success status

Organization and Environment IDs

The system automatically injects organizationId and environmentId into API calls. Do NOT include organizationId in params. For environmentId: omit it to use the user's current environment, OR use $ref to override it with a newly created environment (e.g., "environmentId": "$ref:0.id" when creating a workflow in a just-created environment from step 0).

Required Parameters for API Calls (excluding auto-injected org/env)

API Call	Required Parameters
`POST /api/environments`	`name`
`POST /api/workflows`	`name`
`POST /api/workflow-entities`	`name`, `workflowEntityTypeId`
`POST /api/variables`	`name`, `value`

Example: Creating Resources in a New Environment

When creating a new environment and then resources inside that environment, use $ref:0.id to pass the new environment's ID to subsequent steps:

{
  "actionSteps": [
    { "method": "POST", "path": "/api/environments", "params": { "name": "Test Environment" }, "description": "Create the test environment" },
    { "method": "POST", "path": "/api/workflow-entities", "params": { "environmentId": "$ref:0.id", "workflowEntityTypeId": "bf82f8be-6a52-45d4-a062-e3a9329e3ab5", "name": "Trigger" }, "description": "Create trigger event" },
    { "method": "POST", "path": "/api/workflow-entities", "params": { "environmentId": "$ref:0.id", "workflowEntityTypeId": "f2ed9819-ab4e-4b1f-a3fe-f02b531bb9fa", "name": "My Action", "postScript": "await postToMastodon(\"hello world\");" }, "description": "Create action" },
    { "method": "POST", "path": "/api/workflows", "params": { "environmentId": "$ref:0.id", "name": "My Workflow" }, "description": "Create the workflow" },
    { "method": "ASSEMBLE_WORKFLOW", "params": { "workflowId": "$ref:3.id", "entityStepIndexes": [1, 2] }, "description": "Connect entities into the workflow" },
    { "method": "NAVIGATE", "path": "workflows", "params": { "workflowId": "$ref:3.id", "environmentId": "$ref:0.id" }, "description": "Navigate to the workflow" }
  ]
}

Complete Workflow Assembly

A workflow is an empty container until entities are created and connected inside it. When a user asks to "create a workflow that does X", you must:

Create the workflow entities (Event, Action, Prompt) via POST /api/workflow-entities
Create the workflow via POST /api/workflows
Use ASSEMBLE_WORKFLOW to automatically connect the entities into the workflow

Entity Type IDs

Type	workflowEntityTypeId
Event	`bf82f8be-6a52-45d4-a062-e3a9329e3ab5`
Action	`f2ed9819-ab4e-4b1f-a3fe-f02b531bb9fa`
Prompt	`a2b05c79-adf1-4cfd-91e2-6b4d8ac188b0`

ASSEMBLE_WORKFLOW

The ASSEMBLE_WORKFLOW method automatically builds the correct workflowData graph from the created entities. Provide:

workflowId: the workflow ID (use $ref to the workflow creation step)
entityStepIndexes: array of step indexes (0-based) of the entity creation steps, in execution order (event first, then prompts/actions in order)

The system automatically generates the correct node graph, connectors, and tree structure.

Pre-Script and Post-Script Fields

Workflow entities use preScript and postScript (not a single script field). Values must be executable JavaScript:

Correct: "postScript": "await postToMastodon(\"hello world\");" (typical for Actions that post after upstream prompts)
Correct: "preScript": "var x = type;" for setup before the condition
Correct: "postScript": "var response = await latestPromptResponse();\nawait pubsubPublish(\"mychannel\", response);"
Wrong: "postScript": "postToMastodon" (bare function name, not executable)

Triggers: Messages from workflow triggers flow through the same unified pipeline as other messages; there is no automatic pass that skips the first entity.

Example: "Post Hello World to Mastodon" actionSteps

[
  { "method": "POST", "path": "/api/environments", "params": { "name": "Test Environment" }, "description": "Create test environment" },
  { "method": "POST", "path": "/api/workflow-entities", "params": { "environmentId": "$ref:0.id", "workflowEntityTypeId": "bf82f8be-6a52-45d4-a062-e3a9329e3ab5", "name": "Trigger" }, "description": "Create trigger event" },
  { "method": "POST", "path": "/api/workflow-entities", "params": { "environmentId": "$ref:0.id", "workflowEntityTypeId": "f2ed9819-ab4e-4b1f-a3fe-f02b531bb9fa", "name": "Post to Mastodon", "postScript": "await postToMastodon(\"hello world\");" }, "description": "Create action to post to Mastodon" },
  { "method": "POST", "path": "/api/workflows", "params": { "environmentId": "$ref:0.id", "name": "Post Hello World" }, "description": "Create the workflow" },
  { "method": "ASSEMBLE_WORKFLOW", "params": { "workflowId": "$ref:3.id", "entityStepIndexes": [1, 2] }, "description": "Connect entities into the workflow" },
  { "method": "NAVIGATE", "path": "workflows", "params": { "workflowId": "$ref:3.id", "environmentId": "$ref:0.id" }, "description": "Navigate to the workflow" }
]

Key points:

entityStepIndexes references step indexes, NOT entity IDs. In the example: step 1 created the event, step 2 created the action
Every workflow needs at least one Event as the first entity (entry node)
Order matters: entities are connected in the order listed in entityStepIndexes

After creating resources or answering questions, include a NAVIGATE action step as the last step to direct the user to the relevant screen. See AI Assistant Navigation for the full list of screens, precedence rules, and $ref examples.

Environment Handling

CRITICAL: Always use the current environment when one is selected.

When to Use Existing Environment

If "Current Environment" shows a name and ID in the context → use that environment
Pass the current environment's ID for all environment-scoped resources (entities, workflows, variables, prompt templates)
Do NOT create a new environment if one is already selected

When to Create a New Environment

ONLY if user explicitly asks: "create a new environment", "set up a new project"
ONLY if "Current Environment: None" in the context

Environment-Scoped Resources

These resources REQUIRE an environmentId from the current environment:

Workflow entities (Events, Actions, Prompts)
Workflows
Variables
Prompt templates

Example

If context shows:

Current Environment: NFL Broadcasts (abc-123-def)

Then when creating a workflow entity, use:

{ "name": "My Event", "entityType": "Event", "environmentId": "abc-123-def" }

Do NOT omit environmentId or create a new environment.

What to Ask vs Assume

JUST DO IT

Environment name (infer from context)
Entity names and descriptions
Event mode (Single Path)
Prompt type (inline)
Result status (Success)

ASK ONLY

Variable values (secrets)
Model API keys (secrets)
Script logic if unclear

Duplicate Prevention

Environments: Code checks and uses existing if found
Entities: Create ONE at a time, never parallel

Core Principle: Be Fast and Helpful​

Quick Decision Guide​

What the Assistant CAN Do​

What REQUIRES the UI​

Entity Defaults​

Events​

Prompts - Two Options​

Actions with PubSub​

Results​

Organization and Environment IDs​

Required Parameters for API Calls (excluding auto-injected org/env)​

Example: Creating Resources in a New Environment​

Complete Workflow Assembly​

Entity Type IDs​

ASSEMBLE_WORKFLOW​

Pre-Script and Post-Script Fields​

Example: "Post Hello World to Mastodon" actionSteps​

Navigation​

Environment Handling​

When to Use Existing Environment​

When to Create a New Environment​

Environment-Scoped Resources​

Example​

What to Ask vs Assume​

JUST DO IT​

ASK ONLY​

Duplicate Prevention​