Installation Guide

February 21, 2026 · View on GitHub

This guide will walk you through the steps required to install AgentForge on your system.

Installation Steps

1. Ensure Python is Installed

Python Version: AgentForge requires Python 3.11.
Check Python Version:
```
python3 --version
```
If Python is not installed or the version is anything other than 3.11, download version 3.11 from the official Python website.

2. Set Up a Virtual Environment (Optional But Recommended)

Using a virtual environment helps avoid conflicts with system-wide packages.

Create a Virtual Environment:
```
python3.11 -m venv venv
```
Activate the Virtual Environment:
- On Unix/macOS:
```
source venv/bin/activate
```
- On Windows:
```
venv\Scripts\activate
```

3. Install AgentForge

With the virtual environment activated, install AgentForge using pip:

pip install agentforge

4. Set Up Environment Variables

Depending on the language model service you plan to use with AgentForge, you may need to set up environment variables with your API keys. If you're using local models like LM Studio or Ollama, you do not need to set up environment variables for API keys.

You can set environment variables in one of two ways:

Option 1: Export Environment Variables Directly

For example, for OpenAI:

export OPENAI_API_KEY='your-openai-api-key'

For Anthropic:

export ANTHROPIC_API_KEY='your-anthropic-api-key'

For Google Gemini:

export GOOGLE_API_KEY='your-google-api-key'

Option 2: Use a `.env` File

Create a file named .env in your project directory and add your API keys like this:

OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
GOOGLE_API_KEY=your-google-api-key

To load these variables in your Python scripts, install the python-dotenv package:

pip install python-dotenv

Then, add the following lines at the top of your main script (before you use the environment variables):

from dotenv import load_dotenv
load_dotenv()

This will automatically load the variables from your .env file into the environment for your script.

5. Initialize Your Project

Navigate to your project directory and initialize your AgentForge project:

python -m agentforge.init_agentforge

This command creates a new .agentforge folder in your project with sub-folders containing YAML files:

your_project/
  .agentforge/
    actions/
    cogs/
    custom_apis/
    personas/
    prompts/
    settings/
    tools/

6. Initialize Codex OAuth (Only for Codex Models)

If you plan to use OpenAI Codex models, run the OAuth login command after project initialization:

python -m agentforge.init_codex_oauth

This stores OAuth credentials used by the Codex provider. Codex OAuth is separate from OPENAI_API_KEY.

Using AgentForge

Now that your project is set up, you can proceed to the Using AgentForge Guide to learn how to run agents and build your solutions. This guide provides examples and instructions on how to create and interact with agents using AgentForge.

Next Steps

Review the Prerequisites Guide if you haven't set up API keys or other necessary configurations.
If you're having trouble with AgentForge, please head over to the Troubleshooting Guide for solutions to common issues.