Installation

Install the SDK using your preferred package manager:

npm install @runflow-ai/sdk
# or
yarn add @runflow-ai/sdk
# or
pnpm add @runflow-ai/sdk

Requirements

Node.js: >= 22.0.0
TypeScript: >= 5.0.0 (recommended)

Project Entry Point

Every Runflow project needs a main.ts file at the root that exports an async function main(). This is the function the Runflow engine calls when your agent receives a message:

main.ts

import { Agent, openai } from '@runflow-ai/sdk';
import { identify } from '@runflow-ai/sdk/observability';

const agent = new Agent({
  name: 'My Agent',
  instructions: 'You are a helpful assistant.',
  model: openai('gpt-4o'),
});

export async function main(input: any) {
  identify(input.email || input.phone || 'anonymous');

  const result = await agent.process({
    message: input.message,
    sessionId: input.sessionId,
  });

  return { message: result.message };
}

Project Structure

Learn how to organize your project as it grows

Built-in Libraries

The SDK includes the following libraries out-of-the-box. No need to install them separately - they’re available in all your agents:

Library	Version	Description	Import
axios	^1.7.0	HTTP client for API requests	`import axios from 'axios'`
zod	^3.22.0	Schema validation and TypeScript inference	`import { z } from 'zod'`
date-fns	^3.0.0	Modern date utility library	`import { format, addDays } from 'date-fns'`
lodash	^4.17.21	JavaScript utility library	`import _ from 'lodash'`
cheerio	^1.0.0	Fast, flexible HTML/XML parsing	`import * as cheerio from 'cheerio'`
pino	^8.19.0	Fast JSON logger	`import pino from 'pino'`

Quick Examples

import { createTool } from '@runflow-ai/sdk';
import { z } from 'zod';
import axios from 'axios';
import { format, addDays } from 'date-fns';
import _ from 'lodash';

const myTool = createTool({
  id: 'example-tool',
  description: 'Shows all available libraries',
  inputSchema: z.object({
    url: z.string().url(),
    data: z.array(z.any()),
  }),
  execute: async (params) => {
    // ✅ HTTP requests with axios
    const response = await axios.get(params.url);

    // ✅ Date manipulation
    const tomorrow = addDays(new Date(), 1);
    const formatted = format(tomorrow, 'yyyy-MM-dd');

    // ✅ Array/Object utilities with lodash
    const unique = _.uniq(params.data);
    const grouped = _.groupBy(params.data, 'category');
    
    return { response: response.data, date: formatted, unique, grouped };
  },
});

You can also use the SDK’s HTTP helpers for convenience:

import { httpGet, httpPost } from '@runflow-ai/sdk/http';
const data = await httpGet('https://api.example.com/data');

Environment Variables

Set up your environment variables:

# API Configuration
RUNFLOW_API_URL=http://localhost:3001
RUNFLOW_API_KEY=your_api_key_here
RUNFLOW_TENANT_ID=your_tenant_id
RUNFLOW_AGENT_ID=your_agent_id

# Execution Context (optional - usually comes from engine)
RUNFLOW_EXECUTION_ID=exec_123
RUNFLOW_THREAD_ID=thread_456

# Development
RUNFLOW_ENV=development
RUNFLOW_LOCAL_TRACES=true
NODE_ENV=development

Configuration File

Create a .runflow/rf.json file:

{
  "agentId": "your_agent_id",
  "tenantId": "your_tenant_id",
  "apiKey": "your_api_key",
  "apiUrl": "http://localhost:3001"
}

The SDK automatically searches for .runflow/rf.json in the current directory and parent directories. To make these values available as environment variables for external tools (Promptfoo, test runners, custom scripts), add:

import '@runflow-ai/sdk/init';

See Configuration File for details. Configuration Priority:

Explicit config in code
.runflow/rf.json
Environment variables
Defaults

Manual API Client Configuration

import { createRunflowAPIClient, Agent, openai } from '@runflow-ai/sdk';

const apiClient = createRunflowAPIClient({
  apiUrl: 'https://api.runflow.ai',
  apiKey: 'your_api_key',
  tenantId: 'your_tenant_id',
  agentId: 'your_agent_id',
});

// Inject into agent
const agent = new Agent({
  name: 'My Agent',
  instructions: 'Help users',
  model: openai('gpt-4o'),
});

agent._setAPIClient(apiClient);

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Installation

Installation

Requirements

Project Entry Point

Project Structure

Built-in Libraries

Quick Examples

Environment Variables

Configuration File

Manual API Client Configuration

Next Steps

Quick Start

Core Concepts

​Installation

​Requirements

​Project Entry Point

Project Structure

​Built-in Libraries

​Quick Examples

​Environment Variables

​Configuration File

​Manual API Client Configuration

​Next Steps

Quick Start

Core Concepts

Installation

Requirements

Project Entry Point

Built-in Libraries

Quick Examples

Environment Variables

Configuration File

Manual API Client Configuration

Next Steps