@elqnt/agent-sdk 1.0.0

package/README.md

@@ -0,0 +1,401 @@
+# @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
+
+```bash
+npm install @eloquent/agent-sdk
+```
+
+## Quick Start
+
+### Option 1: All-in-One Hook (Recommended)
+
+The `useAgent` hook provides everything you need in one place:
+
+```tsx
+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: 'user@example.com',
+    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
+
+```tsx
+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: 'user@example.com'
+  });
+
+  useEffect(() => {
+    startNewChat();
+  }, []);
+
+  return (
+    // Your UI
+  );
+}
+```
+
+#### Tool Execution
+
+```tsx
+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
+
+```typescript
+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
+
+```typescript
+{
+  // 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
+
+```tsx
+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: 'customer@example.com',
+    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
+
+```tsx
+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: 'user@example.com',
+    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:
+
+```typescript
+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: 'user@example.com',
+  tools
+});
+
+// All properties are fully typed
+agent.messages.forEach(msg => {
+  console.log(msg.content); // ✅ TypeScript knows the structure
+});
+```
+
+## Advanced Usage
+
+### Custom Tool Handlers
+
+```tsx
+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
+
+```tsx
+const { metadata, updateMetadata, clearMetadata } = useAgent({
+  // ... config
+});
+
+// Update metadata
+updateMetadata({
+  selectedProduct: product,
+  cartItems: [...metadata.cartItems, newItem]
+});
+
+// Clear all metadata
+clearMetadata();
+```
+
+### Analytics Tracking
+
+```tsx
+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)