> ## 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.

# Installation

> Install and configure Runflow SDK

## Installation

Install the SDK using your preferred package manager:

```bash theme={null}
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:

```typescript main.ts theme={null}
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 };
}
```

<Card title="Project Structure" icon="folder" href="/project-structure">
  Learn how to organize your project as it grows
</Card>

## 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

```typescript theme={null}
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 };
  },
});
```

<Tip>
  You can also use the SDK's HTTP helpers for convenience:

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

## Environment Variables

Set up your environment variables:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```typescript theme={null}
import '@runflow-ai/sdk/init';
```

See [Configuration File](/configuration/config-file) for details.

**Configuration Priority:**

1. Explicit config in code
2. `.runflow/rf.json`
3. Environment variables
4. Defaults

## Manual API Client Configuration

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Create your first agent
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts/agents">
    Learn about Agents
  </Card>
</CardGroup>