docs/api_reference.md

Secure AI Agents Suite - API Reference Documentation

Overview

The Secure AI Agents Suite provides a comprehensive API for autonomous AI agent interactions. This documentation covers all endpoints, parameters, response formats, and usage examples.

Table of Contents

1. Base URL and Authentication
2. Core Endpoints
3. Agent Management
4. Performance Monitoring
5. WebSocket APIs
6. Error Handling
7. Rate Limiting
8. SDK Reference

Base URL and Authentication

Base URL

Production: https://your-space-url.hf.space
Local: http://localhost:7860

Authentication

# Headers
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "User-Agent": "Secure-AI-Agents-Suite/2.0.0"
}

API Versioning

# Current version: v1
headers["API-Version"] = "v1"

Core Endpoints

1. Process Request

POST /api/v1/process

Description: Process a user request through the autonomous agent system.

Request Body:

{
    "user_input": "string",
    "context": {
        "budget": "number",
        "timeline": "string",
        "team_size": "number",
        "industry": "string",
        "additional_params": "object"
    },
    "agent_type": "string",
    "max_execution_time": "number",
    "options": {
        "enable_monitoring": "boolean",
        "save_results": "boolean",
        "async_mode": "boolean"
    }
}

Parameters:

Parameter	Type	Required	Description	Default
user_input	string	Yes	The user's request text (max 10,000 chars)	-
context	object	No	Additional context as key-value pairs	{}
agent_type	string	No	Agent type ("GeneralAgent", "EnterpriseAgent", etc.)	"GeneralAgent"
max_execution_time	number	No	Maximum execution time in seconds (30-300)	120
options.enable_monitoring	boolean	No	Enable detailed monitoring	true
options.save_results	boolean	No	Save results for later retrieval	true
options.async_mode	boolean	No	Run request asynchronously	false

Response:

{
    "status": "success",
    "request_id": "uuid-string",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "agent_type": "GeneralAgent",
    "processing_time": 0.142,
    "results": {
        "analysis": {
            "intent": {
                "primary": "strategic_planning",
                "secondary": ["content_creation", "market_analysis"],
                "confidence": 0.89
            },
            "complexity": {
                "level": "high",
                "score": 8.5,
                "factors": ["multi_step_planning", "strategic_thinking"],
                "estimated_duration_minutes": 15
            },
            "success_probability": 0.85,
            "risk_factors": ["time_constraint", "resource_availability"],
            "adaptation_requirements": ["dynamic_planning", "feedback_integration"]
        },
        "plan": {
            "tasks": [
                {
                    "id": 1,
                    "description": "Market research and competitor analysis",
                    "priority": "high",
                    "duration_minutes": 120,
                    "dependencies": [],
                    "success_criteria": ["comprehensive_analysis", "actionable_insights"],
                    "fallback_strategies": ["use_previous_data", "simplified_analysis"]
                }
            ],
            "total_estimated_duration": 240,
            "critical_path": [1, 2, 3],
            "resource_requirements": {
                "cpu": "moderate",
                "memory": "high",
                "storage": "low"
            },
            "risk_mitigation": {
                "primary_risks": ["resource_shortage", "time_constraints"],
                "mitigation_strategies": ["resource_pooling", "parallel_processing"]
            }
        },
        "execution": {
            "status": "completed",
            "completed_tasks": 3,
            "total_tasks": 3,
            "success_rate": 1.0,
            "execution_time_minutes": 8.5,
            "adaptations_made": 1,
            "decisions_made": 2,
            "failed_tasks": [],
            "performance_metrics": {
                "efficiency_score": 0.92,
                "quality_score": 0.89,
                "completion_rate": 1.0
            },
            "iterations": [
                {
                    "iteration": 1,
                    "tasks_executed": 2,
                    "success_rate": 0.9,
                    "changes_made": ["refined_strategy", "adjusted_timeline"]
                }
            ]
        },
        "summary": "Comprehensive 3-month marketing strategy created with optimized budget allocation...",
        "recommendations": [
            "Focus on digital channels for cost-effectiveness",
            "Implement A/B testing for campaign optimization",
            "Consider seasonal trends in timing"
        ]
    },
    "monitoring": {
        "memory_usage": "145MB",
        "cpu_utilization": "12.5%",
        "cache_hit_rate": 0.78,
        "error_rate": 0.0
    },
    "metadata": {
        "version": "2.0.0",
        "model_used": "autonomous_engine_v2",
        "processing_mode": "synchronous"
    }
}

