Workflow

Workflow organizes actions into stable processes. It uses playbooks to complete fixed cybersecurity operations tasks, targeting scenarios with clear structure, stable steps, and recurring execution, such as standardized triage and handling for fixed alert types, periodic inspections, daily report generation, and batch asset verification.

The biggest difference from traditional playbooks or drag-and-drop workflow products is that Flocks does not require users to drag nodes manually during orchestration. Users only describe the task flow in language. Rex automatically completes orchestration, tests each node, and ultimately delivers a workflow that can be used immediately.

1. Purpose

1.1 What Workflow Solves

Workflow defines the stable process a task should follow. When task steps are clear, inputs and outputs are explicit, and the capability needs reuse or scheduled execution, it should be promoted to a Workflow first.

In Flocks, a Workflow is not just a static flowchart. It is a runnable, testable, publishable security operations playbook. Rex converts natural-language requirements into nodes, data flow, and runtime configuration, then validates usability through single-node tests and full integration tests.

A typical Workflow includes:

Process description document: a .md file describing process goals, node responsibilities, inputs and outputs, and how to run it.
Structured definition: workflow.json describes nodes, edges, data flow, schema, and runtime configuration, and supports import/export.
Node definitions: each node can be a tool call, Agent delegation, model reasoning, condition branch, human confirmation, and so on.
Data flow: nodes pass data through explicit input and output schemas.
Test data and outputs: intermediate results from single-node tests, integration tests, and production runs usually land in Workspace outputs/.

1.2 Relationship with Other Modules

Module	Relationship
Session Management	Rex can create, run, debug, or modify Workflows in sessions.
Agent	Workflow nodes can delegate to expert Agents; Agents can also trigger Workflows during execution.
Skills	Skills provide methodology, while Workflow fixes stable processes. They can be used together.
Tools	Tool node execution capabilities come from APIs, MCP, Python, local commands, and so on.
Task Center	Task Center turns Workflows into recurring capabilities.
Workspace	Workflow definitions, test data, and runtime outputs are managed by user-level / project-level ownership.

2. Use Cases

2.1 Good Fits for Workflow

The task repeats: daily, weekly, hourly, or event-triggered.
Steps are highly consistent: every run collects data, judges, generates results, and sends notifications in the same order.
Stable inputs and outputs are needed: downstream tasks, reports, or channels depend on structured JSON / Markdown reports.
Testing and auditing are needed: each node should be verifiable, locatable, and regression-testable.
Batch processing is needed: batch alert triage, batch IOC queries, batch asset verification, and similar tasks.

2.2 Poor Fits for Workflow

If a task is one-off, exploratory, or its execution path must change dynamically based on extensive context, it is usually more efficient to hand it directly to Rex or an expert Agent in a session.

Simple rules:

If it should run the same steps next time, create a Workflow.
If only the judgment method should be reused next time, create a Skill.
If a professional role should handle a class of tasks long term, create an Agent.

3. WebUI Entry Points

3.1 Open the Workflow Page

Go to Agent Studio -> Workflow from the sidebar. Titled "Workflow", this page lets users manage and execute workflows.

The list page displays workflows by source and provides All / Built-in / Custom filters:

Custom workflows: workflows created, modified, or installed by users or in the current Workspace.
Built-in workflows: workflow templates and examples provided by the system or plugins.
Each workflow card shows name, source, status, node count, description, invocation count, success rate, and average duration.

Click a workflow card to open its detail page. Click Create Workflow to open the new workflow page.

3.2 Create, Modify, and Publish

Daily Workflow operations can be split into three categories:

Create Workflow: from entry point, AI guidance, built-in examples, and workflow.md review to generating workflow.json.
Modify Workflow: click Rex guidance from the flowchart, or enter the workbench directly and adjust workflow.md, nodes, and workflow.json with natural language.
Invoke Workflow: after validation, run tests directly or publish as API, Webhook, Syslog, Kafka, or scheduled triggers.

For both creation and modification, use workflow.md as the human-readable requirements contract, then let Rex generate or update workflow.json based on the confirmed workflow.md. This reduces the problem of "the UI looks changed, but the real machine definition was not synchronized."

3.3 Automatic Validation and Testing

After generation, Rex continues with validation:

Structure validation: check that nodes, edges, start nodes, schemas, and required fields are complete.
Single-node tests: run each node independently with test data to confirm input/output format and tool calls work.
Full integration test: run the complete end-to-end flow with full test data.
Automatic debugging on failure: if tests fail, Rex modifies node configuration, data mappings, or prompts based on error information and tests again.

3.4 Production Runs

After validation, you can run the Workflow directly on the Workflow page or trigger a test run in a session with natural language:

Help me run this batch of alerts with the NDR alert triage workflow.

After entering production operation, Workflows usually have five invocation or trigger methods:

