Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
350 lines (268 loc) · 7.65 KB

API_DOCUMENTATION.md

File metadata and controls

350 lines (268 loc) · 7.65 KB
Raw

🚀 Multi-Agent Calendar System API

Overview

This FastAPI application provides a comprehensive REST API for a multi-agent calendar system with three specialized agents:

  • 📅 Calendar Agent - Schedule, reschedule, and analyze calendar events
  • 📧 Email Agent - Send, read, search, and compose emails
  • 🔍 Search Agent - Web search, knowledge search, and news search

🏃‍♂️ Quick Start

1. Start the Server

cd /Users/admin/Desktop/POC_testing/langgraph/calendar_agent
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

2. Test the API

# Run comprehensive tests
python test_api.py

# Or test individual endpoints
curl -X GET "http://localhost:8000/api/v1/health"

3. Access Documentation

📡 API Endpoints

🏥 Health & System

GET /api/v1/health

Check system health and service status.

Response:

{
  "status": "healthy",
  "timestamp": "2025-07-25T14:00:00.000Z",
  "agents": {
    "calendar_agent": "active",
    "email_agent": "active",
    "search_agent": "active"
  },
  "services": {
    "google_calendar": "connected",
    "gmail": "connected",
    "search_service": "connected"
  }
}

GET /api/v1/agents/capabilities

Get information about all agent capabilities.

Response:

{
  "status": "success",
  "agents": {
    "calendar_agent": {
      "capabilities": ["schedule", "reschedule", "analyze"],
      "description": "Manages calendar events and scheduling"
    },
    "email_agent": {
      "capabilities": ["send", "read", "search", "compose"],
      "description": "Handles email operations"
    },
    "search_agent": {
      "capabilities": ["web", "knowledge", "news"],
      "description": "Performs various types of searches"
    }
  }
}

💬 Main Chat Interface

POST /api/v1/chat

Main endpoint for natural language interaction with all agents.

Request:

{
  "message": "Schedule a team meeting tomorrow at 2 PM",
  "user_id": "user_123"
}

Response:

{
  "status": "success",
  "intent": "schedule",
  "agent": "calendar_agent",
  "message": "Meeting scheduled successfully for tomorrow at 2:00 PM",
  "timestamp": "2025-07-25T14:00:00.000Z",
  "user_id": "user_123"
}

Example Messages:

  • Calendar: "Schedule a meeting tomorrow at 2 PM", "What meetings do I have today?"
  • Email: "Send an email to John", "Show me my latest emails"
  • Search: "What is AI?", "Find Python tutorials", "Latest tech news"

📅 Calendar Agent

POST /api/v1/agents/calendar/schedule

Direct calendar scheduling.

Request:

{
  "message": "Schedule team standup tomorrow at 9 AM for 30 minutes"
}

POST /api/v1/agents/calendar/analyze

Direct calendar analysis.

Request:

{
  "message": "What meetings do I have today?"
}

📧 Email Agent

POST /api/v1/agents/email/compose

Direct email composition.

Request:

{
  "message": "Compose a thank you email to Sarah for the great presentation"
}

POST /api/v1/agents/email/read

Read latest emails.

Query Parameters:

  • max_results (optional): Number of emails to retrieve (default: 5)

🔍 Search Agent

POST /api/v1/agents/search/knowledge

Knowledge search for factual information.

Request:

{
  "message": "What is artificial intelligence?"
}

POST /api/v1/agents/search/web

Web search for general information.

Request:

{
  "message": "Find Python programming tutorials"
}

POST /api/v1/agents/search/news

News search for current events.

Request:

{
  "message": "Latest developments in renewable energy"
}

🧪 Testing

POST /api/v1/test/agents

Run comprehensive system tests.

Response:

{
  "status": "completed",
  "test_results": [...],
  "summary": {
    "total_tests": 3,
    "passed": 3,
    "failed": 0
  }
}

🛠️ Usage Examples

Calendar Operations

# Schedule a meeting
curl -X POST "http://localhost:8000/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Schedule a team meeting tomorrow at 2 PM"}'

# Check today's meetings
curl -X POST "http://localhost:8000/api/v1/agents/calendar/analyze" \
  -H "Content-Type: application/json" \
  -d '{"message": "What meetings do I have today?"}'

Email Operations

# Compose an email
curl -X POST "http://localhost:8000/api/v1/agents/email/compose" \
  -H "Content-Type: application/json" \
  -d '{"message": "Compose an email to thank John for the presentation"}'

# Read latest emails
curl -X POST "http://localhost:8000/api/v1/agents/email/read?max_results=10"

Search Operations

# Knowledge search
curl -X POST "http://localhost:8000/api/v1/agents/search/knowledge" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is machine learning?"}'

# Web search
curl -X POST "http://localhost:8000/api/v1/agents/search/web" \
  -H "Content-Type: application/json" \
  -d '{"message": "Find React.js tutorials"}'

# News search
curl -X POST "http://localhost:8000/api/v1/agents/search/news" \
  -H "Content-Type: application/json" \
  -d '{"message": "Latest AI news"}'

🔧 Configuration

Environment Variables

Ensure these are set in your .env file:

OPENAI_API_KEY=your_openai_key
GOOGLE_ACCESS_TOKEN=your_google_token
GMAIL_ACCESS_TOKEN=your_gmail_token
TIMEZONE=Asia/Kolkata

Agent Features

  • Time Awareness: All agents understand current time and date context
  • Conflict Resolution: Calendar agent handles scheduling conflicts intelligently
  • Email Templates: Email agent supports multiple template types
  • Multi-Search: Search agent supports web, knowledge, and news searches

📊 Response Formats

All endpoints return JSON responses with consistent structure:

{
  "status": "success|error",
  "message": "Human-readable message",
  "timestamp": "ISO timestamp",
  "agent": "agent_name",
  "intent": "detected_intent"
}

🐛 Error Handling

Common HTTP status codes:

  • 200: Success
  • 400: Bad Request (invalid input)
  • 500: Internal Server Error (system error)
  • 503: Service Unavailable (system unhealthy)

🚦 Testing Your Setup

  1. Health Check: curl http://localhost:8000/api/v1/health
  2. Agent Test: curl -X POST http://localhost:8000/api/v1/test/agents
  3. Full Test Suite: python test_api.py

🎯 Integration Examples

JavaScript/Frontend

// Schedule a meeting
const response = await fetch('http://localhost:8000/api/v1/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Schedule a team meeting tomorrow at 2 PM',
    user_id: 'user_123'
  })
});

const result = await response.json();
console.log(`Agent: ${result.agent}, Status: ${result.status}`);

Python Client

import requests

# Send a message to the multi-agent system
response = requests.post('http://localhost:8000/api/v1/chat', json={
    'message': 'What meetings do I have today?',
    'user_id': 'user_123'
})

data = response.json()
print(f"Agent: {data['agent']}, Message: {data['message']}")

🔐 Security Notes

  • API currently uses static tokens for Google services
  • No authentication implemented (add as needed)
  • CORS enabled for all origins (restrict in production)

📈 Performance

  • Async FastAPI for high concurrency
  • Cached multi-agent system initialization
  • Optimized tool execution with proper error handling

🎉 Your multi-agent system is ready for testing!

Start the server and try the examples above to see all three agents in action.