Skip to main content

Workers API

AI Workers are the core of ByteEngine's healthcare AI platform. They are intelligent agents that can be configured with specific models, tools, and knowledge bases to handle complex healthcare workflows.

Base URL​

https://api.engine.boolbyte.com/api/workers

Create Worker​

POST /api/workers

Creates a new AI Worker with specified capabilities and configuration.

Using JavaScript SDK:

import { EngineClient } from '@boolbyte/engine';

const client = new EngineClient({ apiKey: 'YOUR_API_KEY' });

const worker = await client.worker.createWorker({
  name: 'clinical-analyzer',
  description: 'Healthcare AI assistant specialized in clinical data analysis',
  instructions: 'You are a healthcare AI assistant specialized in clinical data analysis. Provide insights while maintaining patient privacy.',
  defaultModelName: 'openai/gpt-4',
  modelNames: ['openai/gpt-4', 'openai/gpt-3.5-turbo'],
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read', 'write'],
          resourceTypes: ['Patient', 'Observation', 'Condition']
        }
      }
    ],
    toolkits: [
      {
        toolkitName: 'medical_analysis',
        config: {
          includeLabResults: true,
          includeDiagnostics: true
        },
        excludeToolIds: ['deprecated_tool']
      }
    ]
  }
});

Request Body:

{
  "name": "clinical-analyzer",
  "description": "Healthcare AI assistant specialized in clinical data analysis",
  "instructions": "You are a healthcare AI assistant specialized in clinical data analysis. Provide insights while maintaining patient privacy.",
  "defaultModelName": "openai/gpt-4",
  "modelNames": ["openai/gpt-4", "openai/gpt-3.5-turbo"],
  "toolConfigs": {
    "tools": [
      {
        "toolName": "fhir_access",
        "config": {
          "serverId": "fhir-server-123",
          "permissions": ["read", "write"],
          "resourceTypes": ["Patient", "Observation", "Condition"]
        }
      }
    ],
    "toolkits": [
      {
        "toolkitName": "medical_analysis",
        "config": {
          "includeLabResults": true,
          "includeDiagnostics": true
        },
        "excludeToolIds": ["deprecated_tool"]
      }
    ]
  }
}

Response:

