Agents API Reference¶

Overview¶

The Agents API provides endpoints for managing and interacting with AIDDDMAP's AI agents, including the core 6+1 agents and custom agents created through UADM.

Authentication Requirements¶

All API requests require authentication using an API key:

Authorization: Bearer YOUR_API_KEY

API Base URL¶

https://api.aidddmap.com/v1

Agent Management Endpoints¶

Agent List Retrieval¶

GET /agents

Returns a list of all available agents for the authenticated user.

Agent List Response¶

{
  "agents": [
    {
      "id": "df-001",
      "name": "DataFinder",
      "type": "core",
      "status": "active",
      "capabilities": ["search", "discovery", "validation"]
    },
    {
      "id": "custom-001",
      "name": "CustomAgent",
      "type": "uadm",
      "status": "active",
      "capabilities": ["processing"]
    }
  ]
}

Agent Deployment¶

POST /agents/deploy

Deploy an agent to the IDAT canvas or specific workflow.

Agent Deployment Request Body¶

{
  "agentId": "df-001",
  "workflowId": "workflow-123",
  "configuration": {
    "mode": "active",
    "parameters": {
      "searchDepth": 3,
      "timeout": 30000
    }
  }
}

Agent Deployment Response¶

{
  "deploymentId": "deploy-456",
  "status": "success",
  "agent": {
    "id": "df-001",
    "status": "deployed"
  }
}

Agent Status Retrieval¶

GET /agents/{agentId}/status

Get the current status and metrics of a specific agent.

Agent Status Response¶

{
  "id": "df-001",
  "status": "active",
  "metrics": {
    "tasksCompleted": 45,
    "uptime": "2d 3h",
    "lastActivity": "2024-01-14T12:00:00Z"
  }
}

Agent Configuration Update¶

PATCH /agents/{agentId}/config

Update the configuration of a deployed agent.

Configuration Update Request Body¶

{
  "parameters": {
    "searchDepth": 5,
    "timeout": 60000
  }
}

Configuration Update Response¶

{
  "id": "df-001",
  "status": "updated",
  "configuration": {
    "searchDepth": 5,
    "timeout": 60000
  }
}

Agent Communication Endpoints¶

Agent Message Sending¶

POST /agents/{agentId}/message

Send a message or command to a specific agent.

Message Request Body¶

{
  "type": "command",
  "content": {
    "action": "search",
    "parameters": {
      "query": "health data",
      "limit": 10
    }
  }
}

Message Response¶

{
  "messageId": "msg-789",
  "status": "received",
  "response": {
    "type": "acknowledgement",
    "content": "Search initiated"
  }
}

Agent Chat History Retrieval¶

GET /agents/{agentId}/chat

Retrieve chat history with a specific agent.

Chat History Response¶

{
  "messages": [
    {
      "id": "msg-123",
      "timestamp": "2024-01-14T11:00:00Z",
      "sender": "user",
      "content": "Start data search"
    },
    {
      "id": "msg-124",
      "timestamp": "2024-01-14T11:00:05Z",
      "sender": "agent",
      "content": "Search initiated"
    }
  ]
}

UADM Integration Endpoints¶

Custom Agent Creation¶

POST /uadm/agents

Create a new custom agent through UADM.

Custom Agent Request Body¶

{
  "name": "CustomProcessor",
  "description": "Custom data processing agent",
  "capabilities": ["processing", "analysis"],
  "configuration": {
    "model": "gpt-4",
    "parameters": {
      "maxTokens": 1000
    }
  }
}

Custom Agent Response¶

{
  "id": "custom-002",
  "status": "created",
  "deploymentReady": true
}

API Error Responses¶

The API uses standard HTTP response codes:

200 - Success
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
500 - Internal Server Error

Error response format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid agent configuration parameter",
    "details": {
      "parameter": "searchDepth",
      "reason": "Must be between 1 and 10"
    }
  }
}

API Rate Limiting¶

API requests are limited to:

100 requests per minute for standard users
1000 requests per minute for enterprise users

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1516131940

WebSocket Connection Guide¶

For real-time agent communication:

const ws = new WebSocket("wss://api.aidddmap.com/v1/agents/websocket");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Agent update:", data);
};

SDK Code Examples¶

TypeScript Implementation¶

import { AIDDDMAPClient } from "@aidddmap/sdk";

const client = new AIDDDMAPClient({
  apiKey: "YOUR_API_KEY",
});

// Deploy an agent
await client.agents.deploy("df-001", {
  workflowId: "workflow-123",
  configuration: {
    mode: "active",
  },
});

// Send message to agent
await client.agents.sendMessage("df-001", {
  type: "command",
  content: {
    action: "search",
    parameters: {
      query: "health data",
    },
  },
});

Python Implementation¶

from aidddmap import Client

client = Client(api_key='YOUR_API_KEY')

# Deploy an agent
response = client.agents.deploy(
    agent_id='df-001',
    workflow_id='workflow-123',
    configuration={
        'mode': 'active'
    }
)

# Send message to agent
response = client.agents.send_message(
    agent_id='df-001',
    message={
        'type': 'command',
        'content': {
            'action': 'search',
            'parameters': {
                'query': 'health data'
            }
        }
    }
)