Skip to main content

​
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:
LibraryVersionDescriptionImport
axios^1.7.0HTTP client for API requestsimport axios from 'axios'
zod^3.22.0Schema validation and TypeScript inferenceimport { z } from 'zod'
date-fns^3.0.0Modern date utility libraryimport { format, addDays } from 'date-fns'
lodash^4.17.21JavaScript utility libraryimport _ from 'lodash'
cheerio^1.0.0Fast, flexible HTML/XML parsingimport * as cheerio from 'cheerio'
pino^8.19.0Fast JSON loggerimport 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 ({ context }) => {
    // ✅ HTTP requests with axios
    const response = await axios.get(context.url);
    
    // ✅ Date manipulation
    const tomorrow = addDays(new Date(), 1);
    const formatted = format(tomorrow, 'yyyy-MM-dd');
    
    // ✅ Array/Object utilities with lodash
    const unique = _.uniq(context.data);
    const grouped = _.groupBy(context.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. Configuration Priority:
  1. Explicit config in code
  2. .runflow/rf.json
  3. Environment variables
  4. 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);

​
Next Steps

Quick Start

Create your first agent

Core Concepts

Learn about Agents