Saltar al contenido principal

Workflow Studio

The Workflow Studio is the operator-facing surface for the additive orchestration control plane introduced by the seven-phase refactor in orchestration-refactor-rollout.md. It composes the five existing graph builders, the three (then five) adapters, and the new hash-locked WorkflowSpec registry into a single replayable workflow concept.

What ships​

LayerFile / Path
Spec contractalphaswarm/agents/orchestration/spec.py
Registry + persist_specalphaswarm/agents/orchestration/registry_specs.py
Runtimealphaswarm/agents/orchestration/runtime.py
Adapter ABC + metaclassalphaswarm/agents/orchestration/base.py
Adapter registryalphaswarm/agents/orchestration/registry.py
Adapters (5)alphaswarm/agents/orchestration/adapters/
ORMalphaswarm/persistence/models_workflows.py
Migrationalembic/versions/0046_workflow_versioning.py
RESTalphaswarm/api/routes/workflows.py
Celery tasksalphaswarm/tasks/orchestration_tasks.py
DataMCP toolsalphaswarm/data/mcp/tools/orchestration.py, alphaswarm/data/mcp/tools/automation.py
Cache entryworkflows category in alphaswarm/cache/keys.py
Frontend routesalphaswarm_client/src/routes/workflows/
Frontend componentsalphaswarm_client/src/components/workflows/

Spec shape​

A workflow selects exactly one OrchestrationAdapter by alias and hands it adapter-specific params. The adapter dispatches internally — composite flows (Crew + Graph + Debate) belong inside their own adapter, not at the spec layer.

name: research.dialectical_with_fusion_v1
description: "Bull/Bear debate + fusion + weight-centric execution"
adapter: LangGraphAdapter
adapter_kind: graph
params:
  builder: dialectical          # one of build_* in alphaswarm/agents/graph/
  builder_kwargs:
    max_rounds: 2
schedule:
  cron: "30 13 * * 1-5"
  timezone: UTC
  enabled: false                # operator flips after the studio + schedule flags
guardrails:
  cost_budget_usd: 3.0
  max_calls: 60
  max_duration_seconds: 900
annotations: [research, dialectical]
template_target: research

WorkflowSpec.snapshot_hash() is the SHA256 of the canonical JSON form (sorted keys, no whitespace). Re-snapshotting a spec with the same hash returns the existing workflow_spec_versions row; changing any field inserts a NEW row (parallel to agent_spec_versions, bot_versions, rl_experiment_versions, analysis_spec_versions).

Operator flow​

  1. Operator flips ALPHASWARM_ORCHESTRATION_STUDIO_ENABLED=true (see the rollout doc).
  2. Frontend navigates to /workflows. List + detail render through <EntityPicker kind="workflows" /> so the dropdown shares the same cache invalidation path as every other entity picker.
  3. Operator hits Run → POST /workflows/{name}/run → enqueues alphaswarm.tasks.orchestration_tasks.run_workflow. The route returns a task_id; the studio attaches via the existing useLiveStream hook for _progress.emit frames (rule 4).
  4. Operator hits Replay on a historical run → POST /workflows/runs/{run_id}/replay re-dispatches with the captured spec_version_id for deterministic reproduction.
  5. Operator hits the topbar KillSwitch's "Halt workflows" action → POST /workflows/halt mirrors the five canonical halt endpoints (/agents/halt, /paper/stop-all, /bots/halt-all, /rl/halt-all, /quant-agents/halt).

Halt fan-out​

The Phase 2 WorkflowRuntime checks should_halt(state) between every adapter transition. should_halt is the OR of:

  • has_kill_switch() — Redis-backed global flag (the existing topbar KillSwitch flips this).
  • state["halt_token"] — per-run boolean the Phase 6 /workflows/halt endpoint sets on every active WorkflowRun row inside ALPHASWARM_ORCHESTRATION_HALT_CHECK_TIMEOUT_SECONDS of the API call.

Long-running adapters (CrewProcessAdapter, LangGraphAdapter, DialecticalDebateAdapter) poll context.is_halted() between inner steps so the SLA holds even mid-debate.

Adapter catalog (Phases 2-5)​

aliaskindsourcedescription
LangGraphAdaptergraphalphaswarmThe default state-machine adapter. Uses LangGraph to define nodes (agent calls, data tools) and edges (conditional transitions). Perfect for multi-turn research loops.
CrewProcessAdaptercrewfinrobotSequential or Hierarchical crew process. Wraps CrewAI to dispatch tasks to a predefined team of agents. Ideal for linear data-mining pipelines.
DialecticalDebateAdapterdebatetradingagentsDialectical multi-agent debate. Pit a 'Bull' agent against a 'Bear' agent, then use a 'Judge' (Fusion) agent to synthesize the final target weight.
SignalFusionAdapterfusionvibe_tradingMulti-alpha signal fusion. Combines signals from multiple sub-workflows or strategies into a single confidence-weighted output.
WeightCentricExecutionAdapterexecutionfinrlFinRL-X execution adapter. Maps high-level target weights to concrete broker orders while honoring RiskLimits.

Halt fan-out and Safety​

The Phase 2 WorkflowRuntime ensures that any "Run" can be stopped immediately, even if it's currently deep in a multi-agent debate.

Global Kill Switch​

The has_kill_switch() check queries a Redis-backed global flag. When the operator hits the topbar Kill Switch, this flag is flipped to true, and every WorkflowRuntime transition will halt.

Per-Run Halt​

The POST /workflows/halt endpoint targets specific run_ids. It sets a halt_token in the run's state. Long-running adapters like CrewProcessAdapter and LangGraphAdapter are instrumented to poll context.is_halted() between inner steps.

Budget Guardrails​

Every WorkflowSpec can define budget limits:

  • cost_budget_usd: Halts if the cumulative LLM cost (tracked in agent_runs_v2) exceeds this limit.
  • max_duration_seconds: Halts if the wall-clock time exceeds the threshold.

Workflow Studio UI​

The Studio provides a visual timeline of the workflow execution:

  • Node Spans: OTEL-instrumented durations for each adapter step.
  • Breadcrumbs: A JSONL audit trail of state transitions and intermediate agent outputs.
  • Cost Accumulator: Real-time USD cost tracking for the current run.
  • Live Stream: Progress frames from _progress.emit rendered as a scrollable log.

Replay and Versioning​

AlphaSwarm rejects in-place mutations of workflow behavior. If you change a prompt, a hyperparameter, or the adapter configuration:

  1. persist_spec(new_spec) computes the new SHA-256 hash.
  2. A new workflow_spec_versions row is inserted.
  3. The previous version remains active for any historical run_ids.

To reproduce a specific historical outcome, the Replay feature loads the pinned version of the spec, ensuring that the exact same logic is executed against the same (or fresh) data.

See also​