Connect your backend.
Keep your architecture.

01 · Install locally

Use the package directly.

During protocol development, reference the checked-out package with a file dependency.

"@omni-agent/protocol": "file:../Omni-Agent/packages/protocol"

02 · Adapter

Describe one provider.

import {
  BackendAuthenticationMethod,
  defineBackendAdapter,
  OMNI_PROTOCOL_VERSION
} from "@omni-agent/protocol";

export default defineBackendAdapter({
  manifest: {
    id: "acme-chat",
    displayName: "Acme Chat",
    channel: "chat",
    protocolVersion: OMNI_PROTOCOL_VERSION,
    authenticationMethods: [BackendAuthenticationMethod.BrowserSSO],
    idleCapabilities: {
      personalBrowser: {
        enabled: true,
        access: {
          mode: "block-all",
          allowList: ["https://*.example.com/*"],
          blockList: []
        }
      }
    }
  },
  async createAuthenticationSession(context) {
    return createAcmeAuthentication(context);
  },
  async connect(context) {
    return createAcmeConnection(context);
  }
});

idleCapabilities describes actions available before a task is active, such as outbound dialing or Omni's managed personal browser. Each active backend may contribute personal-browser URL patterns; Omni combines them while retaining its local block policy. Controls such as hold and disposition are declared separately on each assigned task. Assignments are automatic. A task also carries its channel, wrap time, and any number of named browser URLs. When reuse is false, the browser is never reused. When true, BrowserIsolationScheme decides which definitions reuse the same browser.

03 · Lifecycle

A small, predictable flow.

1. Omni creates the backend authentication session and restores or requests login.
2. After authentication, Omni calls connect() with the signed-in OS agent.
3. Omni subscribes to changes, then reads the current snapshot.
4. requestWork() reports composite capacity; task assignment events are accepted automatically.
5. Break requests remain pending until every provider approves. A provider may deny and suggest a retry time.
6. Task commands carry stable IDs, making retries safe after uncertain network failures.
7. After real-time media ends, Omni starts the task’s fixed wrap timer.
8. After reconnect, the provider republishes one authoritative snapshot so Omni recovers missed work.

04 · Reference pattern

Works naturally with Jema.

Jema’s framework-free design is the reference shape: one client, readable live values, unsubscribe callbacks, promise-based actions, and reconnect hidden in its transport. A Xema adapter maps those values and actions into Omni’s provider-neutral task events. Jema does not need to adopt Omni, and Omni does not depend on SignalR or RxJS.

05 · Verify

Ship a contract test.

import { exerciseAdapter } from "@omni-agent/protocol/testing";

const result = await exerciseAdapter(adapter, {
  agent: { id: "A-102", displayName: "Aarav Sharma" }
});

The test kit checks protocol compatibility and authentication state, connects the adapter, observes its events, reads its state, exercises a capacity signal, and disconnects cleanly.