Functor Logo
GitHub

Agent System

Agent system endpoints provide direct access to the MainOrchestrator status and operations. These endpoints allow you to monitor the health and status of the agentic system components that power the FAITH-AGENTIC-KG-RAG system.

System Architecture

The agent system is built around the MainOrchestrator that coordinates three primary pipelines:

  • Pipeline 1: Data Ingestion - UnifiedIngestionPipeline for document processing
  • Pipeline 2: Retrieval - MultiKGRetrievalPipeline for multi-KG search
  • Pipeline 3: Prediction - KnowledgeGroundingPipeline for answer generation

GET /api/v1/agents/health

Check the health of agent system components including the MainOrchestrator and all pipelines.

Request

cURL Example
curl -X GET "https://your-api.com/api/v1/agents/health"

Response

Success Response (200 OK)
{
  "status": "healthy",
  "service": "agent_system",
  "components": {
    "langgraph_workflow": "available",
    "main_orchestrator": "available",
    "pipelines": ["data_ingestion", "query_processing"]
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Fields

FieldTypeDescription
statusstringOverall agent system status: "healthy", "degraded", or "down"
servicestringService identifier: "agent_system"
componentsobjectStatus of individual agent components
components.langgraph_workflowstringLangGraph workflow availability status
components.main_orchestratorstringMainOrchestrator availability status
components.pipelinesarrayList of available pipelines

GET /api/v1/agents/status

Get detailed status of agent system components including MainOrchestrator initialization status and pipeline availability.

Request

cURL Example
curl -X GET "https://your-api.com/api/v1/agents/status"

Response

Success Response (200 OK)
{
  "main_orchestrator": {
    "initialized": true,
    "version": "1.0.0",
    "pipelines": {
      "ingestion": {
        "status": "ready",
        "initialized": true
      },
      "retrieval": {
        "status": "ready",
        "initialized": true
      },
      "prediction": {
        "status": "ready",
        "initialized": true
      }
    },
    "memory_managers": {
      "episodic": "available",
      "semantic": "available",
      "procedural": "available",
      "short_term": "available",
      "long_term": "available"
    }
  },
  "langgraph_workflow": {
    "available": true,
    "nodes": ["intent_router", "kg_rag_pipeline", "sql_pipeline", "validation", "response_formatter"]
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

POST /api/v1/agents/query

Direct agent query endpoint. This is a convenience endpoint that routes to the main query endpoint. For full functionality, use POST /api/v1/query.

Request

cURL Example
curl -X POST https://your-api.com/api/v1/agents/query \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the symptoms of diabetes?",
    "user_id": "user_123",
    "kg_hint": "KG_Universal"
  }'

Note

This endpoint is a placeholder implementation. For production use, prefer the main query endpoint at POST /api/v1/query which provides full functionality with automatic pipeline routing.

Agent Components

The agent system consists of several key components:

MainOrchestrator

The central coordination hub that manages all pipeline operations. Located atapp/agents/main_orchestrator.py.

  • Manages pipeline lifecycle
  • Handles error recovery and fallbacks
  • Integrates with memory system
  • Coordinates between ingestion, retrieval, and prediction pipelines

UnifiedIngestionPipeline

Processes documents (PDF, CSV, URL, text) and builds knowledge graphs. Located atapp/agents/unified_ingestion_pipeline.py.

  • Entity and relation extraction using LLM
  • Knowledge graph construction
  • Embedding generation for vector search

MultiKGRetrievalPipeline

Handles multi-KG federated search with domain detection. Located atapp/agents/retrieval_pipeline.py.

  • Domain detection and KG routing
  • Vector and structural retrieval
  • Result fusion and ranking

KnowledgeGroundingPipeline

Generates answers with context grounding and validation. Located atapp/agents/prediction_pipeline.py.

  • Answer generation with context grounding
  • Multi-method validation (NLI, LLM-based)
  • Citation extraction
  • Confidence scoring

Examples

Python - Check Agent Health

import requests


def check_agent_health():
    """Check agent system health."""
    response = requests.get(
        "https://your-api.com/api/v1/agents/health",
        headers={"X-API-Key": "your-api-key"}
    )
    
    if response.status_code == 200:
        data = response.json()
        print(f"Agent System Status: {data['status']}")
        print(f"MainOrchestrator: {data['components']['main_orchestrator']}")
        print(f"Available Pipelines: {', '.join(data['components']['pipelines'])}")
        return data['status'] == 'healthy'
    else:
        print(f"Health check failed: HTTP {response.status_code}")
        return False


# Usage
if check_agent_health():
    print("Agent system is ready")
else:
    print("Agent system is not available")

Python - Get Detailed Status

import requests


def get_agent_status():
    """Get detailed agent system status."""
    response = requests.get(
        "https://your-api.com/api/v1/agents/status",
        headers={"X-API-Key": "your-api-key"}
    )
    
    if response.status_code == 200:
        data = response.json()
        
        # Check MainOrchestrator
        orchestrator = data['main_orchestrator']
        print(f"MainOrchestrator Initialized: {orchestrator['initialized']}")
        
        # Check pipelines
        print("\nPipeline Status:")
        for name, pipeline in orchestrator['pipelines'].items():
            status_icon = "✓" if pipeline['status'] == 'ready' else "✗"
            print(f"  {status_icon} {name}: {pipeline['status']}")
        
        # Check memory managers
        print("\nMemory Managers:")
        for name, status in orchestrator['memory_managers'].items():
            status_icon = "✓" if status == 'available' else "✗"
            print(f"  {status_icon} {name}: {status}")
        
        return data
    else:
        print(f"Status check failed: HTTP {response.status_code}")
        return None


# Usage
status = get_agent_status()

JavaScript - Monitor Agent System

async function monitorAgentSystem() {
  try {
    const response = await fetch('https://your-api.com/api/v1/agents/status', {
      headers: { 'X-API-Key': 'your-api-key' }
    });
    
    const data = await response.json();
    
    // Update UI with status
    const statusElement = document.getElementById('agent-status');
    if (data.main_orchestrator.initialized) {
      statusElement.className = 'status-healthy';
      statusElement.textContent = '● Agent System Ready';
    } else {
      statusElement.className = 'status-degraded';
      statusElement.textContent = '● Agent System Initializing';
    }
    
    // Display pipeline status
    const pipelines = data.main_orchestrator.pipelines;
    for (const [name, pipeline] of Object.entries(pipelines)) {
      const element = document.getElementById(`pipeline-${name}`);
      if (element) {
        element.textContent = pipeline.status;
        element.className = pipeline.status === 'ready' ? 'ready' : 'not-ready';
      }
    }
    
  } catch (error) {
    console.error('Failed to monitor agent system:', error);
  }
}


// Monitor every 30 seconds
setInterval(monitorAgentSystem, 30000);
monitorAgentSystem(); // Initial check

Integration with MainOrchestrator

All query and ingestion endpoints interact with the MainOrchestrator. The agent system endpoints provide visibility into the orchestrator's state:

Query Processing Flow

POST /api/v1/query
    ↓
MainOrchestrator.process_query()
    ↓
┌─────────────────────────────────────┐
│ Intent Classification               │
│ (LLM-based intent detection)        │
└─────────────────────────────────────┘
    ↓
    ├─→ KG-RAG Path
    │   ├─→ MultiKGRetrievalPipeline
    │   └─→ KnowledgeGroundingPipeline
    │
    └─→ Text-to-SQL Path
        └─→ SqlQueryService

Data Ingestion Flow

POST /api/v1/ingest
    ↓
MainOrchestrator.ingest_data()
    ↓
UnifiedIngestionService
    ↓
UnifiedIngestionPipeline.process()
    ↓
┌─────────────────────────────────────┐
│ Document Processing                 │
│ Entity & Relation Extraction        │
│ Knowledge Graph Building            │
│ Storage & Embedding                 │
└─────────────────────────────────────┘

Best Practices

  • Health Checks: Monitor agent health before making queries
  • Status Monitoring: Check agent status during system initialization
  • Error Handling: Handle degraded status gracefully with fallbacks
  • Use Main Endpoints: Prefer main query/ingestion endpoints over agent-specific ones
  • Pipeline Awareness: Understand which pipeline handles your requests

Related Documentation