agent_tracker/docs/agent_tracker_API_docs.md

# Agent Registration API Documentation

## Overview

The Agent Registration API allows you to register AI agents and track their usage in the AgentHub system. The API automatically handles duplicate registrations by tracking usage when an agent with the same name already exists.

**Base URL:** `https://ai-sandbox.oliver.solutions/agent_collector/agents`

## Authentication

All requests require authentication using a static API key.

**API Key:** `agent-collector-static-key-2024-secure`

**Header:** `X-API-Key`

## Agent Registration Endpoint

### POST /agents

Register a new agent or track usage of an existing agent.

**URL:** `https://ai-sandbox.oliver.solutions/agent_collector/agents`

**Method:** `POST`

**Required Headers:**
- `Content-Type: application/json`
- `X-API-Key: agent-collector-static-key-2024-secure`

## Request Schema

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | The unique name of the agent (minimum 1 character) |
| `description` | string | A detailed description of the agent's functionality (minimum 1 character) |
| `purpose` | string | The primary purpose or goal of the agent (minimum 1 character) |
| `tool` | string | The tool or platform where the agent operates (minimum 1 character) |

### Optional Fields

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `location` | string | Where the agent is deployed or operates | null |
| `userbase` | array[string] | List of user groups or departments that use this agent | null |
| `version` | string | Version number or identifier of the agent | null |
| `creation_date` | string | ISO 8601 datetime when the agent was first created | null |
| `last_updated` | string | ISO 8601 datetime when the agent was last modified | null |
| `capabilities` | array[string] | List of specific capabilities or features the agent provides | null |
| `status` | string | Current operational status of the agent | "development" |
| `department` | string | Department or team that owns/manages the agent | null |
| `contact_person` | string | Primary contact for questions about this agent | null |
| `tags` | array[string] | Keywords or labels for categorizing the agent | null |
| `metadata` | object | Additional key-value pairs of agent information | null |

### Status Values

The `status` field accepts the following values (case-insensitive):
- `"active"` - Agent is live and operational
- `"inactive"` - Agent is temporarily disabled
- `"deprecated"` - Agent is being phased out
- `"development"` - Agent is in development/testing phase (default)

## Usage Examples

### Basic Agent Registration

**cURL Example:**
```bash
curl -X POST https://ai-sandbox.oliver.solutions/agent_collector/agents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: agent-collector-static-key-2024-secure" \
  -d '{
    "name": "CustomerSupportBot",
    "description": "AI assistant that handles customer inquiries and support tickets",
    "purpose": "Provide 24/7 automated customer support and reduce response times",
    "tool": "chat-sandbox"
  }'
```

**Python Example:**
```python
import requests
import json

url = "https://ai-sandbox.oliver.solutions/agent_collector/agents"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "agent-collector-static-key-2024-secure"
}

data = {
    "name": "CustomerSupportBot",
    "description": "AI assistant that handles customer inquiries and support tickets",
    "purpose": "Provide 24/7 automated customer support and reduce response times",
    "tool": "chat-sandbox"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

### Complex Agent Registration

**cURL Example:**
```bash
curl -X POST https://ai-sandbox.oliver.solutions/agent_collector/agents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: agent-collector-static-key-2024-secure" \
  -d '{
    "name": "DataAnalysisAgent",
    "description": "Advanced AI agent that performs automated data analysis and generates business insights",
    "purpose": "Transform raw business data into actionable insights and recommendations",
    "tool": "Custom Python Framework",
    "location": "AWS us-east-1",
    "userbase": ["Data Science Team", "Business Intelligence", "Executive Team"],
    "version": "2.1.3",
    "creation_date": "2024-01-15T10:30:00Z",
    "last_updated": "2024-08-22T14:45:30Z",
    "capabilities": ["Data Visualization", "Trend Analysis", "Predictive Modeling", "Report Generation"],
    "status": "active",
    "department": "Data Science",
    "contact_person": "Dr. Sarah Johnson",
    "tags": ["analytics", "business-intelligence", "automation", "reporting"],
    "metadata": {
      "framework": "TensorFlow",
      "language": "Python",
      "memory_usage": "2GB",
      "processing_time": "5-10 minutes"
    }
  }'
```

**Python Example:**
```python
import requests
import json
from datetime import datetime

url = "https://ai-sandbox.oliver.solutions/agent_collector/agents"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "agent-collector-static-key-2024-secure"
}

