@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

$3

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 (


`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

$3

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; // 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;
startNewChat: () => Promise;
endChat: () => void;
resetChat: () => void;
disconnect: (intentional?: boolean) => void;

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

// Metadata
metadata: Record;
updateMetadata: (updates: Record) => void;
clearMetadata: () => void;

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

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

$3

Hook for WebSocket chat functionality only.

See detailed API documentation in TypeScript definitions.

$3

Hook for client-side tool execution only.

See detailed API documentation in TypeScript definitions.

Examples

$3

`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 (


`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 (


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

// Type-safe tool handlers
const tools: Record = {
'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

$3

`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');
`

$3

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

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

// Clear all metadata
clearMetadata();
`

$3

`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)