← Documentation Home

Agent Chat Developer Guide

Overview

Package: @bluefly/agent-chat Version: Latest License: MIT

Enterprise-grade AI chat interface with multi-model routing and deep LLM Platform integration. LibreChat-compatible API with native support for Claude, GPT-4, Mistral, and Gemini.

Key Features

Installation

npm install @bluefly/agent-chat

Quick Start

Start Chat Server

# Development mode
npm run dev

# Production mode
npm run build
npm start

Access at http://localhost:3080

CLI Usage

# Start development environment
agent-chat dev

# Check system health
agent-chat health

# Manage users
agent-chat users list
agent-chat users create --email user@company.com --role admin

API Reference

LibreChat-Compatible Endpoints

POST /api/chat/completions

Create chat completion.

Request:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

Response:

{
  "id": "chatcmpl-123",
  "model": "claude-3-5-sonnet-20241022",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    }
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

POST /api/chat/stream

Streaming chat completion.

GET /api/conversations

List user conversations.

GET /api/conversations/:id

Get specific conversation with all messages.

DELETE /api/conversations/:id

Delete conversation.

Platform-Specific Endpoints

POST /api/search

Vector search across conversations:

const results = await fetch('/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'How do I deploy agents?',
    topK: 5,
    includeContext: true
  })
});

POST /api/buildkit

BuildKit integration for CLI operations:

await fetch('/api/buildkit', {
  method: 'POST',
  body: JSON.stringify({
    command: 'agents list',
    namespace: 'production'
  })
});

POST /api/agents/orchestrate

Orchestrate multi-agent conversations:

await fetch('/api/agents/orchestrate', {
  method: 'POST',
  body: JSON.stringify({
    agents: ['researcher', 'writer', 'reviewer'],
    task: 'Create comprehensive analysis of quantum computing',
    workflow: 'sequential'
  })
});

Configuration

Environment Variables

# Chat Service
AGENT_CHAT_PORT=3080
AGENT_CHAT_HOST=0.0.0.0

# LibreChat Compatibility
LIBRECHAT_URL=http://localhost:3080
LIBRECHAT_API_KEY=your-api-key

# Database
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB_NAME=agent_chat
REDIS_URL=redis://localhost:6379

# LLM Platform Integration
LLM_GATEWAY_URL=http://localhost:4000
VECTOR_HUB_URL=http://localhost:6333
AGENT_MESH_URL=http://localhost:3005

# Observability
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PROMETHEUS_PORT=9090
JAEGER_ENDPOINT=http://localhost:14268/api/traces

# Authentication
JWT_SECRET=~/.tokens/jwt-secret
SESSION_TIMEOUT=3600

# MCP Server
MCP_SERVER_ENABLED=true
MCP_SERVER_PORT=3001

Configuration File

config/agent-chat.yaml:

chat:
  maxTokens: 4096
  temperature: 0.7
  streaming: true

models:
  preferred:
    - claude-3-5-sonnet-20241022
    - gpt-4-turbo
  fallback:
    - gpt-3.5-turbo

vectorSearch:
  enabled: true
  topK: 5
  minScore: 0.7

ossa:
  enabled: true
  agentDiscovery: true

Examples

Multi-Model Chat

import { AgentChat } from '@bluefly/agent-chat';

const chat = new AgentChat({
  apiUrl: 'http://localhost:3080',
  apiKey: 'your-api-key'
});

// Automatic model selection
const response = await chat.complete({
  messages: [
    { role: 'user', content: 'Explain quantum entanglement' }
  ],
  // Model auto-selected based on routing strategy
  temperature: 0.7,
  maxTokens: 1000
});

console.log(response.choices[0].message.content);

Streaming Responses

const stream = await chat.stream({
  messages: [
    { role: 'user', content: 'Write a detailed analysis of AI trends' }
  ]
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content);
}

Conversation History

// List conversations
const conversations = await chat.listConversations({
  limit: 10,
  offset: 0
});

// Get conversation with messages
const conversation = await chat.getConversation(conversations[0].id);

// Export to markdown
const markdown = await chat.exportConversation(conversation.id, {
  format: 'markdown',
  includeMetadata: true
});

// Search across all conversations
const results = await chat.searchConversations({
  query: 'kubernetes deployment strategies',
  topK: 5,
  filters: {
    dateRange: {
      start: '2025-01-01',
      end: '2025-01-31'
    },
    models: ['claude-3-5-sonnet-20241022']
  }
});

MCP Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-chat": {
      "command": "node",
      "args": ["/path/to/agent-chat/dist/mcp-server.js"],
      "env": {
        "AGENT_CHAT_URL": "http://localhost:3080",
        "AGENT_CHAT_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

GraphQL API

query GetConversations {
  conversations(limit: 10) {
    id
    title
    createdAt
    messages {
      id
      role
      content
      model
    }
  }
}

mutation SendMessage($input: MessageInput!) {
  sendMessage(input: $input) {
    id
    content
    model
    usage {
      promptTokens
      completionTokens
      totalTokens
    }
  }
}

Observability

Phoenix Arize

# View AI traces
open http://localhost:6006

# Monitor chat performance
curl http://localhost:3080/api/observability/phoenix

Prometheus Metrics

# Export metrics
curl http://localhost:9090/metrics

# Key metrics:
# - agent_chat_requests_total
# - agent_chat_tokens_used
# - agent_chat_latency_seconds
# - agent_chat_active_users

Testing

# Unit tests
npm test

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# Coverage
npm run test:coverage

Deployment

Kubernetes

# Deploy
kubectl apply -f infrastructure/kubernetes/ -n agent-chat

# Check status
kubectl get pods -n agent-chat

Docker

# Build and run
docker build -t bluefly/agent-chat:latest .
docker run -d -p 3080:3080 \
  -e MONGODB_URL=mongodb://mongo:27017 \
  bluefly/agent-chat:latest

Documentation