CometChat AG-UI Integration Steps

Step 1: Deploy Your Agent

Before integrating with CometChat, ensure your agent is:

Publicly accessible over HTTPS
Running on a stable server (AWS, Google Cloud, Azure, etc.)
Protected with authentication headers

Step 2: Configure Agent in CometChat Dashboard

Login to CometChat Dashboard
- Navigate to https://app.cometchat.com
- Select your application
Navigate to AI Agents
- Go to AI Agents in the left-hand menu
- Click “Add Agent” or “Custom Agents”
Configure Agent Settings Basic Information:
- Agent Name: Give your agent a memorable name (e.g., “Support Assistant”)
- Provider: Select “Custom” or “AG-UI Compatible”
- Deployment URL: Enter your agent’s public URL
  https://your-domain.com/agent
Agent Identity:
- Display Name: Name shown to users (e.g., “AI Assistant”)
- Avatar: Upload an avatar image for your agent
- Greeting Message: Set a welcome message
  "Hello! I'm your AI assistant. How can I help you today?"

Configure Security Headers CometChat allows you to securely access your agent using custom headers. This is highly recommended for production. Headers Configuration (JSON format):

{
  "Authorization": "Bearer your-secret-api-key",
  "X-API-Key": "your-custom-api-key",
  "X-Client-ID": "cometchat-client"
}

Example with Basic Auth:

{
  "Authorization": "Basic base64-encoded-credentials"
}

Enable the Agent
- Toggle the agent status to “Enabled”
- Click “Save”

Step 3: Implement Header Validation in Your Agent

Express.js Example:

import express from 'express';

const app = express();

// Middleware to validate headers
app.use('/agent', (req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  const expectedKey = process.env.API_KEY;
  
  if (apiKey !== expectedKey) {
    return res.status(401).json({
      error: 'Unauthorized',
      message: 'Invalid API key'
    });
  }
  
  next();
});

// Your agent endpoint
app.post('/agent', async (req, res) => {
  // Agent logic here
});

NestJS Example:

import { Injectable, NestMiddleware, UnauthorizedException } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  constructor(private configService: ConfigService) {}
  
  use(req: Request, res: Response, next: NextFunction) {
    const apiKey = req.headers['x-api-key'];
    const expectedKey = this.configService.get('API_KEY');
    
    if (apiKey !== expectedKey) {
      throw new UnauthorizedException('Invalid API key');
    }
    
    next();
  }
}

// In your module:
export class AgentModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(AuthMiddleware)
      .forRoutes('agent');
  }
}

Step 4: Test Integration

Access CometChat in your app
Start a conversation with your AI agent
Send a message and verify the agent responds correctly
Check streaming - messages should appear token-by-token
Test tools - if your agent uses tools, verify they execute properly

Step 5: Monitor and Debug

Check Agent Logs:

// Add logging to your agent
console.log('Received request:', {
  threadId: input.threadId,
  runId: input.runId,
  messageCount: input.messages.length,
  toolCount: input.tools.length
});

CometChat Analytics:

Navigate to Analytics in CometChat dashboard
Monitor agent performance, response times, and error rates

Best Practices and Security

Security Best Practices

1. Use HTTPS

Always deploy your agent with HTTPS. Never expose HTTP endpoints in production.

2. Implement Authentication

Use strong authentication headers:

// Environment variables
API_KEY=your-strong-random-key-here
CLIENT_SECRET=another-strong-secret

// Validate in your agent
const validateAuth = (req: Request): boolean => {
  const apiKey = req.headers['x-api-key'];
  const clientId = req.headers['x-client-id'];
  
  return apiKey === process.env.API_KEY && 
         clientId === process.env.CLIENT_ID;
};

3. Rate Limiting

Implement rate limiting to prevent abuse:

import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per windowMs
  message: 'Too many requests, please try again later.'
});

app.use('/agent', limiter);

4. Input Validation

Validate all inputs:

import { IsString, IsArray, ValidateNested } from 'class-validator';

export class RunAgentInputDto {
  @IsString()
  threadId: string;
  
