Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
9.5 KB
Raw Blame

JiuwenSwarm TUI SwarmFlow Guide

This document is for JiuwenSwarm TUI users. It covers the complete workflow of using SwarmFlow (Swarm Workflows) in the terminal interface, including configuration, triggering runs, real-time monitoring, and interactive inspection.


Overview

SwarmFlow is the workflow orchestration and execution capability provided by JiuwenSwarm in Team mode. When multiple Agents form a team to collaborate on complex tasks, SwarmFlow decomposes the entire task into ordered phases, with each phase containing several Agents that execute subtasks in parallel or sequentially. SwarmFlow provides full lifecycle management — from launch and progress tracking to result inspection.

Core Concepts

Concept Description
Workflow A complete SwarmFlow run instance, containing multiple phases and agents
Phase An execution stage within a workflow, e.g. "research", "analysis", "writing"
Agent A team member executing a specific subtask within a phase
Run ID A unique identifier for each workflow run, generated by SwarmflowTool at launch
Status Workflows, phases, and agents each have independent statuses: running / completed / failed / stopped / planned / pending

Workflow Lifecycle

workflow_started → phase → agent_started → agent_completed/failed → ... → workflow_completed/failed
  1. Launch: The Leader Agent analyzes the user's request, starts the workflow via SwarmflowTool, and generates a run_id
  2. Phase progression: The workflow advances through phases in order; agents within each phase execute in parallel
  3. State aggregation: WorkflowMonitorHandler aggregates progress events in real time and pushes incremental updates
  4. Completion / Failure: The workflow enters a terminal state once all phases have finished executing

Prerequisites

1. Install and Start the JiuwenSwarm Backend

# Install
pip install jiuwenswarm

# Initialize (first time)
jiuwenswarm-init

# Start the backend service
jiuwenswarm-start

2. Install and Start the TUI

# Install the TUI
pip install jiuwenswarm-tui

# Start the TUI (in a separate terminal)
jiuwenswarm-tui

The TUI connects to the local Gateway's TUI endpoint via WebSocket (default: ws://127.0.0.1:19001/tui). Make sure the backend service is running.

3. Configure the Model API

