@dreamweav/sdk

⚠️ Alpha Software: This package is in active development. APIs may change between versions.

The Kubernetes of multi-agent AI systems — Orchestrate complex multi-agent AI workflows with built-in observability, automatic retries, budget enforcement, and cost tracking.

DreamWeav makes it easy to build production-ready AI agent systems. Define workflows as code, run them locally or distributed across multiple machines, and monitor everything with automatic tracing and metrics.

📚 Full Documentation & Examples | 🚀 CLI Tool

Installation

npm install @dreamweav/sdk
# or
pnpm add @dreamweav/sdk

Next.js Configuration (Required!)

⚠️ If you're using Next.js, you must configure webpack to externalize native modules.

The SDK uses better-sqlite3 (a native C++ module) which cannot be bundled by Next.js webpack. Without this configuration, you'll encounter TypeError: Cannot read properties of undefined errors.

Step 1: Update next.config.mjs

Add this to your Next.js configuration:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing config...

  // Externalize packages with native dependencies
  experimental: {
    serverComponentsExternalPackages: [
      '@dreamweav/sdk',
      'better-sqlite3',
      'pino',
      'pino-pretty'
    ]
  },

  // Webpack externals for API routes
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.externals = config.externals || []
      config.externals.push({
        '@dreamweav/sdk': 'commonjs @dreamweav/sdk',
        'better-sqlite3': 'commonjs better-sqlite3',
        'pino': 'commonjs pino',
        'pino-pretty': 'commonjs pino-pretty'
      })
    }
    return config
  }
}

export default nextConfig

Step 2: Use Node.js Runtime in API Routes

Add this at the top of your API route file:

// app/api/your-route/route.ts
export const runtime = 'nodejs' // Required for DreamWeav SDK

import { runWorkflow } from "@dreamweav/sdk"
import { myWorkflow } from "@/workflows/my-workflow"

export async function POST(request: Request) {
  const body = await request.json()
  const result = await runWorkflow(myWorkflow, body)
  return Response.json(result)
}

Why is this needed?

• Next.js webpack bundles all dependencies by default
• Native modules (like better-sqlite3) contain compiled C++ code that cannot be bundled
• The externalization config tells Next.js to load these packages directly from node_modules
• Edge Runtime doesn't support native modules, so you must use Node.js runtime

After making these changes:

# Delete build cache
rm -rf .next

# Restart dev server
npm run dev

Quick Start

import { defineWorkflow, step, runWorkflow } from "@dreamweav/sdk";

// Define steps
const fetchData = step("fetchData", async ({ input, tools }) => {
  const response = await tools.http().get(input.url);
  return response.body;
});

const analyze = step("analyze", async ({ input, tools }) => {
  return await tools.llm().summarize(input.text);
});

// Define workflow
const myWorkflow = defineWorkflow("myWorkflow", { budgetUSD: 0.5 }, async ({ io, tools }) => {
  const data = await fetchData.execute(io, tools, "run-1");
  return await analyze.execute({ text: data }, tools, "run-1");
});

// Run workflow
const result = await runWorkflow(myWorkflow, { url: "https://example.com" });
console.log(result);

Features

• DAG Workflows: Define complex agent workflows as directed acyclic graphs
• Retries & Timeouts: Built-in retry logic with exponential backoff
• Budget Tracking: Per-workflow cost limits with automatic enforcement
• Observability: Full tracing with span collection and metrics
• Tool Adapters: LLM, HTTP, and vector database tools
• Local Development: SQLite + JSONL persistence for easy debugging
• Remote Reporting (v0.2): Send spans to hosted Control Plane for centralized monitoring
• Dual Write Support (v0.2): Report to both local storage and remote Control Plane

Remote Reporting (v0.2)

Send workflow execution data to a hosted Control Plane for centralized monitoring and team collaboration.

Quick Start

import { runWorkflow, DreamWeavReporter } from "@dreamweav/sdk";