Publish as API: receive JSON input and provide a stable process invocation entry point for external systems, suitable for security platforms, ticketing systems, or internal business systems to call proactively.
Webhook integration: receive events pushed by third-party systems, suitable for alert callbacks, scan result pushes, and system notifications.
Syslog integration: listen to Syslog data sent by security devices or log platforms, suitable for real-time processing triggered by log arrival.
Kafka integration: consume messages from topics and trigger workflows automatically, suitable for event streams, asynchronous processing, and high-frequency data ingestion.
Scheduled trigger: run proactively on a fixed schedule, suitable for daily reports, weekly reports, periodic inspections, scheduled alert pulls, and similar scenarios.

The publish page provides Rex-assisted publishing for API services, event triggers such as Webhook, Syslog, and Kafka, and scheduled triggers. Rex guides users through runtime mode, authentication, field mapping, samples, and start/stop actions.

When publishing as an API, the page generates a dedicated invocation address and API Key, plus call examples. When publishing as an event trigger, you can configure Webhook, Syslog, or Kafka input. Syslog scenarios usually require listener protocol, address, port, parsing format, and the field name written into Workflow inputs. For details, see Invoke Workflow. Regardless of the method, run once on the page with sample data before enabling continuous operation.

4. Workflow File Structure and Installation

4.1 Storage Locations

Workflows support both user-level and project-level storage:

Type	Storage Location	Description
Project-level Workflow	`.flocks/plugins/workflows/` under the current project or Workspace	Visible only in the current project / Workspace.
User-level Workflow	`~/.flocks/plugins/workflows/` under the user directory	Reusable across multiple Workspaces for the current user.

4.2 Directory Structure

Each Workflow is usually an independent folder:

text

workflows/
└── ndr-alert-triage/
    ├── workflow.json
    ├── workflow.md
    ├── testdata/
    └── README.md

Where:

workflow.json stores the structured workflow definition, including nodes, edges, schemas, and runtime configuration.
workflow.md or other .md files store human-readable process descriptions, node responsibilities, usage, and acceptance criteria.
testdata/ can store sample data for single-node tests and integration tests.
Other scripts or template files can be added as needed by nodes.

4.3 Install a New Workflow

Place a new Workflow folder under .flocks/plugins/workflows/ or ~/.flocks/plugins/workflows/ to install it. The system recognizes its workflow.json and loads it into the workflow list or runtime.

After installation, immediately run a test to confirm that models, tools, MCP, credentials, and output paths in the current environment are available.

5. Run, Verify, and Adjust

5.1 View Execution Outputs

After a Workflow finishes, you can view:

Run summaries in the session or Workflow page.
Each node's inputs, outputs, and execution status.
Structured results, Markdown reports, and outbound results.
Test data, intermediate data, and final outputs in Workspace outputs/.

5.2 Verify Whether a Workflow Meets Expectations

Focus on:

Whether input and output schemas are stable.
Whether each node can be executed repeatedly.
Whether external tools, APIs, MCP, and credentials are available.
Whether branch conditions and failure paths meet business expectations.
Whether the final report meets team format and audit requirements.

5.3 Adjust a Workflow

If Workflow results are not ideal, clearly tell Rex which workflow, node, or data flow to optimize.

For example:

text

Help me optimize the NDR alert triage workflow.
The current intelligence enrichment node returns too few fields. Add IOC background, historical associations, reputation score, and evidence sources,
and update the input schema of the following triage node accordingly.

Rex can adjust node configuration, data mappings, prompts, tool choices, or output format based on feedback. After adjustment, rerun single-node tests and integration tests.

6. Core Concepts

6.1 Node Types

Common node types include:

Tool node (Tool): call APIs, MCP, local Python, Bash, or other tools.
HTTP Request node (HTTP Request): call external HTTP interfaces directly, suitable for simple API requests or temporary integrations.
Python node (Python): execute Python logic, suitable for field transformation, data cleaning, offline computation, and similar work.
Model node (LLM): run one model inference, suitable for summarization, classification, structured extraction, and so on.
Agent node (Agent): delegate a subtask to an expert Agent.
Branch node (Branch): route the process to different paths based on conditions.
Logic node (Logic): execute lightweight logic judgment, field processing, or flow control.
Loop node (Loop): process arrays, batches of alerts, batches of IOCs, and similar data item by item.
Subworkflow node (Subworkflow): call another Workflow, suitable for reusing verified process fragments.
Human confirmation node: pause at critical steps and wait for user confirmation.
Merge node: merge results from multiple branches and continue execution.

You do not need to memorize all node types during creation. Describe the target process, and Rex selects nodes as needed and tests each one after generation.

6.2 Data Schema

Each node should define input and output schemas. Schema is the key to stable Workflow execution because it decides whether upstream output can be consumed correctly by downstream nodes.

Single-node tests mainly verify that a node itself can run. Integration tests mainly verify that data can flow correctly through the entire chain.

6.3 Import and Export

workflow.json supports import and export for version backup, cross-Workspace migration, and team sharing. Before export, ensure it has passed integration tests. After import, test again in the target environment.

6.4 Inputs and Publishing Forms

