Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt

Use this file to discover all available pages before exploring further.

The HTTP module provides pre-configured utilities for making HTTP requests in tools and agents. Built on top of axios, it comes with sensible defaults, automatic error handling, and full TypeScript support.

​
Features

  • 🌐 Pre-configured axios instance with 30s timeout
  • 🛡️ Automatic error handling with enhanced error messages
  • 🎯 Helper functions for common HTTP methods (GET, POST, PUT, PATCH, DELETE)
  • 📦 Zero configuration - works out of the box
  • 🔒 Type-safe - Full TypeScript support with exported types
  • ⚡ Available in all agents - No need to install additional dependencies

​
Quick Start

import { createTool } from '@runflow-ai/sdk';
import { http, httpGet, httpPost } from '@runflow-ai/sdk/http';
import { z } from 'zod';

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a city',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async (params) => {
    try {
      // Option 1: Using httpGet helper (simplest)
      const data = await httpGet('https://api.openweathermap.org/data/2.5/weather', {
        params: {
          q: params.city,
          appid: process.env.OPENWEATHER_API_KEY,
          units: 'metric',
        },
      });

      return {
        city: data.name,
        temperature: data.main.temp,
        condition: data.weather[0].description,
      };
    } catch (error: any) {
      return { error: `Failed to fetch weather: ${error.message}` };
    }
  },
});

​
Helper Functions

The SDK provides convenient helper functions that automatically extract data from responses: 
import { httpGet, httpPost, httpPut, httpPatch, httpDelete } from '@runflow-ai/sdk/http';

// GET request - returns only the data payload
const user = await httpGet('https://api.example.com/users/123');
console.log(user.name);

// POST request
const newUser = await httpPost('https://api.example.com/users', {
  name: 'John Doe',
  email: 'john@example.com',
});

// PUT request
const updated = await httpPut('https://api.example.com/users/123', {
  name: 'Jane Doe',
});

// PATCH request
const patched = await httpPatch('https://api.example.com/users/123', {
  email: 'newemail@example.com',
});

// DELETE request
await httpDelete('https://api.example.com/users/123');

​
Using the HTTP Instance

For more control, use the pre-configured http instance directly: 
import { http } from '@runflow-ai/sdk/http';

// GET with full response
const response = await http.get('https://api.example.com/data');
console.log(response.status);
console.log(response.headers);
console.log(response.data);

// POST with custom headers
const response = await http.post(
  'https://api.example.com/resource',
  { data: 'value' },
  {
    headers: {
      'Authorization': `Bearer ${process.env.API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    timeout: 5000,
  }
);

// Multiple requests in parallel
const [users, posts, comments] = await Promise.all([
  http.get('https://api.example.com/users'),
  http.get('https://api.example.com/posts'),
  http.get('https://api.example.com/comments'),
]);

​
Error Handling

All HTTP utilities provide enhanced error messages: 
import { httpGet } from '@runflow-ai/sdk/http';

try {
  const data = await httpGet('https://api.example.com/data');
  return { success: true, data };
} catch (error: any) {
  // Error message includes HTTP status and details
  console.error(error.message);
  // "HTTP GET failed: HTTP 404: Not Found"
  
  return { success: false, error: error.message };
}

​
Complete Example: Weather Tool

import { Agent, openai, createTool } from '@runflow-ai/sdk';
import { httpGet } from '@runflow-ai/sdk/http';
import { z } from 'zod';

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for any city',
  inputSchema: z.object({
    city: z.string().describe('City name (e.g., "São Paulo", "New York")'),
  }),
  execute: async (params) => {
    try {
      const apiKey = process.env.OPENWEATHER_API_KEY;

      const data = await httpGet('https://api.openweathermap.org/data/2.5/weather', {
        params: {
          q: params.city,
          appid: apiKey,
          units: 'metric',
          lang: 'pt_br',
        },
        timeout: 5000,
      });

      return {
        city: data.name,
        temperature: data.main.temp,
        feelsLike: data.main.feels_like,
        condition: data.weather[0].description,
        humidity: data.main.humidity,
        windSpeed: data.wind.speed,
      };
    } catch (error: any) {
      if (error.message.includes('404')) {
        return { error: `City "${params.city}" not found` };
      }
      throw new Error(`Weather API error: ${error.message}`);
    }
  },
});

const agent = new Agent({
  name: 'Weather Assistant',
  instructions: 'You help users check the weather. Use the weather tool when users ask about weather conditions.',
  model: openai('gpt-4o'),
  tools: {
    weather: weatherTool,
  },
});

// Use the agent
const result = await agent.process({
  message: 'What is the weather like in São Paulo?',
});

​
Next Steps

Connectors

Use built-in connectors

Tools

Learn more about tools