Axess AI JavaScript SDK

A JavaScript/TypeScript SDK for interacting with the Axess AI event system.

Installation

npm install @axessai/sdk
# or
yarn add @axessai/sdk

Usage

Initialize the SDK

import { AxessSDK } from "@axessai/sdk";

// Initialize with required API key
const axess = new AxessSDK({
  apiKey: "your-api-key",
  // Optional configuration
  apiUrl: "https://custom-api-url.com", // Custom API URL if needed
  timeout: 15000, // Custom timeout in milliseconds
});

Or use the factory function:

import { createAxessSDK } from "@axessai/sdk";

const axess = createAxessSDK({
  apiKey: "your-api-key",
});

Sending Events

Send events to your Axess AI system:

// Send a task:start event
await axess.sendEvent("task:start", {
  agentId: "agent-123", // The agentId is required in every event
  taskId: "task-456",
  title: "Process document",
  description: "Extract information from the uploaded document",
  input: {
    prompt: "Extract the main topics from this document",
    artifacts: [
      {
        id: "doc-1",
        type: "document",
        url: "https://example.com/document.pdf",
        name: "Financial Report.pdf",
      },
    ],
  },
});

// Send a task:complete event
await axess.sendEvent("task:complete", {
  agentId: "agent-123", // The agentId is required in every event
  taskId: "task-456",
  output: {
    response: "Document processing complete. Found 3 main topics.",
    artifacts: [
      {
        id: "result-1",
        type: "json",
        url: "https://example.com/results.json",
        name: "extraction_results.json",
      },
    ],
  },
  tokenUsage: {
    totalTokens: 1500,
    promptTokens: 500,
    completionTokens: 1000,
  },
});

TypeScript Support

The SDK includes full TypeScript support with type definitions for all event types:

import { AgentEventName, AgentEventSchemaType } from "@axessai/sdk";

// Type-safe event data
function processEvent<T extends AgentEventName>(
  eventName: T,
  data: AgentEventSchemaType<T>
) {
  // Process event...
}

Get Available Event Types

// Get all available event types
const eventTypes = axess.getEventTypes();
console.log(eventTypes);
// ['task:queued', 'task:start', 'task:complete', ...]

Error Handling

The SDK will validate events before sending them and throw errors for invalid events:

try {
  await axess.sendEvent("task:start", {
    /* ... */
  });
} catch (error) {
  console.error("Failed to send event:", error.message);
}

Type Synchronization

This SDK automatically synchronizes event type definitions from the main Axess AI application. This ensures that:

1. The SDK and the main application always use the same event types
2. When new event types are added to the main application, they are automatically available in the SDK

For developers working on the SDK:

• Event types are defined in src/generated/ directory
• These files are automatically generated and should not be edited directly
• To update types, run npm run sync-types or build the SDK with npm run build
• Generated files are excluded from Git to avoid merge conflicts

API Reference

AxessSDK Class

Constructor

• constructor(options: AxessSDKOptions) - Create a new SDK instance

Methods

• sendEvent<T extends AgentEventName>(eventName: T, eventData: AgentEventSchemaType<T>, options?: SendEventOptions): Promise<any> - Send an event
• getEventTypes(): AgentEventName[] - Get all available event types

Events

The SDK supports the following events:

• Task Events: task:queued, task:start, task:complete, task:failure, task:feedback
• Action Events: task:action:queued, task:action:start, task:action:complete, task:action:failure
• Intervention Events: task:action:intervention:requested, task:action:intervention:start, task:action:intervention:complete
• Escalation Events: task:action:escalation:requested, task:action:escalation:start, task:action:escalation:handled

License

ISC