40  Automations User Guide

40.1 Overview

This guide covers how to create, test, and publish automated workflows using Sophea Automations.

40.2 Getting Started

40.2.1 Opening the builder

  1. Log in to the Sophea Nous web UI
  2. Click “Automations” in the sidebar
  3. Click “Create Flow” to open the builder

40.2.2 The builder interface

The builder has four main areas:

  1. Canvas: The flow diagram showing triggers and actions
  2. Left sidebar: Run history, flow settings, and flow list
  3. Right panel: Step configuration (appears when a step is selected)
  4. Test panel: Step testing and sample data (bottom right)

40.3 Creating Your First Flow

40.3.1 Step 1: Choose a trigger

Every flow starts with a trigger. Available triggers:

  • Manual Trigger: Start the flow manually by clicking “Run”
  • Schedule: Run the flow on a recurring schedule (daily, weekly, monthly)
  • Webhook: Start the flow when an external system sends an HTTP request
  • Agent Run Completed: Start the flow when a Nous agent finishes
  • Document Indexed: Start the flow when a document completes indexing into the knowledge base
  • Connector Sync Completed: Start the flow when a connector sync cycle completes successfully
  • Connector Sync Failed: Start the flow when a connector sync cycle fails

To add a trigger: 1. Click the trigger node on the canvas 2. Select the trigger type from the dropdown 3. Configure the trigger settings in the right panel

40.3.2 Step 2: Add actions

Actions are the steps that run after the trigger. To add an action:

  1. Click the “+” button below the trigger or any action
  2. Browse the piece picker or search for a specific action
  3. Select the action you want to add
  4. Configure the action’s inputs in the right panel

40.3.3 CSV and date defaults

Two common data actions start with supported defaults that you can change when your input requires a different format:

  • Convert CSV to JSON sets Delimiter Type to Comma.

Convert CSV to JSON settings with Delimiter Type set to Comma

Convert CSV to JSON with Comma selected as the delimiter
  • Add/Subtract Time sets both From Time Format and To Time Format to DDD MMM DD YYYY HH:mm:ss (Sun Sep 17 2023 11:23:58).

Add/Subtract Time settings with the From Time Format and To Time Format defaults selected

Add/Subtract Time with supported input and output format defaults

40.3.4 Available Sophea actions

Category Actions
Knowledge ask_nous_knowledge, search_knowledge, batch_search_knowledge, fetch_chunks
AI ask_workspace_model, run_nous_agent
Agent lifecycle start_agent_run, get_agent_run_status, cancel_agent_run, get_agent_run_artifacts
Approvals request_human_approval, create_approval_task, llm_approval
Workspace list_connectors, list_workspace_users, list_workspace_teams, fetch_saved_searches, notify_workspace, send_workspace_email
Documents upload_document, get_document_status

40.3.5 Step 3: Reference previous steps

You can reference the output of previous steps using the {stepName.output} syntax. For example: - {trigger.output.body.email} to reference the email from a webhook trigger - {step_1.output.answer} to reference the answer from a knowledge search - {step_1.output.chunks[0].content} to reference the first chunk from a search

40.3.6 Step 4: Test the flow

Before publishing, test each step:

  1. Select the step you want to test
  2. Click “Test Step” in the test panel
  3. The step will execute and show the output
  4. Use the output to configure subsequent steps

40.3.7 Step 5: Publish the flow

  1. Click “Publish” in the top right
  2. The flow is now active and will run when the trigger fires
  3. Published flows can be viewed in the “Runs” tab

40.4 Using Templates

40.4.1 Browsing templates

  1. Click “Templates” in the sidebar
  2. Browse by category using the category carousel
  3. Click any template to see a preview

40.4.2 Template categories

Category Count Examples
Knowledge 11 FAQ answer, gap analysis, policy Q&A
Reports 11 Executive summary, postmortem, release notes
Research 10 Competitor analysis, market intelligence, regulatory monitoring
Review 8 Content review, code review, vendor evaluation
Approvals 5 Change request review, security review gate
Email 4 Alert notification, weekly knowledge summary
Data 3 Data enrichment, record summarization, deduplication
Legal 1 Legal clause summarizer
HR 1 Job description generator

Some templates appear in more than one category, so the per-category counts sum to more than 43.

40.4.3 Creating a flow from a template

  1. Browse the template gallery
  2. Click a template that fits your use case
  3. Review the template description and setup requirements
  4. Click “Use Template” to create a new flow
  5. Configure any required inputs (API keys, email recipients, etc.)
  6. Test and publish

40.4.4 Saving custom templates

  1. Build a flow in the builder
  2. Click “Save as Template” in the flow settings
  3. Give the template a name and description
  4. The template will be available in “My Templates” for your workspace

