RelayPlane Logo

Quickstart Guide

Get started with RelayPlane in 5 minutes. Build your first multi-step AI workflow.

Installation

Install the RelayPlane SDK and dotenv for local development:

1npm install @relayplane/sdk dotenv

Provider Dependencies

Install the provider SDK for each AI provider you plan to use:

1# For OpenAI
2npm install openai
3
4# For Anthropic (Claude)
5npm install @anthropic-ai/sdk
6
7# For Google (Gemini)
8npm install @google/generative-ai
9
10# For structured output (recommended)
11npm install zod
You only need to install the SDKs for providers you actually use. If you're only using OpenAI, just install openai. The dotenv package is for loading .env files during local development — in production, set environment variables directly in your hosting platform.

Hello World

The simplest possible workflow - a single step that generates text:

1import 'dotenv/config'
2import { relay } from '@relayplane/sdk'
3
4relay.configure({
5  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } }
6})
7
8const result = await relay
9  .workflow('hello')
10  .step('greet')
11  .with('openai:gpt-4o')
12  .prompt('Say hello!')
13  .run()
14
15console.log(result.finalOutput) // "Hello! How can I help you today?"

Multi-Step Workflow

Now let's create a workflow with multiple steps that depend on each other:

1import 'dotenv/config'
2import { relay } from '@relayplane/sdk'
3
4// Configure your providers (do this once at app startup)
5relay.configure({
6  providers: {
7    openai: { apiKey: process.env.OPENAI_API_KEY! }
8  }
9})
10
11// Create a two-step workflow
12const greetingWorkflow = relay
13  .workflow('greeting-workflow')
14  .step('greet')
15  .with('openai:gpt-4o')
16  .prompt('Say hello to the user in a friendly way. Their name is: {{input.name}}')
17  .step('translate')
18  .with('openai:gpt-4o')
19  .depends('greet')
20  .prompt('Translate the following greeting to French: {{greet.output}}')
21
22// Run the workflow
23const result = await greetingWorkflow.run({ name: 'Alice' })
24
25// Check the results
26if (result.success) {
27  console.log('Greeting:', result.steps.greet)
28  console.log('Translation:', result.steps.translate)
29}
This is the canonical RelayPlane workflow pattern. Every multi-step AI workflow follows this structure: define steps, specify explicit provider:model, declare dependencies, and run.

How It Works

RelayPlane is a local-first workflow orchestration engine. Unlike traditional AI routers or gateways, RelayPlane lets you build multi-step AI workflows that run entirely on your machine with explicit control over which provider and model handles each step.

The .workflow() method creates a new workflow definition. Each .step() defines a task in your workflow. The .with() method specifies the exact provider:model to use. The .depends() method creates a dependency graph (DAG) that determines execution order.

Understanding the Code

1. Import the SDK

The relay object is your main entry point. It provides the workflow() factory method.

2. Define Steps

Each step requires:

  • •name - Unique identifier for the step
  • •provider:model - Which AI provider to use (openai, anthropic, google, xai, local)
  • •systemPrompt - Instructions for the AI model
  • •depends() - Optional step names that must complete first

3. Template Variables

Use {{stepName.output}} to reference previous step outputs. Use {{input.field}} to reference workflow inputs.

4. Run the Workflow

Pass your input data to run(). API keys are resolved from your relay.configure() call. The engine will:

  • 1.Validate the workflow DAG (detect cycles, check dependencies)
  • 2.Sort steps topologically
  • 3.Execute steps in dependency order
  • 4.Handle retries on failures (if configured)
  • 5.Return complete execution results

Expected Output

1{
2  "success": true,
3  "steps": {
4    "greet": "Hello Alice! It's wonderful to meet you today!",
5    "translate": "Bonjour Alice ! C'est merveilleux de vous rencontrer aujourd'hui !"
6  },
7  "finalOutput": "Bonjour Alice ! C'est merveilleux de vous rencontrer aujourd'hui !",
8  "metadata": {
9    "workflowName": "greeting-workflow",
10    "startTime": "2024-01-15T10:30:00.000Z",
11    "endTime": "2024-01-15T10:30:02.500Z",
12    "duration": 2500
13  }
14}

Error Handling

Always check result.success and handle errors gracefully:

1const result = await greetingWorkflow.run({ name: 'Alice' })
2
3if (result.success) {
4  console.log('Result:', result.steps.translate)
5} else {
6  console.error('Workflow failed:', result.error?.message)
7  console.error('Failed at step:', result.error?.stepName)
8  // result.error.details contains provider-specific error info
9}

Troubleshooting

Provider not configured

If you see "Provider openai is not configured", ensure you've called relay.configure() before running workflows:

1relay.configure({
2  providers: {
3    openai: { apiKey: process.env.OPENAI_API_KEY! },
4    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! }
5  }
6})

Missing peer dependency

If you see Provider "openai" requires peer dependency "openai", install the missing SDK:

1# For OpenAI/xAI
2npm install openai
3
4# For Anthropic
5npm install @anthropic-ai/sdk
6
7# For Google
8npm install @google/generative-ai

Invalid model format

Always use provider:model format:

1// ✓ Correct
2.with('openai:gpt-4o')
3.with('anthropic:claude-sonnet-4-20250514')
4.with('google:gemini-2.0-flash')
5
6// ✗ Wrong - missing provider prefix
7.with('gpt-4o')

Next Steps