oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity
Files
a9e727dac8d2a019d3493ee43fca11ce16081a8c
aitbc/docs/agent-coordinator/API.md
aitbc a9e727dac8
Some checks failed
API Endpoint Tests / test-api-endpoints (push) Has been cancelled
Details
Cross-Node Transaction Testing / transaction-test (push) Has been cancelled
Details
Deploy to Testnet / deploy-testnet (push) Has been cancelled
Details
Integration Tests / test-service-integration (push) Has been cancelled
Details
Multi-Node Stress Testing / stress-test (push) Has been cancelled
Details
Node Failover Simulation / failover-test (push) Has been cancelled
Details
Production Tests / Production Integration Tests (push) Has been cancelled
Details
Python Tests / test-python (push) Has been cancelled
Details
Security Scanning / security-scan (push) Has been cancelled
Details
CLI Tests / test-cli (push) Has been cancelled
Details
Documentation Validation / validate-docs (push) Has been cancelled
Details
Documentation Validation / validate-policies-strict (push) Has been cancelled
Details
Add agent heartbeat and task queue management endpoints to coordinator API 
- Add /agents/{agent_id}/heartbeat endpoint to receive and process agent heartbeats
- Add /tasks/queues endpoint to retrieve task queue sizes across all priorities
- Add /tasks/queues/{priority}/clear endpoint to clear specific priority queues
- Add /tasks/queues/stats endpoint to get detailed queue and distribution statistics
- Implement get_queue_sizes() method in TaskDistributor to return queue sizes by priority
- Implement clear_queue() method in TaskDistributor to drain
2026-05-07 18:49:17 +02:00

8.8 KiB
Raw Blame History

AITBC Agent Coordinator - API Reference

Base URL

http://localhost:9001

Authentication

Currently, the API does not require authentication. Future versions may support API key authentication and JWT tokens.

Agent Management API

Register Agent

Register a new agent with the coordinator.

Endpoint: POST /agents/register

Request Body:

{
  "agent_id": "string (required)",
  "agent_type": "string (required)",
  "capabilities": ["string"],
  "services": ["string"],
  "endpoints": {"string": "string"},
  "metadata": {"string": "any"}
}

Parameters:

  • agent_id (required): Unique identifier for the agent
  • agent_type (required): Type of agent (worker, provider, consumer, general)
  • capabilities (optional): Array of agent capabilities
  • services (optional): Array of available services
  • endpoints (optional): Object mapping service names to URLs
  • metadata (optional): Additional metadata as key-value pairs

Response (200 OK):

{
  "status": "success",
  "message": "Agent {agent_id} registered successfully",
  "agent_id": "string",
  "registered_at": "ISO 8601 timestamp"
}

Response (422 Unprocessable Entity):

{
  "detail": "Validation error message"
}

Response (500 Internal Server Error):

{
  "detail": "Failed to register agent: {error message}"
}

Example:

curl -X POST http://localhost:9001/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "hermes-agent",
    "agent_type": "worker",
    "capabilities": ["data-processing", "analysis"],
    "services": ["task-execution"],
    "endpoints": {"http": "http://localhost:9002"},
    "metadata": {"version": "1.0.0"}
  }'

Discover Agents

Discover agents based on filtering criteria.

Endpoint: POST /agents/discover

Request Body:

{
  "status": "string (optional)",
  "agent_type": "string (optional)",
  "capabilities": ["string (optional)"],
  "services": ["string (optional)"]
}

Parameters:

  • status (optional): Filter by agent status (active, inactive, busy, stale)
  • agent_type (optional): Filter by agent type
  • capabilities (optional): Filter by required capabilities
  • services (optional): Filter by available services

Response (200 OK):

{
  "status": "success",
  "query": {},
  "agents": [
    {
      "agent_id": "string",
      "agent_type": "string",
      "status": "string",
      "capabilities": ["string"],
      "services": ["string"],
      "endpoints": {"string": "string"},
      "metadata": {"string": "any"},
      "last_heartbeat": "ISO 8601 timestamp",
      "registration_time": "ISO 8601 timestamp",
      "load_metrics": {"string": "number"},
      "health_score": 0.0-1.0,
      "version": "string",
      "tags": ["string"]
    }
  ],
  "count": 0,
  "timestamp": "ISO 8601 timestamp"
}

Response (500 Internal Server Error):

{
  "detail": "Error discovering agents: {error message}"
}

Example:

curl -X POST http://localhost:9001/agents/discover \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "agent_type": "worker"
  }'

Get Agent Information

Retrieve detailed information about a specific agent.

Endpoint: GET /agents/{agent_id}

URL Parameters:

  • agent_id (required): The unique identifier of the agent

Response (200 OK):

