Sessions & Tasks — Context and State Management

In healthcare AI systems, context matters. A single patient query or diagnostic task may span multiple AI calls, reference several FHIR resources, or involve an entire workflow of actions.

That's why ByteEngine introduces Sessions and Tasks — two powerful abstractions that give your AI workers memory, state, and control over complex healthcare operations.

What Are Sessions?

A Session in ByteEngine is like a conversation or context container between you (or your app) and your AI Worker. It stores all the relevant information, messages, and intermediate results — ensuring your AI agent understands context across multiple turns.

Think of Sessions as:

• A chat history for your AI worker
• A stateful memory that persists over multiple API calls
• A secure container for all FHIR or DICOM data referenced in the conversation

Real-World Example

Let's say you're building an AI-powered radiology assistant that:

1. Fetches a patient's latest chest X-ray (from DICOM)
2. Reads their clinical notes (from FHIR Observation)
3. Generates a preliminary summary for a radiologist

You wouldn't want the AI to "forget" the patient's context between steps. Instead, you'd create a Session — which keeps the FHIR resources, conversation messages, and AI outputs together in one secure thread.

Creating a Session

You can create a session via the UI or API.

Using the ByteEngine Console

1. Go to AI Orchestration → Sessions
2. Click "New Session"
3. Select:
   • Worker: e.g. radiology-assistant
   • Context type: FHIR or Generic
   • Optional: Add initial patient ID or reference
4. Once created, the session appears in your dashboard, and you can start adding messages or tasks

Using the REST API

curl -X POST https://api.engine.boolbyte.com/api/sessions \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workerId": "radiology-assistant",
    "metadata": {
      "name": "radiology-session-001",
      "context": {
        "type": "FHIR",
        "patient": "Patient/123"
      }
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "sess_67890",
    "workerId": "radiology-assistant",
    "metadata": {
      "name": "radiology-session-001",
      "context": {
        "type": "FHIR",
        "patient": "Patient/123"
      }
    },
    "messages": [],
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

Using JavaScript SDK

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

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

// Create a session
const session = await client.session.createSession({
  workerId: 'radiology-assistant',
  metadata: {
    name: 'radiology-session-001',
    context: {
      type: 'FHIR',
      patient: 'Patient/123'
    }
  }
});

console.log('Session created:', session.data.id);

This session can now receive messages, tasks, and tool invocations.

Adding Messages to a Session

Messages provide conversation history and context cues to your AI Worker.

curl -X POST https://api.engine.boolbyte.com/api/sessions/sess_67890/messages \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Summarize the latest X-ray and related observations for Patient 123."
  }'

The system automatically updates the session context, adding this message to the state log. You can view session messages anytime via the UI or API.

What Are Tasks?

Tasks are atomic units of work executed within a session. Each task represents a specific AI operation — e.g., generating a summary, classifying a DICOM image, or extracting structured data.

Think of them as:

• "Action nodes" in your session workflow
• Each task produces outputs (results, FHIR resources, or function calls)
• They can call external tools, functions, or other ByteEngine services (e.g., pipelines or FHIR servers)

Example: Creating a Task

curl -X POST https://api.engine.boolbyte.com/api/sessions/sess_67890/tasks \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Summarize imaging findings and FHIR observations for the patient.",
    "model": "medgemma-27b",
    "temperature": 0.7
  }'

Response:

{
  "success": true,
  "data": {
    "id": "task_98234",
    "sessionId": "sess_67890",
    "status": "running",
    "instructions": "Summarize imaging findings and FHIR observations for the patient.",
    "model": "medgemma-27b",
    "createdAt": "2024-01-15T12:05:00.000Z",
    "updatedAt": "2024-01-15T12:05:00.000Z"
  }
}

When complete, the task will store results directly in the session history.

Using JavaScript SDK

// Create a task within the session
const task = await client.task.createTask(session.data.id, {
  instructions: "Summarize imaging findings and FHIR observations for the patient.",
  model: "medgemma-27b",
  temperature: 0.7
});

console.log('Task created:', task.data.id);

YAML Configuration Example

You can also define sessions and tasks declaratively using YAML — especially when orchestrating workflows.

session:
  id: sess_radiology
  worker: radiology-assistant
  context:
    type: FHIR
    patient: Patient/123
  messages:
    - role: user
      content: "Analyze the patient's latest radiology image and summarize findings."

  tasks:
    - name: retrieve-dicom
      tool: DICOM.fetch
      params:
        studyId: "study-abc"

    - name: summarize
      tool: Model.generate
      params:
        prompt: "Summarize the findings from the retrieved image."

This configuration can be uploaded to ByteEngine via the console or CLI.

How Sessions, Tasks & Workers Fit Together

+------------------+
|   AI Worker      |
|------------------|
| Reacts to Input  |
| Calls Tools (MCP)|
+--------+---------+
         |
         v
+------------------+
|   Session        |
|------------------|
| Stores Context   |
| Stores Messages  |
| Tracks Tasks     |
+--------+---------+
         |
         v
+------------------+
|     Task         |
|------------------|
| Executes Action  |
| Returns Result   |
+------------------+

Flow Summary:

1. User or workflow creates a Session for a specific Worker
2. Messages are added to maintain conversation state
3. Tasks are queued and executed
4. Outputs are stored back into the Session — ensuring continuity and traceability

Security & Compliance Notes

• All session data is encrypted at rest and in transit
• Sessions automatically expire or can be set to auto-delete after inactivity
• Patient identifiers in context are FHIR-referenced only (no raw PHI)
• Tasks can be logged for auditing in compliance with HIPAA/GDPR

Best Practices

Goal	Tip
Maintain long-running clinical context	Use one Session per patient encounter
Audit actions	Enable Session logging in compliance settings
Debug AI outputs	Retrieve full Session message trace via API
Control costs	Auto-close inactive sessions via timeout rules

Real-World Use Cases

Clinical Consultation Session

// Create a session for a patient consultation
const consultationSession = await client.session.createSession({
  workerId: 'clinical-assistant',
  metadata: {
    patientId: 'patient-123',
    consultationType: 'follow-up',
    providerId: 'provider-456'
  }
});

// Add initial context
await client.session.addMessage(consultationSession.data.id, {
  role: 'system',
  content: 'Patient is here for diabetes follow-up. Review latest lab results and provide recommendations.'
});

// Run analysis task
const analysisTask = await client.task.createTask(consultationSession.data.id, {
  instructions: 'Analyze the patient\'s HbA1c trends and medication adherence, then provide specific recommendations.',
  model: 'medgemma-27b'
});

Radiology Workflow Session

// Create a session for radiology analysis
const radiologySession = await client.session.createSession({
  workerId: 'radiology-assistant',
  metadata: {
    studyId: 'study-789',
    modality: 'CT',
    bodyPart: 'chest'
  }
});

// Run image analysis task
const analysisTask = await client.task.createTask(radiologySession.data.id, {
  instructions: 'Analyze the CT scan for pulmonary nodules and provide a structured report.',
  model: 'medgemma-27b',
  additionalMessages: [{
    role: 'user',
    content: 'Focus on nodule size, location, and characteristics. Include follow-up recommendations.'
  }]
});

Next Steps

• Sessions & Tasks API Reference - Complete API documentation
• AI Workers Guide - Learn how to create and configure AI Workers
• Knowledge Bases API - Connect AI Workers to your data
• Quick Start Guide - Build your first healthcare AI application