Abraxas Workflows Frontend

Quick reference for starting and monitoring Abraxas workflows from your React frontend using the useAbraxasWorkflow hook and Timeline component.

useAbraxasWorkflow is just a custom React hook that use the routes defined in back/src/routers/abraxas.py which expose some Abraxas' client operations

How do I start a workflow?

Using the useAbraxasWorkflow hook:

import { useAbraxasWorkflow } from '@/hooks/useAbraxas';
import { AbraxasTimeline } from '@/components/features/abraxas-timeline/Timeline';

export function MyWorkflowComponent() {
  const { start, status, timelineSteps, result, metadata } = useAbraxasWorkflow<MyResultType>('my-workflow-name');

  const handleStartWorkflow = async () => {
    await start({ 
      user_id: 1,
      additional_params: 'value' 
    });
  };

  return (
    <div className="space-y-4">
      <button
        onClick={handleStartWorkflow}
        disabled={status === 'RUNNING'}
        className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
      >
        {status === 'RUNNING' ? 'Running...' : 'Start Workflow'}
      </button>
      
      <AbraxasTimeline steps={timelineSteps} />
      
      {result && (
        <div>
          <h3>Result:</h3>
          <pre>{JSON.stringify(result, null, 2)}</pre>
        </div>
      )}
    </div>
  );
}

How do I display workflow progress?

The AbraxasTimeline component automatically displays progress:

import { AbraxasTimeline } from '@/components/features/abraxas-timeline/Timeline';

// The timeline component takes steps from useAbraxasWorkflow
<AbraxasTimeline steps={timelineSteps} />

The timeline displays:

• RUNNING: Blue color with spinning loader icon
• COMPLETED: Green color with check icon
• FAILED: Red color with X icon

You can edit this component however you want.

How do I handle different workflow statuses?

React to workflow status changes:

// No need to handle a default case, Typescript would raise a type error if we don't handle all status
const mapStatusToColor: Record<Api['WorkflowExecutionStatus'], string> = {
  RUNNING: 'text-blue-600',
  COMPLETED: 'text-green-600',
  FAILED: 'text-red-600',
  CANCELLED: 'text-gray-600',
}

export function WorkflowStatusHandler() {
  const { start, status, timelineSteps, result } = useAbraxasWorkflow('data-processing');

  return (
    <div>
      <div className="mb-4">
        Status: <span className={mapStatusToColor[status]}>{status}</span>
      </div>
      
      <AbraxasTimeline steps={timelineSteps} />
    </div>
  );
}

How do I handle workflow results and metadata?

Access workflow results and execution metadata:

interface TaskResult {
  tasks_created: number;
  task_ids: string[];
  total_time: number;
}

export function TaskCreationWorkflow() {
  const { start, status, result, metadata } = useAbraxasWorkflow<TaskResult>('create-user-tasks');

  const handleCreateTasks = async () => {
    await start({
      user_id: 1,
      task_count: 5,
      category: 'work'
    });
  };

  return (
    <div className="space-y-4">
      <button onClick={handleCreateTasks} disabled={status === 'RUNNING'}>
        {status === 'RUNNING' ? 'Creating Tasks...' : 'Create Tasks'}
      </button>
      
      {result && (
        <div className="grid grid-cols-2 gap-4">
          <div>
            <h3 className="font-bold">Result</h3>
            <div className="bg-gray-50 p-3 rounded">
              <p>Tasks Created: {result.tasks_created}</p>
              <p>Total Time: {result.total_time}s</p>
              <details>
                <summary>Task IDs</summary>
                <ul className="mt-2 text-sm">
                  {result.task_ids.map(id => (
                    <li key={id} className="font-mono">{id}</li>
                  ))}
                </ul>
              </details>
            </div>
          </div>
          
          <div>
            <h3 className="font-bold">Metadata</h3>
            <pre className="bg-gray-50 p-3 rounded text-xs overflow-auto">
              {JSON.stringify(metadata, null, 2)}
            </pre>
          </div>
        </div>
      )}
    </div>
  );
}

Best Practices

1. Handle Loading States: Always disable buttons when status === 'RUNNING'
2. Type Your Results: Use generics with useAbraxasWorkflow<YourResultType>
3. Error Handling: Check for failed status and handle appropriately
4. Input Validation: Validate input data before calling start()