@eloquent/agent-sdk

Build custom AI agent UIs with ease. The Eloquent Agent SDK provides a developer-friendly framework for creating agent interfaces, from simple chat widgets to complex custom implementations.

Features

✅ Phase 1: Foundation (Available Now)

• 🎯 Core hooks for agent interaction
• 💬 WebSocket-based real-time chat
• 🔧 Client-side tool execution
• 📊 Metadata management
• 🎭 TypeScript-first with full type safety
• 📝 Comprehensive JSDoc documentation

🚧 Coming Soon

• Phase 2: React component library
• Phase 3: Pre-built widgets
• Phase 4: CLI tools and templates
• Phase 5: Visual builder and developer portal

Installation

npm install @eloquent/agent-sdk

Quick Start

Option 1: All-in-One Hook (Recommended)

The useAgent hook provides everything you need in one place:

import { useAgent } from '@eloquent/agent-sdk';

function MyAgentUI() {
  const {
    messages,
    sendMessage,
    isConnected,
    isWaiting,
    executeClientTool,
    metadata,
    updateMetadata
  } = useAgent({
    agentId: 'your-agent-id',
    orgId: 'your-org-id',
    serverBaseUrl: 'wss://chat.example.com',
    userEmail: '[email protected]',
    tools: {
      'search_products': async (params) => {
        const results = await api.search(params.query);
        return { products: results };
      }
    }
  });

  return (
    <div>
      <div className="messages">
        {messages.map(msg => (
          <div key={msg.id}>{msg.content}</div>
        ))}
      </div>

      <input
        onKeyPress={(e) => {
          if (e.key === 'Enter') {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
        disabled={!isConnected}
      />

      {isWaiting && <div>Agent is typing...</div>}
    </div>
  );
}

Option 2: Individual Hooks

For more control, use hooks separately:

Chat Functionality

import { useAgentChat } from '@eloquent/agent-sdk';

function ChatComponent() {
  const {
    messages,
    sendMessage,
    isConnected,
    startNewChat
  } = useAgentChat({
    agentId: 'your-agent-id',
    orgId: 'your-org-id',
    serverBaseUrl: 'wss://chat.example.com',
    userEmail: '[email protected]'
  });

  useEffect(() => {
    startNewChat();
  }, []);

  return (
    // Your UI
  );
}

Tool Execution

import { useAgentTools } from '@eloquent/agent-sdk';

function ToolsComponent() {
  const { executeClientTool, registerTool } = useAgentTools({
    tools: {
      'track_order': async ({ orderId }) => {
        const order = await api.getOrder(orderId);
        return { status: order.status };
      }
    },
    onToolExecuted: (toolName, result) => {
      console.log(`Tool ${toolName} executed:`, result);
    }
  });

  return (
    // Your UI
  );
}

API Reference

useAgent(config)

All-in-one hook for complete agent interaction.

Configuration

interface UseAgentConfig {
  agentId: string;                    // Required: Agent ID
  orgId: string;                      // Required: Organization ID
  serverBaseUrl: string;              // Required: WebSocket server URL
  userEmail: string;                  // Required: User identifier
  tools?: ToolHandlers;               // Optional: Client-side tool handlers
  initialMetadata?: Record<string, any>; // Optional: Initial metadata
  features?: AgentFeatures;           // Optional: Feature flags
  onMessage?: (event: ChatEvent) => void;
  onConnect?: () => void;
  onDisconnect?: () => void;
  onToolCall?: (toolName: string, params: any) => void;
  onCSATSubmit?: (response: any) => void;
  autoReconnect?: boolean;            // Default: true
  debug?: boolean;                    // Default: false
}

Returns

{
  // Agent info
  agent: Agent | undefined;

  // Chat state
  messages: ChatMessage[];
  currentChat: Chat | undefined;
  users: ChatUser[];
  isConnected: boolean;
  isWaiting: boolean;
  chatKey: string | undefined;
  error: AgentError | undefined;

  // Chat actions
  sendMessage: (content: string) => Promise<void>;
  startNewChat: () => Promise<void>;
  endChat: () => void;
  resetChat: () => void;
  disconnect: (intentional?: boolean) => void;

  // Tools
  tools: Record<string, Tool>;
  executeClientTool: (toolName: string, params: any) => Promise<any>;
  registerTool: (toolName: string, handler: ToolHandler) => void;
  unregisterTool: (toolName: string) => void;

  // Metadata
  metadata: Record<string, any>;
  updateMetadata: (updates: Record<string, any>) => void;
  clearMetadata: () => void;

  // CSAT
  csatSurvey: CSATSurvey | undefined;
  submitCSATResponse: (response: any) => void;
  dismissCSAT: () => void;

  // Analytics
  logEvent: (eventData: any) => Promise<void>;
}

useAgentChat(config)

Hook for WebSocket chat functionality only.

See detailed API documentation in TypeScript definitions.

useAgentTools(config)

Hook for client-side tool execution only.

See detailed API documentation in TypeScript definitions.

Examples

E-commerce Shopping Assistant

import { useAgent } from '@eloquent/agent-sdk';

function ShoppingAssistant() {
  const {
    messages,
    sendMessage,
    metadata,
    updateMetadata,
    executeClientTool
  } = useAgent({
    agentId: 'shopping-agent',
    orgId: 'my-store',
    serverBaseUrl: 'wss://chat.mystore.com',
    userEmail: '[email protected]',
    tools: {
      'add_to_cart': async ({ productId }) => {
        const product = await api.getProduct(productId);
        updateMetadata({
          cart: [...(metadata.cart || []), product]
        });
        return { success: true };
      },
      'search_products': async ({ query }) => {
        const results = await api.search(query);
        return { products: results };
      }
    }
  });

  return (
    <div className="shopping-assistant">
      {/* Your shopping assistant UI */}
    </div>
  );
}

Customer Support

import { useAgent } from '@eloquent/agent-sdk';

function SupportChat() {
  const {
    messages,
    sendMessage,
    csatSurvey,
    submitCSATResponse
  } = useAgent({
    agentId: 'support-agent',
    orgId: 'my-company',
    serverBaseUrl: 'wss://support.mycompany.com',
    userEmail: '[email protected]',
    features: {
      csat: true,
      handoff: true
    }
  });

  return (
    <div className="support-chat">
      {/* Chat UI */}

      {csatSurvey && (
        <CSATForm
          survey={csatSurvey}
          onSubmit={submitCSATResponse}
        />
      )}
    </div>
  );
}

TypeScript Support

The SDK is written in TypeScript and provides full type safety:

import { useAgent, ToolHandler } from '@eloquent/agent-sdk';

// Type-safe tool handlers
const tools: Record<string, ToolHandler> = {
  'search': async (params: { query: string }) => {
    return { results: [] };
  }
};

const agent = useAgent({
  agentId: 'my-agent',
  orgId: 'my-org',
  serverBaseUrl: 'wss://...',
  userEmail: '[email protected]',
  tools
});

// All properties are fully typed
agent.messages.forEach(msg => {
  console.log(msg.content); // ✅ TypeScript knows the structure
});

Advanced Usage

Custom Tool Handlers

const { registerTool, unregisterTool } = useAgentTools();

// Register a tool dynamically
registerTool('custom_analysis', async (params) => {
  const result = await performAnalysis(params);
  return result;
});

// Unregister when no longer needed
unregisterTool('custom_analysis');

Metadata Management

const { metadata, updateMetadata, clearMetadata } = useAgent({
  // ... config
});

// Update metadata
updateMetadata({
  selectedProduct: product,
  cartItems: [...metadata.cartItems, newItem]
});

// Clear all metadata
clearMetadata();

Analytics Tracking

const { logEvent } = useAgent({
  // ... config
  features: {
    analytics: true
  }
});

// Track custom events
await logEvent({
  eventType: 'product_viewed',
  productId: '123',
  source: 'agent_recommendation'
});

Roadmap

• ✅ Phase 1: Foundation - Core hooks and type system
• 🚧 Phase 2: Component Library - Pre-built React components
• 🚧 Phase 3: Widget SDK - Production-ready widgets
• 🚧 Phase 4: CLI & Templates - Developer tools
• 🚧 Phase 5: Developer Portal - Visual builders and docs

Contributing

This is an internal package for the Eloquent platform. For questions or issues, contact the Eloquent team.

License

Proprietary - Eloquent Platform

Documentation

For complete documentation, see:

• Design Document: /docs/agents-sdk.md
• API Reference: TypeScript definitions
• Examples: /examples (coming soon)