Workflows can receive structured JSON data as input and be published as APIs, providing stable process invocation entry points for external systems. This is suitable for packaging alert triage, asset verification, batch IOC queries, report generation, and similar capabilities as services that other systems can call.

Workflows can also receive syslog, Kafka, and other streaming inputs, and be published as streaming tasks. This is suitable for continuously processing security device logs, alert streams, asset change events, or other real-time data sources.

Choose publishing form as follows:

JSON input / API publishing: suitable for on-demand calls, batch submission, and processes actively triggered by external systems.
syslog / Kafka streaming tasks: suitable for continuous listening, real-time processing, and processes triggered when events arrive.
Task Center recurring runs: suitable for summarizing, inspecting, or generating reports on fixed time windows.

6.5 Relationship with Sessions

Conversations inside the Workflow page and conversations in Session Management share the same Agent runtime. The difference is that the Workflow page additionally provides the context of "currently designing or debugging a workflow," so Rex actively refers to the current node graph and workflow definition.

6.6 Workflow Capability Boundaries

Workflows are suitable for stable, repeatable, testable processes. They are not suitable for hard-coding every situational judgment. In practice:

Maintain single responsibility for each node. Avoid overloading a single node with excessive logic.
Keep schemas stable. Reduce implicit fields and free-text passing.
Encapsulate external API and tool calls centrally to make failures easier to locate.
Complex judgment can be delegated to Agent nodes, but avoid overly deep workflow nesting.
Rerun tests after every modification.

6.7 Runtime and Debugging Details

Before running, a Workflow performs structural checks to confirm that nodes, connections, start nodes, and required fields are complete. During runtime, it keeps node inputs and outputs, execution logs, and run history to help locate failures.

Some nodes may have their own runtime dependencies, timeout settings, or environment requirements. For nodes involving Python, external commands, APIs, or MCP, run single-node tests after generation before running the full integration test. This quickly separates tool unavailability, credential errors, schema mismatches, and unstable model node output.

7. Real Example: NDR Alert Triage Workflow

7.1 Background

The goal is to preserve the NDR alert triage process as a repeatable workflow. The input is one alert or a batch of alerts. The output is a structured triage conclusion and an externally sendable report.

7.2 Creation Process

Users can provide Rex with goals, alert samples, handling standards, and output templates. Rex generates an initial node graph, for example:

Parse raw alert text.
Enrich IOC intelligence.
Query asset and historical alert context.
Delegate to the alert triage Agent for judgment.
Generate JSON and Markdown reports.
Decide whether to send externally based on risk level.

7.3 Validation Process

Rex continues with:

Single-node tests, running each node with sample data.
Integration test, running the full flow with complete alert data.
Failure debugging, correcting schemas, node configuration, or tool parameters based on error information.

7.4 Outputs

Typical outputs include:

workflow.json: structured workflow configuration that supports import/export.
workflow.md: human-readable process description.
Test data and intermediate results.
Final JSON conclusion and Markdown report.
Runtime results sent to channels or Task Center.

8. FAQ

8.1 What If the Generated Workflow Cannot Run?

First determine whether the failure is in a single-node test or an integration test. Common causes include missing required tools or MCP, insufficient model capability, missing schema fields, unavailable credentials, and changed external API responses.

8.2 What If Workflow Execution Is Too Slow?

Merge nodes that can batch process, reduce unnecessary model nodes, cache repeated query results, optimize external API calls, or choose faster models and tools for critical nodes.

8.3 Can I Manually Edit workflow.json?

Yes. workflow.json is a structured definition file and supports direct editing and reimport. After editing, always rerun single-node tests and integration tests.

8.4 What Is the Difference Between Workflow and Skill?

Dimension	Workflow	Skill
What it is	Executable process / node graph	Methodology / standard / task template
Can it execute independently?	Yes, the platform runs it according to the graph	No, it must be loaded by an Agent
Suitable for	Stable steps, batch processing, scheduled runs	Judgment methods, checklists, experience reuse

8.5 What Is the Relationship Between Workflow and Task Center?

Workflow defines "how the process works." Task Center defines "when and how often it runs." A typical path is: define and test the Workflow, then configure recurring runs and result notifications in Task Center.

Create Workflow: Creation entry points, AI guidance, built-in examples, and workflow.md review.
Modify Workflow: Modify Workflows through flowchart Rex guidance or workbench natural language.
Invoke Workflow: Publish Workflows as API, Webhook, Syslog, Kafka, or scheduled triggers.
Session Management: Create, run, and adjust Workflows through Rex.
Agent: Workflow nodes can delegate to expert Agents.
Skills: Provide methodology for Agent nodes.
Tools: Source of execution tools for Workflow nodes.
Task Center: Turn Workflows into recurring runs.
Workspace: Storage location for Workflow definitions, test data, and outputs.
Scenario Practice - Alert Triage: Walkthrough of a typical NDR workflow.
Scenario Practice - Threat Intelligence and IOC Triage: Batch IOC triage workflow.

Operation demo videos will be added to this page after release materials are stable.