Universal Agent Deployment Module (UADM) API¶

The UADM API enables programmatic control over AI agent deployment, management, and monitoring across various devices and environments.

Overview¶

The UADM API provides endpoints for:

Agent deployment and lifecycle management
Device registration and control
Real-time monitoring and metrics
Security and access control

Authentication¶

All API requests require authentication using a Bearer token:

Authorization: Bearer <your_token>

API Endpoints¶

Agent Management¶

Deploy Agent¶

POST /api/uadm/agents/deploy

Request body:

{
  "agentId": "string",
  "deviceId": "string",
  "configuration": {
    "memory": "number",
    "cpu": "number",
    "permissions": ["string"]
  }
}

Response:

{
  "deploymentId": "string",
  "status": "DEPLOYING",
  "timestamp": "string"
}

List Deployments¶

GET /api/uadm/agents/deployments

Response:

{
  "deployments": [
    {
      "id": "string",
      "agentId": "string",
      "deviceId": "string",
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Device Management¶

Register Device¶

POST /api/uadm/devices/register

Request body:

{
  "name": "string",
  "type": "string",
  "capabilities": ["string"],
  "connectionInfo": {
    "protocol": "string",
    "address": "string",
    "port": "number"
  }
}

Response:

{
  "deviceId": "string",
  "token": "string",
  "status": "REGISTERED"
}

Get Device Status¶

GET /api/uadm/devices/{deviceId}/status

Response:

{
  "deviceId": "string",
  "status": "string",
  "lastSeen": "string",
  "deployedAgents": ["string"],
  "metrics": {
    "cpu": "number",
    "memory": "number",
    "network": "object"
  }
}

Monitoring & Metrics¶

Get Agent Metrics¶

GET /api/uadm/metrics/agents/{agentId}

Response:

{
  "agentId": "string",
  "metrics": {
    "requests": "number",
    "latency": "number",
    "errors": "number",
    "uptime": "string"
  },
  "period": "string"
}

Stream Device Logs¶

GET /api/uadm/devices/{deviceId}/logs

WebSocket connection for real-time log streaming:

{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "metadata": "object"
}

Security & Access Control¶

Update Agent Permissions¶

PUT /api/uadm/agents/{agentId}/permissions

Request body:

{
  "permissions": ["string"],
  "scope": "string"
}

Response:

{
  "agentId": "string",
  "permissions": ["string"],
  "updated": "boolean"
}

WebSocket Events¶

Connect to WebSocket for real-time updates:

ws://api.aidddmap.com/uadm/events

Event Types¶

Agent Status Change¶

{
  "type": "AGENT_STATUS_CHANGE",
  "data": {
    "agentId": "string",
    "status": "string",
    "timestamp": "string"
  }
}

Device Connection¶

{
  "type": "DEVICE_CONNECTION",
  "data": {
    "deviceId": "string",
    "status": "string",
    "timestamp": "string"
  }
}

Error Handling¶

Errors follow a standard format:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object"
  }
}

Common error codes:

AGENT_NOT_FOUND: Agent does not exist
DEVICE_OFFLINE: Device is not connected
INSUFFICIENT_RESOURCES: Device lacks required resources
PERMISSION_DENIED: Insufficient permissions

Rate Limiting¶

1000 requests per hour per API token
Headers indicate limits:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Best Practices¶

Error Handling
Implement proper error handling for all API calls
Use exponential backoff for retries
Resource Management
Monitor agent resource usage
Set appropriate resource limits
Security
Rotate API tokens regularly
Use minimal required permissions
Monitoring
Subscribe to WebSocket events for real-time updates
Implement health checks

SDK Support¶

Official SDKs available for:

JavaScript/TypeScript
Python
Go
Java

Example using TypeScript SDK:

import { UADMClient } from "@aidddmap/uadm-sdk";

const client = new UADMClient({
  token: "your_token",
});

// Deploy an agent
await client.agents.deploy({
  agentId: "agent_id",
  deviceId: "device_id",
  configuration: {
    memory: 512,
    cpu: 1,
  },
});