michael f811854198 added Quality Audit and fixed various bugs

2025-09-05 13:41:33 -05:00

9.8 KiB

Raw Blame History

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

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:

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:

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:

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:

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:

{
    "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:

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

Error Responses

Invalid API Key (401)

{
    "detail": "Invalid API key"
}

Unsupported Media Type (415)

{
    "error": "Unsupported Media Type",
    "message": "Request must be JSON"
}

Database Error (500)

{
    "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)

{
    "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:

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

Response:

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

Best Practices

Use descriptive names: Agent names should be unique and descriptive to avoid confusion
Include version information: Use the version field to track agent iterations
Set appropriate status: Keep the status field updated to reflect the agent's current state
Provide contact information: Include a contact_person for operational support
Use tags effectively: Tags help with categorization and searching
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.

9.8 KiB Raw Blame History