{
  "status": "success",
  "agent": {
    "agent_id": "string",
    "agent_type": "string",
    "status": "string",
    "capabilities": ["string"],
    "services": ["string"],
    "endpoints": {"string": "string"},
    "metadata": {"string": "any"},
    "last_heartbeat": "ISO 8601 timestamp",
    "registration_time": "ISO 8601 timestamp",
    "load_metrics": {"string": "number"},
    "health_score": 0.0-1.0,
    "version": "string",
    "tags": ["string"]
  },
  "timestamp": "ISO 8601 timestamp"
}

Response (404 Not Found):

{
  "detail": "Agent not found"
}

Response (500 Internal Server Error):

{
  "detail": "Error getting agent: {error message}"
}

Example:

curl http://localhost:9001/agents/hermes-agent

Update Agent Status

Update the status and load metrics of an agent.

Endpoint: PUT /agents/{agent_id}/status

URL Parameters:

  • agent_id (required): The unique identifier of the agent

Request Body:

{
  "status": "string (required)",
  "load_metrics": {
    "active_connections": 0,
    "pending_tasks": 0,
    "cpu_usage": 0.0,
    "memory_usage": 0.0
  }
}

Parameters:

  • status (required): New agent status (active, inactive, busy, stale)
  • load_metrics (optional): Object containing load metrics

Response (200 OK):

{
  "status": "success",
  "message": "Agent {agent_id} status updated",
  "agent_id": "string",
  "new_status": "string",
  "updated_at": "ISO 8601 timestamp"
}

Response (422 Unprocessable Entity):

{
  "detail": "Validation error message"
}

Response (500 Internal Server Error):

{
  "detail": "Error updating agent status: {error message}"
}

Example:

curl -X PUT http://localhost:9001/agents/hermes-agent/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "busy",
    "load_metrics": {
      "active_connections": 5,
      "pending_tasks": 2
    }
  }'

Task Management API

Submit Task

Submit a task for distribution to agents.

Endpoint: POST /tasks/submit

Request Body:

{
  "task_data": {
    "task_type": "string",
    "model": "string",
    "prompt": "string",
    "parameters": {"string": "any"}
  },
  "priority": "string (required)",
  "requirements": {
    "capabilities": ["string"],
    "agent_type": "string"
  }
}

Parameters:

  • task_data (required): Object containing task information
  • priority (required): Task priority (urgent, critical, high, normal, low)
  • requirements (optional): Object specifying agent requirements

Response (200 OK):

{
  "status": "success",
  "message": "Task submitted successfully",
  "task_id": "UUID string",
  "priority": "string",
  "submitted_at": "ISO 8601 timestamp"
}

Response (400 Bad Request):

{
  "detail": "Invalid priority: {priority}"
}

Response (503 Service Unavailable):

{
  "detail": "Task distributor not available"
}

Response (500 Internal Server Error):

{
  "detail": "Error submitting task: {error message}"
}

Example:

curl -X POST http://localhost:9001/tasks/submit \
  -H "Content-Type: application/json" \
  -d '{
    "task_data": {
      "model": "llama2",
      "prompt": "test prompt"
    },
    "priority": "normal",
    "requirements": {}
  }'

Get Task Status

Get task distribution statistics and load balancer metrics.

Endpoint: GET /tasks/status

Response (200 OK):

{
  "status": "success",
  "stats": {
    "tasks_distributed": 0,
    "tasks_completed": 0,
    "tasks_failed": 0,
    "avg_distribution_time": 0.0,
    "load_balancer_stats": {
      "strategy": "least_connections",
      "total_assignments": 0,
      "successful_assignments": 0,
      "failed_assignments": 0,
      "success_rate": 0.0,
      "active_agents": 0,
      "agent_weights": 0,
      "avg_agent_load": 0
    },
    "queue_sizes": {
      "urgent": 0,
      "critical": 0,
      "high": 0,
      "normal": 0,
      "low": 0
    }
  },
  "timestamp": "ISO 8601 timestamp"
}

Response (503 Service Unavailable):

{
  "detail": "Task distributor not available"
}

Response (500 Internal Server Error):

{
  "detail": "Error getting task status: {error message}"
}

Example:

curl http://localhost:9001/tasks/status

Health Check

Service Health

Check the health of the agent coordinator service.

Endpoint: GET /health

Response (200 OK):

{
  "status": "healthy",
  "version": "string",
  "timestamp": "ISO 8601 timestamp"
}

Example:

curl http://localhost:9001/health

Error Codes

Status Code Description
200 Success
400 Bad Request - Invalid parameters
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
500 Internal Server Error
503 Service Unavailable - Component not ready

Rate Limiting

Currently, rate limiting is not implemented. Future versions may include rate limiting to prevent abuse.

WebSocket Support

WebSocket support is planned for future releases to provide real-time updates on:

  • Agent status changes
  • Task distribution events
  • Load balancer metrics updates

OpenAPI Specification

The API follows OpenAPI 3.0 specification. An OpenAPI JSON schema can be generated from the FastAPI application by visiting:

http://localhost:9001/openapi.json

Interactive API documentation is available at:

http://localhost:9001/docs