@aiia/agui-sdk

AG-UI Streaming SDK for AIIA client applications.

Overview

This SDK provides a platform-agnostic client for consuming AG-UI Server-Sent Events (SSE) streams. It works with:

• Web Apps: React, Vue, Angular, vanilla JavaScript
• Mobile Apps: React Native (iOS & Android)
• Node.js: Server-side streaming consumption

Installation

npm install @aiia/agui-sdk
# or
yarn add @aiia/agui-sdk
# or
pnpm add @aiia/agui-sdk

Usage

Basic Client (Platform-Agnostic)

import { AGUIClient, createAGUIClient } from '@aiia/agui-sdk';

const client = createAGUIClient({
  baseUrl: 'https://api.aiia.io',
  token: 'your-bearer-token',
  tenantId: 'your-tenant-id', // optional
  clientId: 'your-client-id', // optional
});

// Set up event handlers
client.setHandlers({
  onLifecycle: (event) => {
    console.log(`Status: ${event.status}, Step: ${event.step}/${event.total_steps}`);
  },
  onTextDelta: (event) => {
    process.stdout.write(event.content); // Streaming text
  },
  onToolCall: (event) => {
    console.log(`Tool ${event.tool_name}: ${event.status}`);
  },
  onResult: (event) => {
    console.log('Result:', event.data);
  },
  onError: (event) => {
    console.error(`Error: ${event.error_message}`);
  },
});

// Start streaming
await client.stream('Show me the profit and loss report');

React Hook

import { useAGUIStream } from '@aiia/agui-sdk/react';

function ChatComponent() {
  const {
    isStreaming,
    isConnecting,
    status,
    step,
    totalSteps,
    text,
    toolCalls,
    result,
    error,
    stream,
    abort,
    reset,
  } = useAGUIStream({
    baseUrl: 'https://api.aiia.io',
    token: authToken,
  });

  const handleSubmit = async (query: string) => {
    await stream(query);
  };

  return (
    <div>
      {isConnecting && <p>Connecting...</p>}

      {isStreaming && (
        <div>
          <p>Step {step} of {totalSteps}: {status}</p>
          <button onClick={abort}>Cancel</button>
        </div>
      )}

      {text && <p>{text}</p>}

      {toolCalls.map((tc) => (
        <div key={tc.name}>
          {tc.name}: {tc.status}
          {tc.duration && ` (${tc.duration}ms)`}
        </div>
      ))}

      {error && <p className="error">{error.message}</p>}
    </div>
  );
}

React Native

The SDK works with React Native using the same API:

import { useAGUIStream } from '@aiia/agui-sdk/react';
import { View, Text, Button, ActivityIndicator } from 'react-native';

function AIAssistant() {
  const { isStreaming, text, stream, abort } = useAGUIStream({
    baseUrl: 'https://api.aiia.io',
    token: authToken,
  });

  return (
    <View>
      {isStreaming && <ActivityIndicator />}
      <Text>{text}</Text>
      <Button title="Ask" onPress={() => stream('What are my expenses?')} />
      <Button title="Cancel" onPress={abort} disabled={!isStreaming} />
    </View>
  );
}

Event Types

Lifecycle Events

interface LifecycleEvent {
  type: 'lifecycle';
  status: 'started' | 'parsing' | 'intent_found' | 'routing' | 'executing' | 'completed' | 'error';
  step?: number;
  total_steps?: number;
}

Text Delta Events

interface TextDeltaEvent {
  type: 'text_delta';
  content: string;
  content_type: 'text' | 'markdown' | 'code';
  is_complete: boolean;
}

Tool Call Events

interface ToolCallEvent {
  type: 'tool_call';
  tool_name: string;
  status: 'started' | 'completed' | 'error';
  duration_ms?: number;
  error_message?: string;
}

Result Events

interface ResultEvent {
  type: 'result';
  success: boolean;
  data?: unknown;
  bob_name?: string;
  execution_time_ms?: number;
}

Error Events

interface ErrorEvent {
  type: 'error';
  error_code: string;
  error_message: string;
  recoverable: boolean;
  suggestions?: string[];
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | required | API base URL | | token | string | required | Bearer authentication token | | tenantId | string | optional | Tenant ID for multi-tenant | | clientId | string | optional | Client ID for multi-tenant | | maxRetries | number | 3 | Max reconnection attempts | | retryDelayMs | number | 1000 | Base delay for backoff | | timeoutMs | number | 30000 | Connection timeout | | debug | boolean | false | Enable debug logging |

Features

• Automatic Reconnection: Exponential backoff with configurable retries
• Event Replay: Uses Last-Event-ID header for missed event recovery
• Multi-Tenant Support: Tenant and client ID headers
• Type-Safe: Full TypeScript support with comprehensive types
• Platform-Agnostic: Works in browser, Node.js, and React Native

Publishing

To publish to npm:

# Login to npm (one-time)
npm login

# Build and publish
npm run build
npm publish --access public

For scoped packages, ensure the package name is @aiia/agui-sdk and use --access public for public packages.

License

MIT