SupportAgentService

Kind: Service

Source: atloria-monorepo/apps/api/src/support-agent/support-agent.service.ts

SupportAgentService manages support-agent configuration and agent lifecycle operations, including creating, updating, listing, and deleting support agents. It also provides chat and streaming-chat capabilities while preserving access to conversation history. In the NestJS API, controllers or other backend services use it as the primary integration point for support-agent administration and messaging.

Methods

  versionNumber?: number;
  conversationHistory?: Array<{ role: string; content: string }>;
  sessionId?: string;
})` | `unknown` |  |

| chatStream | chatStream(projectId: string, agentId: string, organizationId: string, message: string, opts: { versionNumber?: number; conversationHistory?: Array<{ role: string; content: string }>; sessionId?: string; }) | unknown | Stream chat response (SSE) Yields chunks as they come from the AI, then saves to history | | getChatHistory | getChatHistory(projectId: string, agentId: string, limit: unknown) | unknown | Get chat history for an agent Returns all messages from active sessions | | clearChatHistory | clearChatHistory(projectId: string, agentId: string) | unknown | Clear chat history for an agent (end current session) | | search | search(projectId: string, organizationId: string, query: string, limit: unknown, docVersionId: string) | unknown | Scoped RAG search for support agent. | | searchAll | searchAll(projectId: string, organizationId: string, query: string, limit: unknown) | unknown | Search all document types for a project — used by the public search bar. |

Dependencies

• PrismaService
• AzureSearchService
• LanguageDetectorService
• AgentAdapterService

Where it refuses work

• SupportAgentService stops the work with NotFoundException when !agent.isEnabled — “Agent not found or disabled”, in 2 places.
• SupportAgentService stops the work with NotFoundException when !project — “Project not found”, in 2 places.
• SupportAgentService stops the work with NotFoundException when existingCount >= MAX_AGENTS_PRO.
• SupportAgentService stops the work with NotFoundException when !agent — “Agent not found”.
• SupportAgentService stops the work with an early return when seen.has(r.id), in 2 places.
• SupportAgentService stops the work with an early return when existing.

When something fails

• SupportAgentService handles failure in 4 places: it logs it and continues in all 4.

Diagram

mermaid
sequenceDiagram
  participant Client
  participant Controller
  participant Service as SupportAgentService
  participant Store as Config/Agent Store
  participant AI as AI Provider

  Client->>Controller: Create agent / send chat message
  Controller->>Service: createAgent() or chat()
  Service->>Store: Load configuration and agent details
  Store-->>Service: Config and agent data

  alt Agent management
    Service->>Store: Persist agent changes
    Store-->>Service: Saved agent
  else Chat request
    Service->>AI: Send context and message
    AI-->>Service: Response or token stream
    Service->>Store: Save chat history
  end

  Service-->>Controller: Result
  Controller-->>Client: API response

Usage

ts
import { Injectable } from '@nestjs/common';
import { SupportAgentService } from './support-agent.service';

@Injectable()
export class SupportController {
  constructor(
    private readonly supportAgentService: SupportAgentService,
  ) {}

  async createAndChat() {
    const agent = await this.supportAgentService.createAgent({
      name: 'Billing Support',
      description: 'Assists customers with invoices and payments.',
    });

    const response = await this.supportAgentService.chat({
      agentId: agent.id,
      message: 'How can I download my latest invoice?',
    });

    return response;
  }

  async getConversation(agentId: string, conversationId: string) {
    return this.supportAgentService.getChatHistory({
      agentId,
      conversationId,
    });
  }
}

AI Coding Instructions

• Keep agent configuration and CRUD operations routed through SupportAgentService; avoid duplicating persistence or validation logic in controllers.
• Load the relevant configuration and agent context before calling chat() or chatStream() so provider requests use the intended agent behavior.
• Use chatStream() for token-by-token responses and ensure the calling controller correctly forwards and closes the stream.
• Preserve conversation identifiers when retrieving or storing history; chat history should remain associated with the correct agent and session.
• Handle missing agents, invalid configuration, and upstream AI-provider failures explicitly when extending service methods.

Relationships

• DEPENDS_ON → PrismaService
• DEPENDS_ON → AzureSearchService
• DEPENDS_ON → LanguageDetectorService
• DEPENDS_ON → AgentAdapterService

Referenced By

• PublicProjectController (DEPENDS_ON)
• SupportAgentController (DEPENDS_ON)
• SupportAgentModule (MODULE_PROVIDES)
• SupportAgentModule (MODULE_EXPORTS)