40.5 Testing and Debugging

40.5.1 Testing individual steps

  1. Select a step on the canvas
  2. Click “Test Step” in the test panel
  3. The step executes and displays the output
  4. Use the output to configure the next step

40.5.2 Loading run data into tests

If a step failed in a previous run, you can load the run data into the test panel:

  1. Open the run from the run list sidebar
  2. Select the step that failed
  3. Click “Load into test” to populate the test panel with the run’s input data
  4. Modify the input and re-test

40.5.3 Viewing run history

  1. Click the “Runs” icon in the left sidebar
  2. Filter by status (all, running, succeeded, failed, paused)
  3. Click any run to inspect step inputs and outputs
  4. Use the error search to find runs with specific error messages

40.5.4 Cancelling runs

  • Running runs cannot be cancelled (they must complete or time out)
  • Queued runs can be cancelled from the run list
  • Paused runs (waiting for approval) can be cancelled

40.6 Using AI to Generate Flows

40.6.1 AI flow generation

Instead of building a flow manually, you can describe what you want in natural language:

  1. Click Generate with AI in the builder.
  2. Choose Workspace default or a visible explicit model.
  3. Describe the workflow you want to create.
  4. The AI generates a flow with appropriate triggers and actions.
  5. Review the generated flow, test it, and publish.

Create with AI dialog with Sophea W4 selected and marked as the default model

Create with AI dialog using Sophea W4 as the Workspace default

40.6.2 Tips for AI flow generation

  • Be specific about the trigger (e.g., “Run daily at 9 AM” or “When a webhook is received”)
  • Mention which Sophea actions you want (e.g., “Search the knowledge base and send an email”)
  • Include the expected input and output format
  • The AI uses the Sophea piece actions, so describe the workflow in terms of knowledge search, AI model, email, etc.

40.6.3 Refining a generated flow

After the AI generates a flow, you can iterate on it with follow-up instructions instead of starting over:

  1. Click Refine with AI in the flow builder header.
  2. Describe the change you want, for example Add an email step after the knowledge search or Change the schedule to weekly.
  3. Confirm Workspace default or choose a visible explicit model, then click Refine.
  4. Review the updated flow and continue refining or publish.

You can refine multiple times. Each refinement builds on the current state of the flow, so you do not need to restart when you want to make adjustments.

Generate and Refine refresh the available models when opened and again when you submit. If your selected model was hidden or removed in between, Automations stops the request and refreshes the selector. Review the new selection and click again; it does not change the model silently.

40.7 Choosing models in workflow steps

Model-capable Nous actions offer Workspace default and the visible explicit models available to your Workspace.

  • Workspace default is recommended for most flows. The saved flow follows the live Workspace default on every run.
  • An explicit model remains pinned while that model is visible. If an administrator later hides it, the saved flow uses the current Workspace default and records the requested model, executed model, and fallback reason in the run details.
  • A deleted, malformed, or different-Workspace model ID stops the step safely. Open the step, refresh the model list, and make an explicit selection before retrying.

40.8 Approvals

40.8.1 Human-in-the-loop approvals

The request_human_approval action pauses the flow and waits for a human to approve or reject:

  1. Add the request_human_approval action after an AI step
  2. Configure the approval message and assignee
  3. The flow pauses when it reaches this step
  4. The assigned user receives an email with a link to approve or reject
  5. If approved, the flow continues. If rejected, the flow stops.

40.8.2 LLM approval gates

The llm_approval action uses an AI model to approve or reject based on criteria:

  1. Add the llm_approval action
  2. Set the criteria (e.g., “Approve if the content is professional and accurate”)
  3. Set the subject (the content to evaluate)
  4. Set the confidenceThreshold (0-1, default 0.8)
  5. The AI evaluates the subject against the criteria and returns approved/rejected

40.8.3 Approval workbench

The approval workbench shows all pending approval tasks: 1. Click “Approvals” in the sidebar 2. View pending, approved, and rejected tasks 3. Click any task to approve or reject

40.9 Email

40.9.1 Sending workspace emails

The send_workspace_email action sends an email to workspace members:

  1. Add the send_workspace_email action
  2. Set recipientMode to RUN_USER (send to the flow runner) or WORKSPACE_MEMBERS (selected workspace members)
  3. If WORKSPACE_MEMBERS, select the recipients from the workspace member list
  4. Set the subject and body
  5. Set bodyFormat to markdown or plain_text

40.9.2 Common email patterns

  • Daily brief: Schedule trigger + ask_workspace_model + send_workspace_email
  • Alert notification: Webhook trigger + ask_workspace_model + send_workspace_email
  • Weekly summary: Schedule trigger + ask_nous_knowledge + send_workspace_email