Installation

System Requirements

Python Version

Python 3.12 or higher required

Operating System

macOS, Linux, or Windows (WSL2 recommended)

Memory

Minimum 2GB RAM available

Storage

~500MB for dependencies

Python 3.12+ is strictly required. AgenticPal uses modern Python features like match statements and type unions that don’t work on older versions.

Installation Methods

Using uv (Recommended)

uv is a blazing-fast Python package installer and resolver written in Rust. It’s 10-100x faster than pip.

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository

git clone https://github.com/hasanfaesal/agentic-pal.git
cd agentic-pal

Install dependencies

uv sync

This installs all dependencies from pyproject.toml in a virtual environment.

uv sync automatically creates and activates a virtual environment in .venv/

Verify installation

# Check Python version
python --version
# Should output: Python 3.12.x or higher

# Verify core dependencies
python -c "import langchain_qwq; import langgraph; print('✓ Installation successful')"

Using pip

If you prefer traditional pip:

Create virtual environment

python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install from source

pip install -e .

The -e flag installs in editable mode, useful for development.

Development Installation

For contributors and developers:

# Install with dev dependencies (pytest, type checkers, etc.)
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"

Google Cloud Setup

AgenticPal requires OAuth 2.0 credentials to access Google Workspace APIs.

Create a Google Cloud Project

Create project

Go to Google Cloud Console
Click Select a project → New Project
Name it “AgenticPal” (or your preferred name)
Click Create

You can use an existing project if you prefer. Free tier is sufficient for personal use.

Enable Required APIs

Navigate to APIs & Services → Library and enable:

Google Calendar API
Gmail API
Google Tasks API

Search for “Google Calendar API” and click EnableOr use direct link: Enable Calendar API

Configure OAuth Consent Screen

Go to APIs & Services → OAuth consent screen
Choose External as user type (unless you have Google Workspace)
Fill in required fields:
- App name: AgenticPal
- User support email: Your email
- Developer contact: Your email
Click Save and Continue
Skip the Scopes section (click Save and Continue)
Under Test users, click + ADD USERS
Add your Gmail address
Click Save and Continue

Critical: You MUST add your email as a test user, or OAuth will fail with a 403 error.

Create OAuth Client ID

Go to APIs & Services → Credentials
Click + CREATE CREDENTIALS
Select OAuth client ID
Choose Application type: Desktop app
Name it “AgenticPal Local Client”
Click Create
Click OK on the confirmation dialog

Download Credentials

Find your new OAuth 2.0 Client ID in the list
Click the download icon (⬇️) on the right
Save the JSON file as credentials.json
Move it to your AgenticPal project root:

# Your project structure should look like:
agentic-pal/
├── credentials.json  ← OAuth credentials here
├── main.py
├── pyproject.toml
├── agent/
├── services/
└── ...

credentials.json is already in .gitignore to prevent accidental commits.

Understanding OAuth Scopes

AgenticPal requests these OAuth scopes defined in auth.py:10-14:

auth.py

DEFAULT_SCOPES = (
    "https://www.googleapis.com/auth/calendar",        # Full Calendar access
    "https://mail.google.com/",                        # Full Gmail access
    "https://www.googleapis.com/auth/tasks",           # Full Tasks access
)

Security Note: These are full access scopes suitable for personal use. For production applications, use least-privilege scopes:

Calendar: calendar.events (read/write events only)
Gmail: gmail.readonly or gmail.modify (not full access)
Tasks: tasks (same, but be aware of permissions)

Environment Configuration

Required Environment Variables

LLM API Key

AgenticPal uses Alibaba Cloud’s Qwen model by default:

.env

DASHSCOPE_API_KEY=sk-your-dashscope-key-here

Get your key from DashScope Console.

Using OpenAI instead?

To use OpenAI models, set:

.env

OPENAI_API_KEY=sk-your-openai-key

Then modify main.py:34:

main.py

graph, tools_registry = create_graph_runner(
    # ... other params
    model_name="gpt-4o",  # or "gpt-4-turbo"
)

Using Anthropic Claude?

.env

ANTHROPIC_API_KEY=sk-ant-your-key

Modify main.py to import and use ChatAnthropic:

main.py

from langchain_anthropic import ChatAnthropic

# In create_graph_runner call:
model_name="claude-3-5-sonnet-20241022"

Optional: Redis for Web API

If deploying the FastAPI backend, configure Redis:

.env

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# Optional: REDIS_PASSWORD=your-password

Redis is only needed for the web API (api.main:app). The CLI (main.py) doesn’t require it.

Optional: Web API Settings

Configure the FastAPI server:

.env

# Server
HOST=0.0.0.0
PORT=8000
ENVIRONMENT=production  # or "development"

# CORS (comma-separated origins)
CORS_ORIGINS=https://app.example.com,https://admin.example.com

# Rate limiting
RATE_LIMIT=60/minute  # Format: <count>/<minute|hour|day>

Load Environment Variables

# Option 1: Export in shell
export DASHSCOPE_API_KEY="your-key"
export REDIS_HOST="localhost"

# Option 2: Load from .env file
source .env  # If using direnv

# Option 3: Use python-dotenv
pip install python-dotenv
# Add to main.py: from dotenv import load_dotenv; load_dotenv()

First Authentication

Run AgenticPal to trigger the OAuth flow:

python main.py

What Happens

OAuth flow starts

AgenticPal reads credentials.json and starts the OAuth flow (code in auth.py:49):

auth.py

flow = InstalledAppFlow.from_client_secrets_file(str(credentials_file), scope_list)
creds = flow.run_local_server(port=0, prompt="consent")

Browser opens automatically

Your default browser opens to Google’s consent screen

Sign in with the account you added as a test user
Review the permissions
Click Continue or Allow

