motosan-agent-workflow (TypeScript)

A general-purpose DAG-based agent workflow engine for orchestrating LLM agents.

Installation

npm install motosan-agent-workflow

Optional YAML support:

npm install motosan-agent-workflow js-yaml

Quick Start

import {
  Workflow, Node, Runtime, LlmClient, LlmResponse,
} from "motosan-agent-workflow";

const myLlm: LlmClient = {
  async call(systemPrompt: string, input: any, tools: string[]): Promise<LlmResponse> {
    return { content: { answer: "..." }, inputTokens: 100, outputTokens: 50 };
  },
};

const workflow = Workflow.builder("my-pipeline")
  .node(Node.agent("researcher", { systemPrompt: "Find key facts about the topic." }))
  .node(Node.agent("writer", { systemPrompt: "Write a report.", inputFrom: ["researcher"] }))
  .edge("researcher", "writer")
  .build();

const runtime = new Runtime(myLlm);
const result = await runtime.execute(workflow, { topic: "TypeScript in 2026" });
console.log(result.nodeOutput("writer")?.content);

YAML Workflow

import { loadWorkflow, loadWorkflowFromStr, Format } from "motosan-agent-workflow";

// From file (Node.js)
const workflow = loadWorkflow("my-workflow.yaml");

// From string
const workflow = loadWorkflowFromStr(yamlStr, Format.Yaml);

Node Types

| Type | Description | LLM | |------|-------------|-----| | Node.agent() | LLM-powered agent | Yes | | Node.human() | Human-in-the-loop gate | No | | Node.transform() | Pure function transform | No | | Node.condition() | Conditional branching | No | | Node.loopNode() | Iterative loop | Depends | | Node.subWorkflow() | Nested sub-workflow | Depends |

Features

• Parallel execution — Nodes in the same DAG layer run concurrently via Promise.all
• Output schema validation — JSON Schema with auto self-correction
• Retry policies — Per-node exponential backoff with Skip/Abort/Fallback modes
• Human-in-the-loop — Gates with timeout and default action
• Event streaming — WorkflowEvent via callback
• Token tracking — Per-node and total, with budget enforcement
• Cost estimation — Pre-execution cost estimates with configurable pricing
• YAML/JSON loader — loadWorkflow() and loadWorkflowFromStr()
• 8 built-in templates — code-review, research, brainstorm, report, playlist, content, architecture-review, sprint-planning

Publishing

git tag ts-v0.3.0
git push origin ts-v0.3.0
# → triggers publish-typescript.yml → npm