Status Codes:

• 200: Success
• 400: Bad Request (validation error)
• 429: Rate Limit Exceeded
• 500: Internal Server Error
• 503: Service Unavailable

Example Usage:

import requests
import json

url = "http://localhost:7860/api/v1/process"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-api-key"
}

payload = {
    "user_input": "Create a comprehensive marketing plan for our new mobile app",
    "context": {
        "budget": 50000,
        "timeline": "3 months",
        "team_size": 5,
        "industry": "technology"
    },
    "agent_type": "EnterpriseAgent",
    "max_execution_time": 180,
    "options": {
        "enable_monitoring": True,
        "save_results": True,
        "async_mode": False
    }
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()
print(json.dumps(result, indent=2))

2. Get Request Status

GET /api/v1/status/{request_id}

Description: Get the status of an asynchronous request.

Path Parameters:

• request_id (string): The unique request identifier

Response:

{
    "status": "completed",
    "request_id": "uuid-string",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "progress": {
        "stage": "execution",
        "completed_percentage": 75,
        "current_task": "content generation",
        "estimated_completion": "2024-11-29T17:05:00.000Z"
    },
    "partial_results": {
        "analysis": "completed",
        "plan": "completed",
        "execution": "in_progress"
    },
    "errors": [],
    "estimated_total_time": 120
}

3. Get Results

GET /api/v1/results/{request_id}

Description: Retrieve the complete results of a completed request.

Path Parameters:

• request_id (string): The unique request identifier

Query Parameters:

• format (string): Response format ("json", "summary", "detailed") - default: "json"

Response: Same as POST /api/v1/process response format.

Agent Management

4. List Available Agents

GET /api/v1/agents

Description: Get list of available agent types and their capabilities.

Response:

{
    "agents": [
        {
            "name": "GeneralAgent",
            "type": "general",
            "description": "Multi-domain task handling with balanced capabilities",
            "capabilities": [
                "task_planning",
                "context_analysis",
                "adaptive_execution"
            ],
            "specialties": ["general_purpose", "flexible_thinking"],
            "max_context_length": 5000,
            "typical_response_time": 0.15,
            "success_rate": 0.98
        },
        {
            "name": "EnterpriseAgent",
            "type": "enterprise",
            "description": "Strategic business planning and enterprise-level decision making",
            "capabilities": [
                "strategic_planning",
                "business_analysis",
                "risk_assessment",
                "compliance_awareness"
            ],
            "specialties": ["business_strategy", "financial_planning", "operational_optimization"],
            "max_context_length": 10000,
            "typical_response_time": 0.20,
            "success_rate": 0.96
        }
    ],
    "total_agents": 5,
    "default_agent": "GeneralAgent"
}

5. Get Agent Info

GET /api/v1/agents/{agent_name}

Description: Get detailed information about a specific agent.

Path Parameters:

• agent_name (string): Name of the agent

Response:

{
    "name": "EnterpriseAgent",
    "configuration": {
        "temperature": 0.7,
        "max_tokens": 2000,
        "top_p": 0.9,
        "frequency_penalty": 0.0,
        "presence_penalty": 0.0
    },
    "capabilities": [
        {
            "name": "strategic_planning",
            "description": "Long-term strategic planning and roadmap development",
            "supported_contexts": ["business", "finance", "operations"],
            "quality_score": 0.95
        }
    ],
    "performance_metrics": {
        "total_requests": 1250,
        "success_rate": 0.96,
        "average_response_time": 0.20,
        "memory_efficiency": 0.85,
        "error_rate": 0.04
    },
    "limitations": {
        "max_input_length": 10000,
        "max_execution_time": 300,
        "context_overflow_handling": "truncate"
    }
}

Performance Monitoring

6. System Health

GET /api/v1/health

Description: Get system health and status information.

Response:

{
    "status": "healthy",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "uptime_seconds": 86400,
    "version": "2.0.0",
    "system": {
        "memory": {
            "total_gb": 8.0,
            "used_gb": 2.5,
            "available_gb": 5.5,
            "usage_percentage": 31.25
        },
        "cpu": {
            "cores": 4,
            "usage_percentage": 12.5,
            "load_average": [0.5, 0.3, 0.2]
        },
        "disk": {
            "total_gb": 100.0,
            "used_gb": 15.0,
            "available_gb": 85.0,
            "usage_percentage": 15.0
        }
    },
    "services": {
        "api_server": "healthy",
        "agent_manager": "healthy",
        "cache_server": "healthy",
        "database": "not_configured"
    },
    "metrics": {
        "total_requests": 1250,
        "requests_per_minute": 5.2,
        "average_response_time": 0.142,
        "error_rate": 0.02
    }
}

7. Performance Metrics

GET /api/v1/metrics

Description: Get detailed performance metrics.

Query Parameters:

• time_range (string): Time range for metrics ("1h", "24h", "7d", "30d") - default: "1h"
• include_agent_details (boolean): Include per-agent metrics - default: false

Response:

{
    "time_range": "1h",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "overall_metrics": {
        "total_requests": 125,
        "successful_requests": 123,
        "failed_requests": 2,
        "success_rate": 0.984,
        "average_response_time": 0.142,
        "p50_response_time": 0.120,
        "p95_response_time": 0.280,
        "p99_response_time": 0.450,
        "requests_per_minute": 2.1,
        "peak_requests_per_minute": 8.5
    },
    "agent_metrics": {
        "GeneralAgent": {
            "requests": 75,
            "success_rate": 0.987,
            "average_response_time": 0.138,
            "error_rate": 0.013
        }
    },
    "system_metrics": {
        "memory_usage": {
            "peak_gb": 3.2,
            "average_gb": 2.1,
            "current_gb": 2.5
        },
        "cpu_usage": {
            "peak_percentage": 25.0,
            "average_percentage": 12.5,
            "current_percentage": 15.0
        }
    },
    "error_breakdown": {
        "validation_errors": 1,
        "timeout_errors": 1,
        "system_errors": 0
    },
    "cache_performance": {
        "hit_rate": 0.78,
        "total_requests": 125,
        "cache_hits": 98,
        "cache_misses": 27
    }
}

8. Analytics Dashboard Data

GET /api/v1/analytics

Description: Get data for analytics dashboard.

Query Parameters:

• dashboard_type (string): Type of dashboard ("overview", "performance", "agents")
• time_range (string): Time range for data
• granularity (string): Data granularity ("minute", "hour", "day")

Response:

{
    "dashboard_type": "overview",
    "time_range": "24h",
    "granularity": "hour",
    "data": {
        "response_times": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 0.145},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 0.142}
        ],
        "success_rates": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 0.98},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 0.984}
        ],
        "request_counts": [
            {"timestamp": "2024-11-29T16:00:00.000Z", "value": 65},
            {"timestamp": "2024-11-29T17:00:00.000Z", "value": 60}
        ],
        "agent_distribution": [
            {"agent": "GeneralAgent", "count": 85, "percentage": 68},
            {"agent": "EnterpriseAgent", "count": 25, "percentage": 20}
        ]
    },
    "trends": {
        "response_time_trend": "decreasing",
        "success_rate_trend": "stable",
        "request_volume_trend": "increasing"
    }
}