  @IsString()
  runId: string;
  
  @IsArray()
  @ValidateNested({ each: true })
  messages: Message[];
  
  // ... other validations
}

5. Error Handling

Never expose sensitive information in errors:

try {
  // Agent logic
} catch (error) {
  console.error('Internal error:', error); // Log internally
  
  // Return generic error to client
  res.write(encoder.encode({
    type: EventType.RUN_ERROR,
    message: 'An unexpected error occurred. Please try again.'
  }));
}

Performance Best Practices

1. Streaming Optimization

Stream responses as soon as possible:

// Good: Start streaming immediately
res.write(encoder.encode({ type: EventType.RUN_STARTED }));

// Bad: Wait for all processing before streaming
// processEverything().then(() => startStreaming());

2. Connection Management

Handle client disconnections gracefully:

app.post('/agent', async (req, res) => {
  let isCancelled = false;
  
  req.on('close', () => {
    isCancelled = true;
    console.log('Client disconnected');
  });
  
  // Check cancellation in your loops
  for await (const chunk of stream) {
    if (isCancelled) break;
    res.write(encoder.encode(chunk));
  }
});

3. Timeout Configuration

Set appropriate timeouts:

const server = app.listen(port);
server.timeout = 300000; // 5 minutes
server.keepAliveTimeout = 65000; // 65 seconds

4. Memory Management

Clean up resources properly:

try {
  // Process stream
  for await (const chunk of stream) {
    // ...
  }
} finally {
  // Clean up resources
  stream.destroy();
  res.end();
}

Development Best Practices

1. Environment Variables

Use environment variables for all sensitive data:

# .env
OPENAI_API_KEY=sk-...
API_KEY=your-secret-key
PORT=8000
NODE_ENV=production

2. TypeScript Strict Mode

Enable strict TypeScript checking:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true
  }
}

3. Logging

Implement structured logging:

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

logger.info('Agent request received', {
  threadId: input.threadId,
  messageCount: input.messages.length
});

4. Testing

Write tests for your agent:

import request from 'supertest';
import app from './server';

describe('AG-UI Agent', () => {
  it('should respond with RUN_STARTED event', async () => {
    const response = await request(app)
      .post('/agent')
      .send({
        threadId: 'test_123',
        runId: 'run_456',
        messages: [{ id: '1', role: 'user', content: 'Hello' }],
        tools: [],
        context: [],
        state: {},
        forwardedProps: {}
      });
    
    expect(response.status).toBe(200);
    expect(response.text).toContain('RUN_STARTED');
  });
});

Deployment Checklist

Conclusion

You now have a comprehensive understanding of:

AG-UI Protocol - Event types, message formats, and patterns
CometChat Integration - “Bring Your Own Agent” approach
Agent Implementation - Complete Express.js and NestJS examples
Security & Best Practices - Production-ready configurations

Your AG-UI compatible agent can now be seamlessly integrated with CometChat, providing a powerful, self-served AI agent experience with full control over your agent logic while benefiting from CometChat’s production-ready chat infrastructure.

Additional Resources

AG-UI Documentation: https://docs.ag-ui.com
CometChat Documentation: https://www.cometchat.com/docs
AG-UI GitHub: https://github.com/ag-ui-protocol/ag-ui
CometChat Dashboard: https://app.cometchat.com

Happy Building! 🚀

​Step 1: Deploy Your Agent

​Step 2: Configure Agent in CometChat Dashboard

​Step 3: Implement Header Validation in Your Agent

​Step 4: Test Integration

​Step 5: Monitor and Debug

​Best Practices and Security

​Security Best Practices

​1. Use HTTPS

​2. Implement Authentication

​3. Rate Limiting

​4. Input Validation

​5. Error Handling

​Performance Best Practices

​1. Streaming Optimization

​2. Connection Management

​3. Timeout Configuration

​4. Memory Management

​Development Best Practices

​1. Environment Variables

​2. TypeScript Strict Mode

​3. Logging

​4. Testing

​Deployment Checklist

​Conclusion

​Additional Resources