Getting Started

Welcome to AgentForge! This guide will help you get up and running in minutes.

Choose Your Path

Pick the installation method that best fits your needs:

🚀 CLI Scaffold (Recommended for new projects)

Best for: Starting a new AgentForge project from scratch

What you get: Pre-configured TypeScript, example agent, environment setup, development scripts

Time: ~2 minutes

👉 Jump to CLI Installation

🔧 Manual Install (For existing projects)

Best for: Adding AgentForge to an existing TypeScript project

What you get: Full control over configuration and dependencies

Time: ~5 minutes

👉 Jump to Manual Installation

📦 Add to Existing Project

Best for: Integrating AgentForge into your current codebase

What you need: Existing Node.js/TypeScript project with package.json

Time: ~3 minutes

👉 See Manual Installation and skip the project initialization steps

Prerequisites

Before you begin, make sure you have:

• Node.js 18.x or higher
• pnpm 8.x or higher (recommended) or npm/yarn
• TypeScript knowledge (basic understanding)
• OpenAI API key (or other LLM provider)

Installation

Option 1: Using the CLI (Recommended)

The fastest way to get started is using the AgentForge CLI:

# Create a new project
npx @agentforge/cli create my-agent

# Navigate to the project
cd my-agent

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

Option 2: Manual Installation

If you prefer to set up manually:

# Create a new directory
mkdir my-agent && cd my-agent

# Initialize package.json
pnpm init

# Install AgentForge packages
pnpm add @agentforge/core @agentforge/patterns @agentforge/tools
pnpm add -D typescript @types/node tsx

# Install LangChain dependencies
pnpm add @langchain/core @langchain/openai

# Initialize TypeScript
npx tsc --init

Project Structure

A typical AgentForge project looks like this:

my-agent/
├── src/
│   ├── agent.ts          # Agent definition
│   ├── tools.ts          # Custom tools
│   └── index.ts          # Entry point
├── .env                  # Environment variables
├── package.json
├── tsconfig.json
└── README.md

Your First Agent

Let's create a simple ReAct agent that can answer questions and perform calculations.

1. Create the Agent

Create src/agent.ts:

import { createReActAgent } from '@agentforge/patterns';
import { ChatOpenAI } from '@langchain/openai';
import { calculator } from '@agentforge/tools';

export const agent = createReActAgent({
  model: new ChatOpenAI({
    model: 'gpt-4',
    temperature: 0
  }),
  tools: [calculator],
  maxIterations: 5
});

2. Create the Entry Point

Create src/index.ts:

import { agent } from './agent.js';

async function main() {
  const result = await agent.invoke({
    messages: [{
      role: 'user',
      content: 'What is 25 * 4 + 10?'
    }]
  });

  console.log('Agent response:', result.messages[result.messages.length - 1].content);
}

main().catch(console.error);

3. Set Up Environment

Create .env with your API key:

OPENAI_API_KEY=your-api-key-here

Complete Environment Setup

For detailed environment configuration including LangSmith tracing, multiple LLM providers, and custom settings, see the Environment Setup Guide.

4. Run Your Agent

# Using tsx (recommended for development)
npx tsx src/index.ts

# Or compile and run
npx tsc
node dist/index.js

What's Next?

Now that you have a basic agent running, here's your learning path:

📚 Learn the Fundamentals

• Quick Start Guide - Build more complex agents step-by-step
• Core Concepts - Understand tools, state, middleware, and memory
• Agent Patterns - Compare all 4 agent patterns

🎯 Choose Your Pattern

• ReAct Pattern - Best for exploration and flexibility
• Plan-Execute Pattern - Best for structured workflows
• Reflection Pattern - Best for quality-critical outputs
• Multi-Agent Pattern - Best for specialized tasks

🛠️ Build Custom Solutions

• Custom Tools Tutorial - Create your own tools
• Advanced Patterns Tutorial - Combine patterns
• Examples - See real-world examples

Common Issues

Module Resolution Errors

If you see module resolution errors, make sure your tsconfig.json has:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

API Key Not Found

Make sure you've:

1. Created a .env file
2. Added OPENAI_API_KEY=your-key
3. Loaded environment variables (use dotenv if needed)

Type Errors

AgentForge requires TypeScript 5.0+. Update if needed:

pnpm add -D typescript@latest

Getting Help

• GitHub Discussions - Ask questions
• Discord - Chat with the community
• Examples - Browse code examples