// Create reporter
const reporter = new DreamWeavReporter({
  apiUrl: "https://api.dreamweav.com",
  apiKey: "dw_your_api_key_here",
  workflowName: "myWorkflow",
});

// Run workflow with remote reporting
const result = await runWorkflow(myWorkflow, input, {
  writers: [reporter],
});

Environment Variables

The easiest way to enable remote reporting:

export DREAMWEAV_API_URL=https://api.dreamweav.com
export DREAMWEAV_API_KEY=dw_your_api_key_here

The SDK will automatically create a reporter if these variables are set.

Dual Write (Local + Remote)

Report to both local storage AND remote Control Plane:

import { SQLiteWriter, JSONLWriter, DreamWeavReporter } from "@dreamweav/sdk";

const result = await runWorkflow(myWorkflow, input, {
  writers: [
    new SQLiteWriter({ dbPath: ".dreamweav/local.db" }),
    new JSONLWriter({ directory: ".dreamweav/traces" }),
    new DreamWeavReporter({
      apiUrl: process.env.DREAMWEAV_API_URL,
      apiKey: process.env.DREAMWEAV_API_KEY,
      workflowName: "myWorkflow",
    }),
  ],
});

Configuration Options

interface ReporterConfig {
  // Required
  apiUrl: string;              // Control Plane URL
  apiKey: string;              // Project API key (starts with dw_)
  workflowName: string;        // Workflow identifier

  // Optional
  batchSize?: number;          // Spans per batch (default: 100)
  flushIntervalMs?: number;    // Auto-flush interval (default: 2000ms)
  onError?: (error: Error) => void;  // Error callback
}

Getting an API Key

1. Deploy the Control Plane (see deployment docs)
2. Create a project:

   curl -X POST https://api.dreamweav.com/v1/projects \
     -H "Content-Type: application/json" \
     -d '{"name":"my-project"}'

3. Save the returned api_key

Error Handling

Remote reporting is best-effort and non-blocking:

• Network failures don't crash your workflows
• Errors are logged but execution continues
• Local storage always works as fallback
• Failed spans are logged via onError callback

const reporter = new DreamWeavReporter({
  apiUrl: "https://api.dreamweav.com",
  apiKey: "dw_...",
  workflowName: "myWorkflow",
  onError: (error) => {
    console.error("Reporter error:", error.message);
    // Optionally send to error tracking service
  },
});

Batching & Performance

Spans are automatically batched for efficiency:

• Default batch size: 100 spans
• Auto-flush interval: 2 seconds
• Manual flush on workflow completion
• Max batch size supported by API: 1000 spans

Viewing Results

Once reporting is enabled, view your runs in the Dashboard:

# Start the dashboard (or access hosted version)
open https://dashboard.dreamweav.com/runs

# Filter by workflow, status, date range
# Click any run to see execution timeline
# View cost breakdowns and token usage

Troubleshooting

401 Unauthorized

• Verify your API key is correct
• Ensure API key starts with dw_
• Check that the project exists in Control Plane

Network Errors

• Verify Control Plane URL is accessible
• Check firewall/network settings
• Enable onError callback to see details

Spans Not Appearing

• Wait a few seconds for batching/flushing
• Check Control Plane logs for ingestion errors
• Verify workflow name matches between SDK and dashboard

API Reference

step(name, options, handler)

Define a workflow step with retry and timeout configuration.

Options:

• timeoutMs: Maximum execution time (default: 30000)
• retry: Retry configuration
  • maxAttempts: Number of retry attempts
  • backoff: 'none' | 'linear' | 'exponential'
  • baseDelayMs: Base delay for backoff
• concurrency: Max parallel executions

defineWorkflow(name, options, graphFn)

Define a workflow with steps and dependencies.

Options:

• budgetUSD: Maximum cost in USD
• timeoutMs: Overall workflow timeout
• metadata: Custom metadata

runWorkflow(workflow, input, options?)

Execute a workflow and return the result. Traces are automatically collected and persisted.

Development

# Build
pnpm build

# Test
pnpm test

# Watch mode
pnpm dev

License

MIT