Skip to main content
Get AgenticPal running locally in just a few minutes. This guide will walk you through installation, Google Cloud setup, and your first conversation with the agent.

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.12 or higher installed
  • A Google Cloud Platform account (free tier works)
  • 5-10 minutes for initial setup

​
Quick Setup

1

Install AgenticPal

Clone the repository and install dependencies:
git clone https://github.com/hasanfaesal/agentic-pal.git
cd agentic-pal
uv sync
uv is 10-100x faster than pip. Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh
2

Set up Google Cloud credentials

AgenticPal needs OAuth credentials to access your Google Workspace:
  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable these APIs:
    • Google Calendar API
    • Gmail API
    • Google Tasks API
  4. Configure OAuth consent screen (add your email as test user)
  5. Create OAuth Client ID (Application type: Desktop app)
  6. Download the JSON file and save it as credentials.json in the project root
Keep your credentials.json file secure and never commit it to version control. It’s already in .gitignore.
For detailed instructions, see Google Cloud Setup.
3

Configure environment variables

Create a .env file in the project root:
.env
# LLM API Key (required)
DASHSCOPE_API_KEY=your_dashscope_api_key_here

# Optional: Use OpenAI or Anthropic instead
# OPENAI_API_KEY=your_openai_key
# ANTHROPIC_API_KEY=your_anthropic_key
AgenticPal uses Alibaba’s Qwen model by default. Get a free API key at DashScope.
4

Run AgenticPal

Start the interactive CLI:
python main.py
On first run, a browser window will open for OAuth authentication. Grant the requested permissions, and AgenticPal will save the token for future use.You’ll see:
AgenticPal - Your AI Personal Assistant
Type 'exit', 'quit', or 'q' to exit
Mode: Legacy
--------------------------------------------------

You: _

​
Try Your First Commands

Once AgenticPal is running, try these natural language commands:

​
Calendar Management

You: Add a meeting with John next Tuesday at 2pm

  Assistant: I've created a calendar event "Meeting with John" 
             on Tuesday, March 12, 2026 at 2:00 PM.

​
Email Operations

You: Show me my unread emails

  Assistant: You have 3 unread emails:
             1. From: [email protected] - "Q1 Budget Review"
             2. From: [email protected] - "Sprint Planning Notes"
             3. From: [email protected] - "Weekly Tech Digest"

​
Task Management

You: Create a task: Review pull requests, due tomorrow

  Assistant: Created task "Review pull requests" 
             Due: March 9, 2026 at 11:59 PM

​
Multi-turn Conversations

AgenticPal remembers context and asks clarifying questions: 
You: Delete the meeting I just created

  Assistant: I found "Meeting with John" scheduled for March 12 at 2 PM.
             Are you sure you want to delete this event? (yes/no)

You: yes

  Assistant: Event deleted successfully.

​
Using the Web API

AgenticPal also provides a REST API with streaming support:
1

Install Redis

The web API requires Redis for session management:
brew install redis
brew services start redis
2

Configure Redis

Add to your .env file:
.env
REDIS_HOST=localhost
REDIS_PORT=6379
SESSION_SECRET=your-secret-key-here
3

Start the API server

uvicorn api.main:app --reload
The API will be available at http://localhost:8000.Visit http://localhost:8000/docs for interactive API documentation.

​
CLI Commands

help

Show available tools and commands
You: help

exit / quit / q

Exit the interactive CLI
You: exit

​
Troubleshooting

If the OAuth flow doesn’t start automatically:
  1. Copy the URL from the terminal
  2. Paste it into your browser manually
  3. Complete the authentication
  4. The CLI will continue once you authorize
If you see “invalid_grant” or credential errors:
  1. Delete token.json in the project root
  2. Run python main.py again
  3. Re-authenticate in the browser
This usually happens if you:
  • Changed OAuth scopes
  • Removed your email as a test user
  • The token expired (shouldn’t happen often)
If you see syntax errors about match or type unions:
python --version  # Must be 3.12+
Update Python or use pyenv to manage versions:
pyenv install 3.12
pyenv local 3.12
If the agent isn’t responding:
  1. Check your API key in .env
  2. Verify you have API credits/quota
  3. Try a different model in main.py:
model_name="gpt-4"  # If using OpenAI
model_name="claude-3-opus-20240229"  # If using Anthropic

​
Next Steps

Core Concepts

Learn how AgenticPal’s architecture works

Features

Explore all capabilities in depth

API Reference

Integrate AgenticPal into your applications

Examples

See more usage examples

Build docs developers (and LLMs) love

Get started for freeTalk to us