Site Operator (Core)

The core Web Component library for Site Operator. It provides the <agent-chat> custom element and the chatPortalService.

This package is framework-agnostic and built with Lit.

Installation

npm install site-operator

Chat Portal API

The Chat Portal API is the bridge that allows the AI Agent to understand and interact with your application. It consists of two main parts:

1. AppContext: Static definition of your site (routes, users, global actions).
2. AppState: Dynamic definition of the current state (current URL, visible buttons, active focus).

Example: Defining your Application Context

import { chatPortalService, type AppContext } from 'site-operator';

const myAppContext: AppContext = {
  v: "1.1",
  site: { 
    name: "Dali CRM", 
    description: "Main sales and lead management portal",
    deployment: "prod",
    locale: "en-US" 
  },
  nav: {
    routes: [
      {
        id: "leads.list",
        name: "Leads List",
        path: "/leads",
        title: "Sales Leads",
        description: "Standard view for managing and filtering sales leads",
        keywords: ["leads", "prospects", "sales"],
        clickTargets: [
          {
            id: "btn.newLead",
            name: "Create New Lead",
            label: "New Lead",
            description: "Opens the lead creation form",
            kind: "button",
            locator: { testId: "create-lead-btn" },
            action: { type: "open", targetId: "LeadCreateModal" }
          }
        ]
      }
    ],
    globalClickTargets: [
      {
        id: "nav.dashboard",
        name: "Dashboard",
        label: "Home",
        kind: "link",
        action: { type: "navigate", toPath: "/dashboard" }
      }
    ]
  }
};

// Register the portal so the agent knows about it
chatPortalService.registerPortal(myAppContext);

Example: Updating Dynamic State

import { chatService, type AppState } from 'site-operator';

const currentState: AppState = {
  v: "1.1",
  location: {
    path: "/leads?status=new",
    title: "New Leads",
    params: { status: "new" }
  },
  ui: {
    // Tell the agent exactly which buttons are visible on the screen right now
    visibleClickTargetIds: ["btn.newLead", "nav.dashboard"]
  },
  focus: {
    type: "lead",
    id: "lead_123",
    label: "John Doe"
  }
};

chatService.setAppState(currentState);

Using the Web Component

<script type="module" src="node_modules/site-operator/dist/site-operator.es.js"></script>

<agent-chat
  backend-url="https://your-api.com/ag_ui"
  app-name="Dali CRM"
  inspector="true"
></agent-chat>

<script>
  const chat = document.querySelector('agent-chat');
  // You can also set context/state directly on the element
  chat.setAppContext(myAppContext);
</script>