Installation Guide

This guide covers all the ways to install Agent Patterns and get your environment set up for development or production use.

Quick Install

Upgrade to Latest Version

pip install --upgrade agent-patterns

Installation from Source

Standard Installation

Clone the repository and install:

# Clone the repository
git clone https://github.com/osok/agent-patterns.git
cd agent-patterns

# Create and activate virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Development Installation

If you plan to contribute or modify the library, install with development dependencies:

# Clone and navigate to repository
git clone https://github.com/osok/agent-patterns.git
cd agent-patterns

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"

The development installation includes:

  • pytest - Testing framework

  • pytest-cov - Code coverage reporting

  • pytest-mock - Mocking utilities

  • black - Code formatter

  • ruff - Fast Python linter

  • mypy - Static type checker

Requirements

System Requirements

  • Python: 3.10 or higher (3.10, 3.11, 3.12 supported)

  • Operating System: Linux, macOS, Windows

  • Memory: Minimum 2GB RAM (4GB+ recommended)

Core Dependencies

Agent Patterns automatically installs these required dependencies:

langgraph>=0.2.0          # State graph management
langchain>=0.3.0          # LLM abstractions
langchain-core>=0.3.0     # Core LangChain functionality
langchain-openai>=0.2.0   # OpenAI integration
langchain-anthropic>=0.2.0 # Anthropic integration
python-dotenv>=1.0.0      # Environment variable management

Environment Setup

1. Create Configuration File

Copy the example environment file:

cp .env.example .env

2. Add API Keys

Edit .env and add your API keys:

# Required: At least one API key
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# Model configuration
THINKING_MODEL_PROVIDER=openai
THINKING_MODEL_NAME=gpt-4-turbo
THINKING_TEMPERATURE=0.7

3. Verify Installation

Test your installation:

from agent_patterns.patterns import ReActAgent

# Should import without errors
print("Agent Patterns installed successfully!")

Installation Options

Minimal Installation (Core Only)

If you only need specific providers:

# OpenAI only
pip install agent-patterns langchain-openai

# Anthropic only
pip install agent-patterns langchain-anthropic

Specific Version

Install a specific version:

pip install agent-patterns==0.2.0

From GitHub Branch

Install from a specific branch (for testing unreleased features):

pip install git+https://github.com/osok/agent-patterns.git@main

Virtual Environment Setup

Using conda

# Create conda environment
conda create -n agent-patterns python=3.10

# Activate environment
conda activate agent-patterns

# Install Agent Patterns
pip install agent-patterns

# Deactivate when done
conda deactivate

Using poetry

# Initialize poetry project
poetry init

# Add Agent Patterns
poetry add agent-patterns

# Install dependencies
poetry install

# Run commands in poetry environment
poetry run python your_script.py

Verification and Testing

Quick Verification

Create a test script test_install.py:

#!/usr/bin/env python3
"""Quick installation verification script."""

import sys

def verify_installation():
    """Verify Agent Patterns installation."""
    try:
        # Import core modules
        from agent_patterns.core import BaseAgent
        from agent_patterns.patterns import (
            ReActAgent,
            ReflectionAgent,
            PlanAndSolveAgent,
            ReflexionAgent,
            LLMCompilerAgent,
            REWOOAgent,
            LATSAgent,
            SelfDiscoveryAgent,
            STORMAgent,
        )

        print("✓ All pattern imports successful")

        # Check version
        import agent_patterns
        print(f"✓ Agent Patterns version: {agent_patterns.__version__}")

        # Check dependencies
        import langgraph
        import langchain
        print("✓ Core dependencies available")

        return True

    except ImportError as e:
        print(f"✗ Import failed: {e}")
        return False

if __name__ == "__main__":
    success = verify_installation()
    sys.exit(0 if success else 1)

Run the verification:

python test_install.py

Run Unit Tests

If you installed from source:

# Run all tests
pytest

# Run with coverage report
pytest --cov=agent_patterns --cov-report=html

# Run specific test file
pytest tests/test_base_agent.py

# Run with verbose output
pytest -v

Troubleshooting Installation

Common Issues

Issue: pip: command not found

Solution: Install pip or use python’s pip module:

python -m ensurepip --default-pip
# or
python -m pip install agent-patterns

Issue: Permission denied

Solution: Install to user directory or use virtual environment:

pip install --user agent-patterns
# or create virtual environment (recommended)
python -m venv venv && source venv/bin/activate

Issue: SSL certificate verification failed

Solution: Update certificates or use trusted host:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org agent-patterns

Issue: Incompatible Python version

Solution: Check Python version and upgrade if needed:

python --version  # Should be 3.10+

# Install specific Python version (macOS with brew)
brew install python@3.10

# Install specific Python version (Ubuntu)
sudo apt install python3.10

Issue: Dependency conflicts

Solution: Use virtual environment and upgrade pip:

python -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install agent-patterns

Issue: LangChain/LangGraph version conflicts

Solution: Install specific compatible versions:

pip install langgraph==0.2.0 langchain==0.3.0 agent-patterns

Getting Help

If you encounter installation issues:

  1. Check requirements: Ensure Python 3.10+

  2. Update pip: pip install --upgrade pip

  3. Use virtual environment: Isolate dependencies

  4. Check GitHub Issues: agent-patterns/issues

  5. Ask for help: Create a new issue with:

    • Python version (python --version)

    • OS and version

    • Full error message

    • Installation command used

IDE Setup

VS Code

Recommended extensions:

  • Python (Microsoft)

  • Pylance

  • Python Docstring Generator

Settings (.vscode/settings.json):

{
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.formatting.provider": "black",
    "python.analysis.typeCheckingMode": "basic"
}

PyCharm

  1. Open Settings > Project > Python Interpreter

  2. Add new virtual environment or select existing

  3. Install agent-patterns in selected interpreter

  4. Enable type checking: Settings > Editor > Inspections > Python

Next Steps

After successful installation:

  1. Read the Quick Start Guide for a 5-minute tutorial

  2. Review Core Concepts to understand patterns

  3. Explore Pattern API Reference for detailed documentation

  4. Check out Examples for real-world usage

Upgrading from v0.1.x

If you’re upgrading from version 0.1.x, be aware of breaking changes:

Major Changes in v0.2.0:

  • Complete rewrite to synchronous architecture (no async/await)

  • New prompt customization system (file-based, instructions, overrides)

  • Updated API for all patterns

  • New patterns: Reflexion, LLM Compiler, REWOO, LATS, Self-Discovery, STORM

Migration Steps:

  1. Review the changelog for all changes

  2. Remove all async/await keywords from your code

  3. Update agent initialization to use new configuration format

  4. Update prompt customization approach if using custom prompts

  5. Test thoroughly with new synchronous API

Example migration:

# Old (v0.1.x) - Async
async def main():
    agent = ReActAgent(...)
    result = await agent.run(query)

# New (v0.2.0) - Synchronous
def main():
    agent = ReActAgent(...)
    result = agent.run(query)