On first use, you need to set up the model API in the configuration. You can do this through the Web frontend (http://localhost:5173) in the Configuration panel, or by using the /config command in the TUI.


Enabling SwarmFlow

SwarmFlow is enabled by default in the Team mode configuration. The configuration file is located at ~/.jiuwenswarm/config/config.yaml.

Configuration

In the modes.team section of config.yaml, the enable_swarmflow field controls whether SwarmFlow is enabled:

modes:
  team:
    jiuwen_team:
      team_name: jiuwen_team
      lifecycle: persistent
      teammate_mode: build_mode
      spawn_mode: inprocess
      enable_swarmflow: true    # Set to true to enable SwarmFlow, default is True

      leader:
        member_name: team-leader
        display_name: Team Leader
        persona: "Expert project manager, skilled at task decomposition and team coordination"

      agents:
        leader: $agent_leader

      workspace:
        enabled: true

      transport:
        type: inprocess

      storage:
        type: sqlite

Key Configuration Fields

Field Description Default
enable_swarmflow Whether to enable SwarmFlow workflows true
team_name Team name jiuwen_team
lifecycle Team lifecycle: persistent / temporary persistent
teammate_mode Member build mode: build_mode build_mode
spawn_mode Process mode: inprocess (single machine) / see Distributed Team for distributed inprocess

Note: After modifying the configuration, restart the JiuwenSwarm backend service (jiuwenswarm-start) for changes to take effect.


Using SwarmFlow

Step 1: Switch to Team Mode

In the TUI, enter the following command to switch to Team mode:

/mode team

After switching, the TUI displays the current mode as team, and the Leader Agent takes charge of coordinating team tasks.

Step 2: Submit a Task

In Team mode, simply type a task description. SwarmFlow starts automatically after the Leader analyzes the task:

In swarmflow mode, research the new energy vehicle industry and produce an analysis report

The Leader Agent will:

  1. Analyze the requirements and decompose the task into multiple phases (e.g., research → analysis → writing → review)
  2. Launch the workflow via SwarmflowTool, generating a run_id
  3. Assign team members to execute subtasks in each phase

Step 3: Monitor Workflow Progress

After a workflow starts, the TUI main view automatically displays a running workflow status banner:

◐ 1 workflow running
  NEV Industry Research · 2m 15s

The banner includes:

  • An animated spinner indicator (◐◓◑◒)
  • The number of running workflows
  • The workflow name and elapsed time

Step 4: Inspect Workflow Details

Use the /swarmflows command to open the SwarmFlow interactive viewer:

/swarmflows

You can also use the alias:

/swarmworkflows

SwarmFlow Interactive Viewer

Opening /swarmflows enters a full-screen interactive view with three levels of navigation: Workflow List → Phase Details → Agent Details.

Level 1: Workflow List

Displays an overview of all workflows in the current session:

Swarm workflows
2 running, 1 completed

  ● running  NEV Industry Research      3/8 agents
  ● running  Competitive Analysis       1/5 agents
  ✓ completed User Profiling            6 agents

up/down select - Enter view - r refresh - Esc close
Information Description
Status icon ● running / ○ pending / ◎ planned / ✓ completed / ✗ failed / ■ stopped
Workflow name Set by SwarmflowTool at launch
Agent progress completed/total format

Controls:

Key Action
↑ / ↓ Move focus between workflows
Enter Enter the selected workflow's phase details
r Refresh the workflow list
Esc Close the viewer, return to chat

Level 2: Phase Details

After selecting a workflow, you enter the phase detail view. The left side shows the phase list, and the right side shows the agents in the current phase:

NEV Industry Research
Research the NEV industry and produce an analysis report
● running · 3/8 agents
2m 15s

Logs
  [leader] Starting research phase...
  [researcher] Searching industry data...

Phases                          Agents · Research
  ✓ Research    2/3              ● running  Data Researcher   · glm-5
  ● Analysis    1/3              ● running  Market Analyst    · glm-5
  ○ Writing     0/2              ✓ completed Info Collector   · glm-5

press l to see full logs
up/down select phase · Enter show agents · Tab/Right agents · Esc back

Controls:

Key Action
↑ / ↓ Move focus between phases
Enter Switch focus to the agent list
Tab / → Toggle focus between Phases and Agents lists
← Return to the workflow list
l View full workflow logs (enters the file viewer)
r Refresh
Esc Return to the workflow list

Level 3: Agent Details

Select an agent in the agent list and press Enter to view details:

Data Researcher
NEV Industry Research · Research
● running · glm-5
duration 45s

Prompt
  Research NEV industry market data for the past three years, including sales,...

Outcome
  (Displayed after the agent completes execution)

press p to see full prompt - o outcome - e error
Esc/← back

Controls:

Key Action
p View full Prompt (enters the file viewer)
o View full Outcome (enters the file viewer)
e View full Error message (enters the file viewer; only available on failure)
← / Esc Return to phase details

File Viewer

When viewing logs, Prompt, Outcome, or Error, a full-screen file viewer opens:

Key Action
↑ / ↓ Scroll up / down
PgUp / PgDn Page up / down
Home / g Jump to the beginning
End / Shift+g Jump to the end
Esc / Ctrl+C Exit the viewer

Workflow Status Reference

Workflow Statuses

Status Description
running The workflow is currently executing
pending The workflow has been created, awaiting execution
planned The workflow has been planned, not yet started
completed All phases in the workflow have finished executing
failed An error occurred during workflow execution
stopped The workflow was interrupted or stopped by the user

Phase Statuses

Status Description
running The phase is currently executing
planned The phase has been planned, not yet started
completed All agents in the phase have finished executing
failed An error occurred during phase execution

Agent Statuses

Status Description
running The agent is currently executing a subtask
completed The agent has completed its subtask
failed The agent encountered an error