Octopus Integration

Integration Direction

WorkDesk embeds Octopus — the integration is one-directional: WorkDesk embeds the Octopus ChatWidget. WorkDesk passes page context as seed data to the widget so the agent is immediately aware of what the employee is looking at.

ChatWidget in WorkDesk Shell

The ChatWidget is mounted once in WorkDeskShell.tsx and persists across page navigation. As the employee navigates between pages, WorkDesk updates the widget's context seed data to reflect the current view:

// WorkDeskShell.tsx — Octopus ChatWidget integration
import { ChatWidget } from '@bizfirstai/octopus-react';
import { useOctopusContext } from './hooks/useOctopusContext';

export function WorkDeskShell() {
  const { agentId, seedData } = useOctopusContext(); // context changes per page

  return (
    <div className="shell">
      <WorkDeskNav />
      <main>
        <Outlet />  {/* React Router page content */}
      </main>

      <ChatWidget
        agentId={agentId}             // configured per WorkDesk deployment
        seedData={seedData}           // current-page context (task, execution, etc.)
        theme="dark"
        position="bottom-right"
        initiallyOpen={false}
        locale={userLocale}
      />
    </div>
  );
}

Context-Aware Seed Data

The useOctopusContext hook builds seed data based on the current route. The agent receives relevant context without the employee needing to explain what they're looking at:

// useOctopusContext.ts — builds seed data per page
export function useOctopusContext(): OctopusContextData {
  const location = useLocation();
  const { taskId } = useParams();
  const task = useTaskStore(s => s.activeTask);
  const execution = useHistoryStore(s => s.activeExecution);

  return useMemo(() => {
    // Task inbox — active task page
    if (location.pathname.startsWith('/tasks/') && task) {
      return {
        agentId: OCTOPUS_AGENT_ID,
        seedData: {
          context: 'hil_task',
          taskId:       task.id,
          taskType:     task.type,         // "approval" | "form" | "review"
          taskTitle:    task.title,
          workflowName: task.workflowName,
          dueAt:        task.dueAt,
          // Note: form field values NOT included — privacy boundary
        }
      };
    }

    // Workflow history — execution detail page
    if (location.pathname.startsWith('/history/') && execution) {
      return {
        agentId: OCTOPUS_AGENT_ID,
        seedData: {
          context:      'execution_history',
          executionId:  execution.id,
          workflowName: execution.workflowName,
          status:       execution.status,
          triggeredAt:  execution.triggeredAt,
        }
      };
    }

    // Dashboard / default
    return {
      agentId: OCTOPUS_AGENT_ID,
      seedData: { context: 'workdesk_home' }
    };
  }, [location.pathname, task, execution]);
}

What the Agent Can Help With

The Octopus agent configured for WorkDesk has access to the following capabilities based on the context seed:

Privacy Boundaries

WorkDesk enforces strict privacy boundaries on what data is passed to the Octopus agent:

Agent Configuration

The Octopus agent used in WorkDesk is configured in the Octopus admin console and identified by agentId. Platform engineers can configure:

• Which knowledge bases the agent has access to (e.g., company policy documents, workflow descriptions)
• What tools/actions the agent can perform (read-only queries, or active assistance like starting a new workflow)
• The agent's personality and response style (formal vs. conversational)
• Language and locale support

// WorkDesk environment configuration
NEXT_PUBLIC_OCTOPUS_AGENT_ID=agt-workdesk-assistant-prod
NEXT_PUBLIC_OCTOPUS_ENDPOINT=https://octopus.bizfirstai.com

// ChatWidget picks up agent config from Octopus via agentId
// No additional configuration needed in WorkDesk code

ChatWidget Lifecycle