data = {
    "name": "DataAnalysisAgent",
    "description": "Advanced AI agent that performs automated data analysis and generates business insights",
    "purpose": "Transform raw business data into actionable insights and recommendations",
    "tool": "Custom Python Framework",
    "location": "AWS us-east-1",
    "userbase": ["Data Science Team", "Business Intelligence", "Executive Team"],
    "version": "2.1.3",
    "creation_date": "2024-01-15T10:30:00Z",
    "last_updated": datetime.utcnow().isoformat() + "Z",
    "capabilities": ["Data Visualization", "Trend Analysis", "Predictive Modeling", "Report Generation"],
    "status": "active",
    "department": "Data Science",
    "contact_person": "Dr. Sarah Johnson",
    "tags": ["analytics", "business-intelligence", "automation", "reporting"],
    "metadata": {
        "framework": "TensorFlow",
        "language": "Python",
        "memory_usage": "2GB",
        "processing_time": "5-10 minutes"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

## Response Formats

### Successful New Agent Registration

When a new agent is successfully registered:

```json
{
    "status": "success",
    "message": "Agent data collected successfully",
    "agent_id": "64f7b8a9e1234567890abcde"
}
```

### Usage Tracking Response

When an agent with the same name already exists, the system logs usage instead of creating a duplicate:

```json
{
    "status": "usage_logged",
    "message": "Agent already exists, usage tracked",
    "agent_name": "CustomerSupportBot"
}
```

### Error Responses

#### Invalid API Key (401)
```json
{
    "detail": "Invalid API key"
}
```

#### Unsupported Media Type (415)
```json
{
    "error": "Unsupported Media Type",
    "message": "Request must be JSON"
}
```

#### Database Error (500)
```json
{
    "error": "Database Error",
    "message": "Failed to store agent data. MongoDB may be unavailable or there was an error processing the request.",
    "agent_data": {
        "name": "YourAgentName",
        "description": "Your agent description",
        "purpose": "Your agent purpose",
        "tool": "YourAgentTool"
    }
}
```

#### Database Unavailable (503)
```json
{
    "error": "Database Unavailable",
    "message": "MongoDB connection is not available. Please check the database setup.",
    "agent_data": {
        "name": "YourAgentName",
        "description": "Your agent description", 
        "purpose": "Your agent purpose",
        "tool": "YourAgentTool"
    }
}
```

## Usage Tracking Behavior

The API implements intelligent duplicate detection and usage tracking:

### New Agent Registration
- When you register an agent with a **new name**, the system creates a new agent record
- Returns a success response with the new agent's unique ID

### Usage Tracking
- When you register an agent with an **existing name**, the system:
  - Logs the usage attempt with a timestamp
  - Compares the submitted data with the existing agent data
  - Updates the existing agent record if any fields have changed
  - Returns a usage tracking response

### Data Updates
If usage tracking detects that the submitted agent data differs from the existing record (excluding the name field), the system will automatically update the existing agent with the new information. This ensures agent records stay current while maintaining usage statistics.

## Date Format

All date fields (`creation_date`, `last_updated`) should be provided in **ISO 8601 format**:
- `"2024-08-22T14:45:30Z"` (with timezone)
- `"2024-08-22T14:45:30"` (without timezone)

## Health Check

You can check if the API is operational by sending a GET request with JSON Accept header:

```bash
curl -H "Accept: application/json" https://ai-sandbox.oliver.solutions/agent_collector/agents
```

Response:
```json
{
    "status": "healthy",
    "message": "Agent collector API is running",
    "timestamp": "2024-08-22T14:45:30.123456",
    "database": {
        "healthy": true,
        "connection_status": "connected"
    }
}
```

## Best Practices

1. **Use descriptive names**: Agent names should be unique and descriptive to avoid confusion
2. **Include version information**: Use the `version` field to track agent iterations
3. **Set appropriate status**: Keep the `status` field updated to reflect the agent's current state
4. **Provide contact information**: Include a `contact_person` for operational support
5. **Use tags effectively**: Tags help with categorization and searching
6. **Handle errors gracefully**: Always check response status codes and handle errors appropriately

## Rate Limiting

Currently, there are no explicit rate limits on the API, but please be considerate of the shared infrastructure and avoid excessive concurrent requests.

## Support

For technical support or questions about the Agent Registration API, please contact the AgentHub development team.