Token cached

AgenticPal saves the access token to token.json:

auth.py

token_file.write_text(creds.to_json())

Terminal output

AgenticPal - Your AI Personal Assistant
Type 'exit', 'quit', or 'q' to exit
Mode: Legacy
--------------------------------------------------

You: _

Token Persistence: token.json caches your credentials. Subsequent runs won’t require browser authentication unless the token expires (typically after 7 days).

Token Refresh

AgenticPal automatically refreshes expired tokens (see auth.py:37-41):

auth.py

if creds and creds.expired and creds.refresh_token:
    try:
        creds.refresh(Request())
    except Exception:
        creds = None  # Fall back to full flow if refresh fails

Verify Installation

Test that everything is working:

python main.py

Output

AgenticPal - Your AI Personal Assistant
Type 'exit', 'quit', or 'q' to exit
Mode: Legacy
--------------------------------------------------

You: list my calendar events

  Assistant: You have 3 upcoming events:
  1. Team Standup - Mar 9, 2026 at 9:00 AM
  2. Lunch with Sarah - Mar 9, 2026 at 12:00 PM
  3. Q1 Planning - Mar 10, 2026 at 2:00 PM

If you see a response, congratulations! AgenticPal is fully installed and authenticated.

Running the Web API

Install Redis

The FastAPI backend requires Redis for session management:

brew install redis
brew services start redis

Start the API Server

# With auto-reload on file changes
uvicorn api.main:app --reload --port 8000

# Output:
# INFO:     Uvicorn running on http://127.0.0.1:8000
# INFO:     🚀 Agentic-PAL API v0.1.0 started
# INFO:     📡 Redis connected: True

Test the API

# Health check
curl http://localhost:8000/health

# Response:
{
  "status": "healthy",
  "version": "0.1.0",
  "redis_connected": true,
  "timestamp": "2026-03-08T15:30:00.123456"
}

# Interactive API docs
open http://localhost:8000/docs

API Reference

See the complete API documentation with examples

Production Deployment

Using Docker

Create a Dockerfile:

Dockerfile

FROM python:3.12-slim

WORKDIR /app

# Install uv
RUN pip install uv

# Copy project files
COPY pyproject.toml .
COPY . .

# Install dependencies
RUN uv sync --no-dev

# Expose API port
EXPOSE 8000

# Run API server
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

# Build and run
docker build -t agentic-pal .
docker run -p 8000:8000 \
  -e DASHSCOPE_API_KEY=$DASHSCOPE_API_KEY \
  -e REDIS_HOST=redis \
  agentic-pal

Using Docker Compose

docker-compose.yml

version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - redis
    restart: unless-stopped
  
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  redis_data:

# Start services
docker-compose up -d

# View logs
docker-compose logs -f api

Troubleshooting

ModuleNotFoundError: No module named 'langchain_qwq'

Dependencies weren’t installed correctly. Try:

uv sync --force
# Or with pip:
pip install -e . --force-reinstall

Python version too old

Check your Python version:

python --version

If < 3.12, install a newer version:

# Using pyenv
pyenv install 3.12.2
pyenv local 3.12.2

# Verify
python --version

OAuth error: redirect_uri_mismatch

This happens when Google’s redirect URI doesn’t match. For desktop apps:

Verify you selected Desktop app (not Web application)
Delete and recreate the OAuth client ID
Download fresh credentials.json

Redis connection failed

Verify Redis is running:

redis-cli ping
# Should output: PONG

If not running:

# macOS
brew services start redis

# Linux
sudo systemctl start redis

# Docker
docker start redis

Rate limit errors from LLM provider

If you see rate limit errors:

Check your API quota/credits
Add retry logic (already included in LangChain)
Consider upgrading your API plan
Use a local model like Ollama for testing

Next Steps

Configuration

Customize prompts, timezones, and agent behavior

Development

Learn how to add custom tools and extend AgenticPal

Deployment

Deploy to cloud platforms (AWS, GCP, Azure)

API Reference

Complete REST API documentation

Get Started

Core Concepts

Setup Guide

Features

Usage Examples

System Requirements

Python Version

Operating System

Memory

Storage

Installation Methods

Using uv (Recommended)

Using pip

Development Installation

Google Cloud Setup

Create a Google Cloud Project

Understanding OAuth Scopes

Environment Configuration

Required Environment Variables

Load Environment Variables

First Authentication

What Happens

Token Refresh

Verify Installation

Running the Web API

Install Redis

Start the API Server

Test the API

API Reference

Production Deployment

Using Docker

Using Docker Compose

Troubleshooting

Next Steps

Configuration

Development

Deployment

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Setup Guide

Features

Usage Examples

​System Requirements

Python Version

Operating System

Memory

Storage

​Installation Methods

​Using uv (Recommended)

​Using pip

​Development Installation

​Google Cloud Setup

​Create a Google Cloud Project

​Understanding OAuth Scopes

​Environment Configuration

​Required Environment Variables

​Load Environment Variables

​First Authentication

​What Happens

​Token Refresh

​Verify Installation

​Running the Web API

​Install Redis

​Start the API Server

​Test the API

API Reference

​Production Deployment

​Using Docker

​Using Docker Compose

​Troubleshooting

​Next Steps

Configuration

Development

Deployment

API Reference

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Using uv (Recommended)

Using pip

Development Installation

Google Cloud Setup

Create a Google Cloud Project

Understanding OAuth Scopes

Environment Configuration

Required Environment Variables

Load Environment Variables

First Authentication

What Happens

Token Refresh

Verify Installation

Running the Web API

Install Redis

Start the API Server

Test the API

Production Deployment

Using Docker

Using Docker Compose

Troubleshooting

Next Steps