WebSocket APIs

9. Real-time Metrics Stream

WebSocket /ws/metrics

Description: Stream real-time performance metrics.

Connection:

const ws = new WebSocket('ws://localhost:7860/ws/metrics');

Message Format:

{
    "type": "metrics_update",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "data": {
        "response_time": 0.142,
        "memory_usage": 67.2,
        "cpu_usage": 12.5,
        "active_requests": 3,
        "queue_size": 0
    }
}

10. Execution Progress Stream

WebSocket /ws/progress/{request_id}

Description: Stream execution progress for a specific request.

Message Types:

Progress Update:

{
    "type": "progress_update",
    "request_id": "uuid",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "data": {
        "stage": "execution",
        "current_task": "generating_content",
        "completed_tasks": 2,
        "total_tasks": 5,
        "progress_percentage": 40,
        "estimated_time_remaining": 45
    }
}

Completion:

{
    "type": "completion",
    "request_id": "uuid",
    "timestamp": "2024-11-29T17:04:26.632Z",
    "status": "success",
    "summary": "Request completed successfully"
}

Error Handling

Error Response Format

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Input validation failed",
        "details": {
            "field": "user_input",
            "reason": "Input too long",
            "max_length": 10000,
            "current_length": 15000
        },
        "timestamp": "2024-11-29T17:04:26.632Z",
        "request_id": "uuid-string",
        "documentation_url": "https://docs.example.com/errors/VALIDATION_ERROR"
    }
}

