Skip to main content

​
Introduction

The AgenticPal API is a FastAPI-based backend that powers a LangGraph personal assistant agent. It provides endpoints for managing Google Calendar events, Gmail messages, and Google Tasks through natural language conversations. Current Version: v0.1.0

​
Architecture

The API is built with:
  • FastAPI - Modern, high-performance web framework
  • LangGraph - Stateful agent orchestration
  • Redis - Session management and conversation state persistence
  • Google OAuth2 - Secure authentication
  • Server-Sent Events (SSE) - Real-time streaming responses

​
Core Components

Chat Endpoints

Synchronous and streaming chat interfaces with the LangGraph agent

Authentication

Google OAuth2 flow with session-based credential storage

Session Management

Redis-backed sessions with HttpOnly cookies

State Persistence

LangGraph checkpoints stored in Redis for conversation continuity

​
Base URL

The API runs on configurable host and port: 
# Development (default)
http://localhost:8000

# Production
https://your-domain.com
Configure via environment variables: 
HOST=0.0.0.0
PORT=8000

​
API Documentation

Interactive API documentation is available at:
  • Swagger UI: /docs
  • ReDoc: /redoc

​
Rate Limiting

The API implements per-session rate limiting using the slowapi middleware.
​
rate_limit
string
default:"60/minute"
Rate limit for authenticated requests. Tracks by session ID if available, otherwise by IP address.
Configuration: 
# Environment variable
RATE_LIMIT=60/minute
Rate Limit Key Strategy:
  • If session cookie exists: session:{session_id}
  • Otherwise: client IP address
When rate limit is exceeded, the API returns: 
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 60 per minute"
}

​
CORS Configuration

CORS is configured to allow requests from specified origins: Default allowed origins:
  • http://localhost:3000 - Local development
  • https://app.example.com - Production frontend (placeholder)
Configuration: 
# Comma-separated list of origins
CORS_ORIGINS=http://localhost:3000,https://app.example.com
CORS Settings:
  • Credentials: Enabled (cookies supported)
  • Methods: GET, POST, OPTIONS
  • Headers: All (*)

​
Health Checks

The API provides health check endpoints to monitor service status.

​
GET /health

Returns the health status of the API and its dependencies. Response:
​
status
string
Service status: healthy or degraded
​
version
string
API version (e.g., 0.1.0)
​
redis_connected
boolean
Whether Redis connection is active
​
timestamp
string
Current server timestamp (UTC)
Example Response: 
{
  "status": "healthy",
  "version": "0.1.0",
  "redis_connected": true,
  "timestamp": "2026-03-08T12:34:56.789Z"
}

​
GET /

API root endpoint returning basic information. Example Response: 
{
  "name": "Agentic-PAL API",
  "version": "0.1.0",
  "docs": "/docs",
  "health": "/health"
}

​
Redis Configuration

The API uses Redis for two purposes with separate database indexes:

​
Database 0: Sessions

  • User sessions (7-day TTL)
  • OAuth credentials
  • OAuth state tokens (10-minute TTL)
  • Pending messages for streaming (5-minute TTL)

​
Database 1: LangGraph Checkpoints

  • Conversation state
  • Agent execution history
  • Thread persistence
Configuration: 
REDIS_URL=redis://localhost:6379
SESSION_TTL_SECONDS=604800  # 7 days
OAUTH_STATE_TTL_SECONDS=600  # 10 minutes

​
Environment Variables

Key configuration options:
​
HOST
string
default:"0.0.0.0"
API server host
​
PORT
integer
default:"8000"
API server port
​
ENVIRONMENT
string
default:"development"
Environment mode: development or production
​
REDIS_URL
string
default:"redis://localhost:6379"
Redis connection URL
​
CORS_ORIGINS
string
Comma-separated list of allowed CORS origins
​
RATE_LIMIT
string
default:"60/minute"
API rate limit per session/IP
​
SESSION_SECRET
string
required
Secret key for session signing (required in production)
​
SESSION_TTL_SECONDS
integer
default:"604800"
Session expiration time (default: 7 days)
​
GOOGLE_CREDENTIALS_PATH
string
default:"credentials.json"
Path to Google OAuth credentials file
​
GOOGLE_REDIRECT_URI
string
default:"http://localhost:8000/auth/google/callback"
OAuth callback URL
​
FRONTEND_URL
string
default:"http://localhost:3000"
Frontend application URL for post-auth redirects
​
COOKIE_DOMAIN
string
Cookie domain (leave unset for localhost)

​
Error Handling

The API uses consistent error response format: 
{
  "error": "error_code",
  "message": "Human-readable error message"
}
Common Error Codes:
CodeStatusDescription
no_session401No active session cookie
session_expired401Session has expired
no_credentials401Not authenticated with Google
rate_limit_exceeded429Too many requests
agent_error500LangGraph agent execution error
internal_error500Unexpected server error

​
Next Steps

Authentication

Learn how to authenticate with Google OAuth

Chat Endpoints

Send messages and stream agent responses

Build docs developers (and LLMs) love

Get started for freeTalk to us