AI Assistant Navigation

Navigation is an action step the AI assistant can include in its plan. When the assistant creates resources or answers questions, it should include a NAVIGATE step as the final action step to direct the user to the relevant screen.

How Navigation Works

Navigation is planned by the LLM as a standard action step with method: "NAVIGATE":

1. The Information prompt plans action steps, including a NAVIGATE step as the last step
2. The Execute Action Steps script recognizes NAVIGATE and sets the navigation intent
3. The Result Response script forwards the navigation intent to the frontend via the done SSE event
4. The frontend reads the intent and calls router.push(url)
5. Relevant caches are invalidated for the target screen

NAVIGATE Action Step Format

{
  "method": "NAVIGATE",
  "path": "environments",
  "params": {},
  "description": "Navigate to environments page to view the new environment"
}

Fields

Field	Required	Description
method	Yes	Must be "NAVIGATE"
path	Yes	Screen name (see table below)
params	No	URL parameters — use $ref to pass IDs from previous steps
description	Yes	Brief reason for navigating (shown in logs)

Available Screens

Screen Name	Route Path	Description	When to Navigate
environments	/environments	Environment management	After creating or listing environments
workflows	/workflows	Workflow canvas	After creating a workflow
workflow-entities	/workflow-entities	Entity list	After creating entities (events, actions, prompts)
prompt-builder	/prompt-builder	Prompt template editor	After creating prompt templates
settings	/settings	Models and variables	After creating models or variables
dashboard	/dashboard	Main dashboard	General overview requests

Navigation Precedence

When multiple resources are created in the same request, use the highest priority screen for the NAVIGATE step:

1. Workflow (highest) — include workflowId and environmentId in params
2. Prompt Template
3. Workflow Entity
4. Model or Variable (settings)
5. Environment (lowest)

Referencing Created Resources with $ref

NAVIGATE steps support the same $ref:N.field pattern as other action steps. This lets you pass IDs from resources created in earlier steps.

Example: Create environment then navigate

{
  "actionSteps": [
    {
      "method": "POST",
      "path": "/api/environments",
      "params": { "name": "Test Environment" },
      "description": "Create the test environment"
    },
    {
      "method": "NAVIGATE",
      "path": "environments",
      "params": {},
      "description": "Navigate to environments page"
    }
  ]
}

Example: Create workflow then navigate with IDs

{
  "actionSteps": [
    {
      "method": "POST",
      "path": "/api/environments",
      "params": { "name": "My Project" },
      "description": "Create the project environment"
    },
    {
      "method": "POST",
      "path": "/api/workflows",
      "params": { "name": "Main Workflow", "environmentId": "$ref:0.id" },
      "description": "Create the workflow in the new environment"
    },
    {
      "method": "NAVIGATE",
      "path": "workflows",
      "params": { "workflowId": "$ref:1.id", "environmentId": "$ref:0.id" },
      "description": "Navigate to the created workflow"
    }
  ]
}

Example: Information-only with navigation

When the intent is "information" (no create/update/delete), a NAVIGATE step can still direct the user to the relevant screen:

{
  "intent": "information",
  "actionSteps": [
    {
      "method": "NAVIGATE",
      "path": "prompt-builder",
      "params": {},
      "description": "Navigate to prompt builder for template testing"
    }
  ]
}

Environment Switching for Workflows

When navigating to a workflow, you MUST include environmentId in params. The workflows page validates that the requested workflow belongs to the currently selected environment. Without the correct environmentId, the workflow will not load.

The frontend will:

1. Read environmentId from navigation params
2. Switch the app-wide selected environment to match
3. Navigate to /workflows?workflowId={id}&environmentId={envId}
4. The workflows page loads the workflow because environments now match

This is critical when:

• The assistant creates a new environment AND a workflow in the same session
• The workflow is created in a different environment than the user's currently selected one