agent-service.ts

Overview

agent-service.ts is a TypeScript module that acts as a centralized service layer for interacting with various backend API endpoints related to "canvas" entities, agents, templates, logs, and related resources within an application. It abstracts HTTP request details by defining a collection of API methods and then registering them with a server utility (registerNextServer). This file primarily serves as an API client wrapper that simplifies calling backend services by defining consistent method signatures and URLs.

Key responsibilities:

• Define API endpoints and HTTP methods for canvas and agent-related operations.

• Provide typed, reusable service methods for fetching, creating, updating, deleting, and running canvases.

• Export specialized functions for fetching trace data and agent logs.

• Utilize utility modules (api, request, registerNextServer) to handle URL definitions, HTTP calls, and server registration.

Classes, Functions, and Methods

This file does not define any classes but exports a collection of service functions and an agentService object.

1. methods (constant object)

• Purpose: Defines all API endpoints used by the service, associating each with a URL and HTTP method.

• Structure: Each key represents an API action, and each value is an object with:

  • url: The endpoint URL string.

  • method: The HTTP method verb (get or post).

Example entry:

fetchCanvas: {
  url: fetchCanvas,   // imported URL string
  method: 'get',
}

• Usage: Used internally by registerNextServer to create typed request handlers.

2. agentService

• Type: Return type of registerNextServer<keyof typeof methods>

• Purpose: The main exported service object that exposes methods to call backend API endpoints defined in methods.

• Implementation: Created by passing the methods object to registerNextServer, which presumably generates request functions for each method.

• Usage Example:

import agentService from './agent-service';

// Fetch canvas by ID
agentService.fetchCanvas({ id: 'canvas123' }).then(response => {
  console.log(response.data);
});

(Note: Actual parameters depend on how registerNextServer constructs method signatures.)

3. fetchTrace

fetchTrace(data: { canvas_id: string; message_id: string }): Promise<any>

• Purpose: Fetches trace information for a given canvas and message.

• Parameters:

  • data: Object containing:

    • canvas_id: Identifier of the canvas.

    • message_id: Identifier of the message to trace.

• Return: A Promise resolving the HTTP GET response.

• Usage Example:

fetchTrace({ canvas_id: 'canvas123', message_id: 'msg456' })
  .then(response => {
    console.log('Trace data:', response.data);
  });

• Implementation Detail: Uses request.get to call the URL stored in methods.trace.url with the parameters serialized as query params.

4. fetchAgentLogsByCanvasId

fetchAgentLogsByCanvasId(canvasId: string, params: IAgentLogsRequest): Promise<any>

• Purpose: Retrieves agent logs for a specific canvas.

• Parameters:

  • canvasId: The ID of the canvas to fetch logs for.

  • params: An object conforming to IAgentLogsRequest interface (imported from interfaces).

• Return: A Promise resolving to the HTTP GET response.

• Usage Example:

fetchAgentLogsByCanvasId('canvas123', { limit: 10, offset: 0 })
  .then(response => {
    console.log('Agent logs:', response.data);
  });

• Implementation Detail: Calls a URL function methods.fetchAgentLogs.url(canvasId) to generate the endpoint URL dynamically based on canvasId, then passes params as query parameters.

Important Implementation Details

• API URL Management: The URLs for all endpoints are imported from the api module, centralizing URL management.

• HTTP Calls: All requests are made using the request utility, likely wrapping fetch or Axios, providing consistent HTTP handling.

• Typed Server Registration: The registerNextServer function is used to register the API methods, presumably generating type-safe client methods for all endpoints.

• Dynamic URLs: Some URLs are functions that accept parameters (e.g., fetchAgentLogs.url(canvasId)). This allows dynamic URL generation based on runtime arguments.

• Separation of Concerns: This file separates API endpoint definitions (methods) from actual HTTP call implementations (agentService and specialized exported functions).

Interaction with Other Parts of the System

• @/interfaces/database/agent: Provides the IAgentLogsRequest interface, which defines the structure of parameters for log requests.

• @/utils/api: Supplies all backend endpoint URLs and possibly other API-related utilities.

• @/utils/register-server: Provides registerNextServer, a utility to wrap the method definitions into actual callable services.

• @/utils/request: Handles the underlying HTTP client operations (e.g., GET, POST).

• Consumers: Other parts of the frontend application import agentService or the specialized functions to interact with backend services related to canvases, agents, logs, and templates.

Visual Diagram

classDiagram
    class agentService {
        +fetchCanvas()
        +getCanvasSSE()
        +setCanvas()
        +fetchVersionList()
        +fetchVersion()
        +listCanvas()
        +resetCanvas()
        +removeCanvas()
        +runCanvas()
        +listTemplates()
        +testDbConnect()
        +getInputElements()
        +debugSingle()
        +listCanvasTeam()
        +settingCanvas()
        +uploadCanvasFile()
        +trace()
        +inputForm()
        +fetchAgentAvatar()
        +fetchAgentLogs()
        +fetchExternalAgentInputs()
        +fetchPrompt()
    }
    class fetchTrace {
        +fetchTrace(data: {canvas_id:string, message_id:string})
    }
    class fetchAgentLogsByCanvasId {
        +fetchAgentLogsByCanvasId(canvasId:string, params: IAgentLogsRequest)
    }
    agentService ..> methods : uses
    fetchTrace ..> methods.trace : calls
    fetchAgentLogsByCanvasId ..> methods.fetchAgentLogs : calls

Summary

agent-service.ts is a dedicated API client module for managing agent and canvas-related backend interactions. It cleanly abstracts HTTP details behind a set of well-organized methods, supports dynamic URL generation, and exports useful helper functions for fetching trace data and logs. It is a vital part of the frontend's data layer, enabling consistent and type-safe communication with the backend services.

End of Documentation for agent-service.ts