{
  "success": true,
  "message": "Worker created successfully",
  "data": {
    "id": "worker-456",
    "name": "clinical-analyzer",
    "description": "Healthcare AI assistant specialized in clinical data analysis",
    "instructions": "You are a healthcare AI assistant specialized in clinical data analysis. Provide insights while maintaining patient privacy.",
    "model": "openai/gpt-4",
    "endpointId": "endpoint-789",
    "toolConfigs": {
      "tools": [
        {
          "toolName": "fhir_access",
          "config": {
            "serverId": "fhir-server-123",
            "permissions": ["read", "write"],
            "resourceTypes": ["Patient", "Observation", "Condition"]
          }
        }
      ],
      "toolkits": [
        {
          "toolkitName": "medical_analysis",
          "config": {
            "includeLabResults": true,
            "includeDiagnostics": true
          },
          "excludeToolIds": ["deprecated_tool"]
        }
      ]
    },
    "teamId": "team-123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List Workers​

GET /api/workers

Retrieves all AI Workers for your team.

Using JavaScript SDK:

const workers = await client.worker.listWorkers();

Response:

{
  "success": true,
  "message": "Workers retrieved successfully", 
  "data": [
    {
      "id": "worker-456",
      "name": "clinical-analyzer",
      "description": "Healthcare AI assistant specialized in clinical data analysis",
      "instructions": "Provide insights while maintaining patient privacy",
      "model": "openai/gpt-4",
      "endpointId": "endpoint-789",
      "teamId": "team-123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Get Worker​

GET /api/workers/{workerId}

Retrieves the configuration and status of a specific AI Worker.

Using JavaScript SDK:

const worker = await client.worker.getWorker('worker-456');

Response:

{
  "success": true,
  "message": "Worker retrieved successfully",
  "data": {
    "id": "worker-456",
    "name": "clinical-analyzer",
    "description": "Healthcare AI assistant specialized in clinical data analysis",
    "instructions": "You are a healthcare AI assistant specialized in clinical data analysis. Provide insights while maintaining patient privacy.",
    "model": "openai/gpt-4",
    "endpointId": "endpoint-789",
    "toolConfigs": {
      "tools": [
        {
          "toolName": "fhir_access",
          "config": {
            "serverId": "fhir-server-123",
            "permissions": ["read", "write"],
            "resourceTypes": ["Patient", "Observation", "Condition"]
          }
        }
      ]
    },
    "teamId": "team-123",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Update Worker​

PUT /api/workers/{workerId}

Updates an AI Worker's configuration, tools, or system prompt.

Using JavaScript SDK:

const updatedWorker = await client.worker.updateWorker('worker-456', {
  name: 'clinical-analyzer-v2',
  instructions: 'Updated system prompt with new guidelines...',
  defaultModelName: 'openai/gpt-4',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-456',
          permissions: ['read']
        }
      }
    ]
  }
});

Request Body:

{
  "name": "clinical-analyzer-v2",
  "description": "Updated healthcare AI assistant",
  "instructions": "Updated system prompt with new guidelines...",
  "defaultModelName": "openai/gpt-4",
  "modelNames": ["openai/gpt-4"],
  "toolConfigs": {
    "tools": [
      {
        "toolName": "fhir_access",
        "config": {
          "serverId": "fhir-server-456",
          "permissions": ["read"]
        }
      }
    ]
  }
}

Delete Worker​

DELETE /api/workers/{workerId}

Permanently deletes an AI Worker and all associated sessions.

Using JavaScript SDK:

await client.worker.deleteWorker('worker-456');

Response:

{
  "success": true,
  "message": "Worker deleted successfully",
  "data": null
}

Worker Configuration​

Required Fields​

  • name: Unique name for the worker
  • defaultModelName: Primary AI model to use

Optional Fields​

  • description: Human-readable description
  • instructions: System prompt defining worker behavior
  • modelNames: Array of available models
  • toolConfigs: Configuration for tools, toolkits, and functions

ToolConfigs Structure​

Tools​

Individual tools that can be attached to workers:

{
  "toolName": "fhir_access",
  "config": {
    "serverId": "fhir-server-123",
    "permissions": ["read", "write"],
    "resourceTypes": ["Patient", "Observation"]
  }
}

Toolkits​

Collections of related tools:

{
  "toolkitName": "medical_analysis",
  "config": {
    "includeLabResults": true,
    "includeDiagnostics": true
  },
  "excludeToolIds": ["deprecated_tool"]
}

Common Use Cases​

Clinical Documentation Assistant​

const clinicalWorker = await client.worker.createWorker({
  name: 'clinical-docs',
  description: 'AI assistant for clinical documentation',
  instructions: 'Help clinicians create accurate, comprehensive clinical documentation following best practices.',
  defaultModelName: 'openai/gpt-4',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read', 'write'],
          resourceTypes: ['Patient', 'Encounter', 'Condition', 'Observation']
        }
      }
    ]
  }
});

Lab Results Analyzer​

const labWorker = await client.worker.createWorker({
  name: 'lab-analyzer',
  description: 'AI assistant for analyzing laboratory results',
  instructions: 'Analyze laboratory results and provide clinical insights, flagging abnormal values and trends.',
  defaultModelName: 'openai/gpt-4',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read'],
          resourceTypes: ['Observation', 'DiagnosticReport']
        }
      }
    ]
  }
});

Patient Communication Assistant​

const patientWorker = await client.worker.createWorker({
  name: 'patient-communication',
  description: 'AI assistant for patient communication',
  instructions: 'Help patients understand their health information in clear, empathetic language.',
  defaultModelName: 'openai/gpt-4',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read'],
          resourceTypes: ['Patient', 'Condition', 'MedicationStatement']
        }
      }
    ]
  }
});

Error Handling​

{
  "success": false,
  "message": "Worker not found",
  "data": null,
  "error": {
    "code": "worker_not_found",
    "details": "Worker with ID 'worker-456' not found"
  }
}

Common Error Codes​

  • worker_not_found: Worker ID doesn't exist
  • invalid_model: Specified model is not available
  • invalid_tool: Tool configuration is invalid
  • name_taken: Worker name already exists
  • insufficient_permissions: Missing required permissions

Next Steps​