Error Codes

Code	Description	HTTP Status	Recovery
VALIDATION_ERROR	Input validation failed	400	Fix input parameters
RATE_LIMIT_EXCEEDED	Rate limit exceeded	429	Wait and retry
AGENT_UNAVAILABLE	Requested agent unavailable	503	Try different agent
EXECUTION_TIMEOUT	Request execution timed out	504	Increase timeout or simplify
MEMORY_LIMIT_EXCEEDED	System memory limit exceeded	507	Reduce concurrent requests
INTERNAL_ERROR	Internal server error	500	Contact support

Rate Limiting

Rate Limits

• Global: 100 requests per minute
• Per IP: 100 requests per minute
• Per Agent: 200 requests per minute per agent type
• Burst Limit: 20 requests per second

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 60

Rate Limit Response

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Try again in 30 seconds.",
        "retry_after": 30,
        "limit": 100,
        "window": 60
    }
}

SDK Reference

Python SDK

Installation

pip install secure-ai-agents-suite

Basic Usage

from secure_ai_agents import AgentClient

# Initialize client
client = AgentClient(
    base_url="http://localhost:7860",
    api_key="your-api-key"
)

# Process request
result = client.process_request(
    user_input="Create a marketing strategy",
    context={"budget": 50000, "timeline": "3 months"},
    agent_type="EnterpriseAgent"
)

print(result.summary)

Async Usage

import asyncio
from secure_ai_agents import AsyncAgentClient

async def main():
    client = AsyncAgentClient(base_url="http://localhost:7860")
    
    # Submit async request
    request_id = await client.submit_request(
        user_input="Complex multi-step workflow",
        context={"priority": "high"}
    )
    
    # Monitor progress
    async for progress in client.monitor_progress(request_id):
        print(f"Progress: {progress.progress_percentage}%")
    
    # Get results
    result = await client.get_results(request_id)
    print(result.summary)

asyncio.run(main())

JavaScript SDK

Installation

npm install secure-ai-agents-suite

Basic Usage

import { AgentClient } from 'secure-ai-agents-suite';

const client = new AgentClient({
    baseUrl: 'http://localhost:7860',
    apiKey: 'your-api-key'
});

// Process request
const result = await client.processRequest({
    userInput: 'Create a business plan',
    context: { industry: 'technology', size: 'startup' },
    agentType: 'EnterpriseAgent'
});

console.log(result.summary);

WebSocket Usage

// Real-time progress monitoring
const progressStream = client.monitorProgress('request-id');

progressStream.on('progress', (progress) => {
    console.log(`Progress: ${progress.completedTasks}/${progress.totalTasks}`);
});

progressStream.on('complete', (result) => {
    console.log('Request completed:', result.summary);
});

Response Streaming

For large responses, you can enable streaming:

client = AgentClient(base_url="http://localhost:7860", stream=True)

async for chunk in client.process_request_stream(
    user_input="Complex analysis request"
):
    print(chunk)  # Process each chunk as it arrives

Rate Limiting and Performance

Best Practices

1. Use Async Mode: For complex requests, use async_mode: true
2. Batch Processing: Group similar requests when possible
3. Context Optimization: Keep context data minimal and relevant
4. Timeout Management: Set appropriate timeouts based on request complexity
5. Error Handling: Implement proper error handling with exponential backoff

Performance Optimization

# Enable response caching
client = AgentClient(
    base_url="http://localhost:7860",
    cache_responses=True,
    cache_ttl=3600
)

# Use connection pooling
client = AgentClient(
    base_url="http://localhost:7860",
    max_connections=10,
    max_keepalive_connections=5
)

# Enable compression
client = AgentClient(
    base_url="http://localhost:7860",
    compression=True
)

Changelog

Version 2.0.0 (2024-11-29)

• Added autonomous planning and reasoning capabilities
• Implemented real-time performance monitoring
• Added WebSocket APIs for streaming
• Enhanced security with input validation
• Improved error handling and recovery
• Added comprehensive API documentation

Version 1.5.0

• Basic agent functionality
• Simple request/response API
• Performance monitoring