Getting Started

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

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

OPENAI_API_KEY=your-api-key-here

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