Maestro TypeScript SDK

Build and execute Maestro workflows programmatically using TypeScript/JavaScript.

Installation

npm install @maestro-app/typescript-sdk

Quick Start

import {
  Workflow,
  StartNode,
  GeneratorNode,
  EndNode,
  MaestroClient,
} from "@maestro-app/typescript-sdk";

// Build a workflow
const workflow = new Workflow("My Workflow");

const start = new StartNode({ id: "start"});
const generator = new GeneratorNode({
  id: "generate",
  systemPrompt: "Generate something about the given input",
});
const end = new EndNode({ id: "end" });

workflow
  .addNode(start)
  .addNode(generator)
  .addNode(end)
  .connect(start, generator)
  .connect(generator, end);

const client = new MaestroClient({
  apiKey: "your-api-key",
  accountSlug: "my-account",
});

const { runId } = await client.executeWorkflow(workflow, {key: "value"});

// Stream the results
for await (const event of client.streamRun(runId)) {
  console.log(event);
}

Node Types

StartNode

Entry point for the workflow.

const start = new StartNode({
  id: "start",
});

EndNode

Exit point for the workflow.

const end = new EndNode({
  id: "end",
  outputMappingExpression: "{{generate.output}}",
});

GeneratorNode

LLM-based content generation with optional tools and RAG.

const generator = new GeneratorNode({
  id: "generate",
  systemPrompt: "Generate content based on: {{input}}",
  provider: "openai",
  modelName: "gpt-4",
  tools: ["web_search"],
  retrieveCollectionName: "my-docs",
});

ValidatorNode

Validates outputs with retry logic.

const validator = new ValidatorNode({
  id: "validate",
  systemPrompt: "Validate the output",
  validatesNodeId: "generate",
  maxRetries: 3,
});

ProcessorNode

Processes and transforms data.

const processor = new ProcessorNode({
  id: "process",
  systemPrompt: "Transform the input",
});

Client Methods

executeWorkflow(workflow, input?)

Execute a workflow without persisting it to the database.

const { runId } = await client.executeWorkflow(workflow, { key: "value" });

streamRun(runId)

Stream execution events in real-time (SSE).

for await (const event of client.streamRun(runId)) {
  console.log(event);
}

API Reference

Workflow

class Workflow {
  constructor(name: string, description?: string);

  addNode(node: WorkflowNode): this;
  removeNode(nodeId: string): this;
  getNode(nodeId: string): WorkflowNode | undefined;
  connect(source, target, options?): this;
  validate(): void;
  toJSON(): object;
}

MaestroClient

class MaestroClient {
  constructor(config: {
    apiKey: string;
    accountSlug: string;
    baseUrl?: string;
  });
  executeWorkflow(workflow, input?): Promise<TriggerRunResult>;
  streamRun(runId, options?): AsyncGenerator<WorkflowStreamEvent>;
}

License

MIT