Installation & Setup Guide

This guide will help you install Azcore, a professional agentic framework for building complex AI agent systems with advanced orchestration, reinforcement learning, and multi-agent reasoning.

Prerequisites

Before installing Azcore, ensure you have:

• Python 3.12+ (Python 3.12 or 3.13 recommended)
• pip (comes bundled with Python)
• OpenAI API Key (for LLM functionality)

Verify your Python installation:

python --version
pip --version

Quick Install

Install Azcore from PyPI with a single command:

pip install azcore

This will install the latest stable version of Azcore along with all required dependencies.

Getting Started with the CLI

Azcore comes with a powerful CLI that helps you scaffold projects, validate your environment, and explore examples.

1. Verify Installation

Check that Azcore is installed correctly:

azcore --version

2. Initialize a New Project

Create a new Azcore project using the interactive CLI:

azcore init

This will:

• Display an interactive project setup wizard
• Let you choose from multiple project templates
• Create a complete project structure with all necessary files
• Generate configuration files and examples

Available Templates:

• basic-agent - Single agent with ReAct reasoning (perfect for getting started)
• team-agent - Multi-agent collaboration system
• modular-team - Enterprise-ready team with organized tool modules and MCP support
• rl-agent - Agent with reinforcement learning for tool selection
• workflow - Custom workflow orchestration system

Quick Start (Non-Interactive):

# Create a basic agent project
azcore init --template basic-agent --name my-agent

# Create an RL-optimized agent with training scaffolding
azcore init --template rl-agent --name my-rl-agent --with-rl

# Create a modular team system
azcore init --template modular-team --name my-team

3. Set Up Your Environment

After creating your project, navigate to the project directory:

cd my-agent

Install dependencies:

pip install -r requirements.txt

Configure your API keys by copying the example environment file:

# Copy the example .env file
cp .env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=your-api-key-here

4. Verify Your Setup

Run the environment diagnostic tool to check your setup:

azcore doctor

This will check:

• Python version compatibility
• Required dependencies
• Configuration files
• API key setup
• Optional components (RL, MCP)

Auto-fix issues:

azcore doctor --fix

Check GPU availability for RL training:

azcore doctor --check-gpu --verbose

5. Run Your Agent

Once your setup is verified, run your agent:

azcore run main.py

Or simply:

python main.py

Explore Examples

The CLI includes a collection of examples to help you learn different Azcore patterns:

List All Examples

azcore examples list

Filter by difficulty:

azcore examples list --difficulty Beginner
azcore examples list --difficulty Intermediate
azcore examples list --difficulty Advanced

Filter by tag:

azcore examples list --tag rl
azcore examples list --tag team

View Example Details

azcore examples show basic-agent
azcore examples show rl-agent
azcore examples show hierarchical-team

Run an Example

# Run directly
azcore examples run basic-agent

# Save to file
azcore examples run basic-agent --output my_agent.py

# Save with config
azcore examples run basic-agent --output my_agent.py --with-config

Search Examples

azcore examples search rl
azcore examples search team
azcore examples search cache

Advanced Setup

Optional Dependencies

Graph Visualization Support

pip install --pre -U graphviz

This enables workflow graph visualization capabilities.

RL Training Dependencies

If you're working with RL-optimized agents, install additional dependencies:

pip install sentence-transformers torch numpy scikit-learn

Or use the --with-rl flag when initializing:

azcore init --template rl-agent --with-rl

Development Dependencies

If you plan to contribute to Azcore or run tests:

pip install azcore[dev]

Virtual Environment (Recommended)

Create an isolated environment for your Azcore projects:

# Create virtual environment
python -m venv azcore_env

# Activate (Linux/Mac)
source azcore_env/bin/activate

# Activate (Windows)
azcore_env\Scripts\activate

# Install Azcore
pip install azcore

Project Structure

After running azcore init, your project will have the following structure:

my-agent/
├── main.py                      # Main application entry point
├── config.yml                   # Core configuration (LLM settings)
├── .env.example                 # Environment variables template
├── .env                         # Your API keys (create from .env.example)
├── requirements.txt             # Python dependencies
├── .gitignore                   # Git ignore patterns
├── README.md                    # Project documentation
├── configs/                     # Additional configurations
│   ├── config.yml              # Main config
│   └── rl_training_config.yml  # RL training settings (if --with-rl)
├── data/                        # Data storage
├── logs/                        # Log files
├── models/                      # Model storage (for RL)
├── rl_data/                     # RL training data (if --with-rl)
├── scripts/                     # Training scripts (if --with-rl)
│   ├── train_synthetic.py      # Train RL models
│   └── generate_synthetic.py   # Generate synthetic training data
└── team_modules/                # Team modules (modular-team template)
    ├── communication_tools.py
    ├── data_tools.py
    ├── file_tools.py
    ├── research_tools.py
    ├── graph_builder.py
    └── prompts/

CLI Command Reference

Core Commands

Options

Initialize with options:

azcore init --template <template> --name <name> --path <path> --force --with-rl

Doctor with options:

azcore doctor --fix --verbose --check-gpu

Examples with filters:

azcore examples list --tag <tag> --difficulty <level>
azcore examples show <id>
azcore examples run <id> --output <file> --with-config
azcore examples search <query>

Troubleshooting

Common Issues

Import Error: ModuleNotFoundError: No module named 'azcore'

# Reinstall Azcore
pip uninstall azcore
pip install azcore

# Check Python environment
which python

OpenAI API Key Error

# Verify .env file exists and has correct format
cat .env

# Check environment variable
echo $OPENAI_API_KEY  # Linux/Mac
echo %OPENAI_API_KEY%  # Windows

Configuration Issues

# Run diagnostics
azcore doctor --verbose

# Auto-fix common issues
azcore doctor --fix

Dependency Conflicts

# Create fresh virtual environment
python -m venv fresh_env
source fresh_env/bin/activate  # Linux/Mac
fresh_env\Scripts\activate      # Windows

# Install Azcore
pip install azcore

Getting Help

If you encounter issues:

• Check the GitHub Issues for similar problems
• Review the Getting Started Guide for usage examples
• Ensure you're using a supported Python version (3.12+)

Next Steps

Now that Azcore is installed, you can:

1. Follow the Getting Started Guide for basic usage examples
2. Explore Agent Patterns for different reasoning approaches
3. Learn about Workflow Types for orchestration patterns
4. Check the API Reference for detailed documentation