Class AgentOS

AgentOS

Implements

Description

The AgentOS class is the SOTA public-facing service facade for the entire AI agent platform. It provides a unified API for interacting with the system, managing the lifecycle of core components, and orchestrating complex AI interactions. This class ensures that all operations adhere to the defined architectural tenets, including robust error handling, comprehensive documentation, and strict type safety.

Implements

  • IAgentOS

Constructors

constructor

Methods

initialize processRequest handleToolResult listWorkflowDefinitions startWorkflow getWorkflow listWorkflows getWorkflowProgress updateWorkflowStatus applyWorkflowTaskUpdates listAvailablePersonas getConversationHistory receiveFeedback shutdown

Constructors

constructor

  • new AgentOS(logger?): AgentOS

  • Constructs an AgentOS instance. The instance is not operational until initialize() is called and successfully completes.

    Parameters

    Returns AgentOS

Methods

initialize

  • initialize(config): Promise<void>

  • Initializes the AgentOS service and all its core dependencies. This method must be called and successfully awaited before any other operations can be performed on the AgentOS instance. It sets up configurations, instantiates managers, and prepares the system for operation.

    Parameters

    • config: AgentOSConfig

      The comprehensive configuration object for AgentOS.

    Returns Promise<void>

    A promise that resolves when initialization is complete.

    Async

    Throws

    If configuration validation fails or if any critical dependency fails to initialize.

processRequest

  • processRequest(input): AsyncGenerator<AgentOSResponse, void, undefined>

  • Processes a single interaction turn with an AI agent. This is an asynchronous generator that yields AgentOSResponse chunks as they become available.

    This method orchestrates:

    1. Retrieval or creation of a StreamId via the AgentOSOrchestrator.
    2. Registration of a temporary, request-scoped stream client to the StreamingManager.
    3. Yielding of AgentOSResponse chunks received by this client.
    4. Ensuring the temporary client is deregistered upon completion or error.

    The underlying AgentOSOrchestrator handles the GMI interaction and pushes chunks to the StreamingManager. This method acts as the bridge to make these chunks available as an AsyncGenerator to the caller (e.g., an API route handler).

    Parameters

    • input: AgentOSInput

      The comprehensive input for the current interaction turn.

    Returns AsyncGenerator<AgentOSResponse, void, undefined>

    An asynchronous generator that yields response chunks. The generator completes when the interaction is finalized or a terminal error occurs.

    Async

    Generator

    Yields

    Chunks of the agent's response as they are processed.

    Throws

    If a critical error occurs during setup or if the service is not initialized. Errors during GMI processing are typically yielded as AgentOSErrorChunks.

handleToolResult

  • handleToolResult(streamId, toolCallId, toolName, toolOutput, isSuccess, errorMessage?): AsyncGenerator<AgentOSResponse, void, undefined>

  • Handles the result of an externally executed tool and continues the agent interaction. This method is an asynchronous generator that yields new AgentOSResponse chunks resulting from the GMI processing the tool's output.

    It functions similarly to processRequest by:

    1. Delegating to AgentOSOrchestrator.orchestrateToolResult, which pushes new chunks to the existing streamId.
    2. Registering a temporary, request-scoped stream client (bridge) to this streamId.
    3. Yielding AgentOSResponse chunks received by this bridge.
    4. Ensuring the bridge client is deregistered.

    Parameters

    • streamId: string

      The ID of the existing stream to which the tool result pertains.

    • toolCallId: string

      The ID of the specific tool call being responded to.

    • toolName: string

      The name of the tool that was executed.

    • toolOutput: any

      The output data from the tool execution.

    • isSuccess: boolean

      Indicates whether the tool execution was successful.

    • Optional errorMessage: string

      An error message if isSuccess is false.

    Returns AsyncGenerator<AgentOSResponse, void, undefined>

    An asynchronous generator for new response chunks.

    Async

    Generator

    Yields

    New response chunks from the agent after processing the tool result.

    Throws

    If a critical error occurs during setup or if the service is not initialized. Errors during GMI processing are yielded as AgentOSErrorChunks.

listWorkflowDefinitions

startWorkflow

  • startWorkflow(definitionId, input, options?): Promise<WorkflowInstance>

  • Parameters

    • definitionId: string
    • input: AgentOSInput
    • options: {
          workflowId?: string;
          conversationId?: string;
          createdByUserId?: string;
          context?: Record<string, unknown>;
          roleAssignments?: Record<string, string>;
          metadata?: Record<string, unknown>;
      } = {}
      • Optional workflowId?: string
      • Optional conversationId?: string
      • Optional createdByUserId?: string
      • Optional context?: Record<string, unknown>
      • Optional roleAssignments?: Record<string, string>
      • Optional metadata?: Record<string, unknown>

    Returns Promise<WorkflowInstance>

getWorkflow

listWorkflows

getWorkflowProgress

updateWorkflowStatus

applyWorkflowTaskUpdates

listAvailablePersonas

  • listAvailablePersonas(userId?): Promise<Partial<IPersonaDefinition>[]>

  • Lists all available personas that the requesting user (if specified) has access to.

    Parameters

    • Optional userId: string

      Optional. The ID of the user making the request. If provided, persona availability will be filtered based on the user's subscription tier and permissions. If omitted, all generally public personas might be listed (behavior determined by GMIManager).

    Returns Promise<Partial<IPersonaDefinition>[]>

    A promise that resolves to an array of persona definitions (or partial definitions suitable for public listing).

    Async

    Throws

    If the service is not initialized.

getConversationHistory

  • getConversationHistory(conversationId, userId): Promise<null | ConversationContext>

  • Retrieves the conversation history for a specific conversation ID, subject to user authorization.

    Parameters

    • conversationId: string

      The unique identifier of the conversation to retrieve.

    • userId: string

      The ID of the user requesting the history. Authorization checks are performed to ensure the user has access to this conversation.

    Returns Promise<null | ConversationContext>

    A promise that resolves to the ConversationContext object if found and accessible, or null otherwise.

    Async

    Throws

    If the service is not initialized or if a critical error occurs during history retrieval (permission errors might result in null or specific error type).

receiveFeedback

  • receiveFeedback(userId, sessionId, personaId, feedbackPayload): Promise<void>

  • Receives and processes user feedback related to a specific interaction or persona. The exact handling of feedback (e.g., storage, GMI adaptation) is determined by the configured GMIManager and underlying GMI implementations.

    Parameters

    • userId: string

      The ID of the user providing the feedback.

    • sessionId: string

      The session ID to which the feedback pertains.

    • personaId: string

      The persona ID involved in the interaction being reviewed.

    • feedbackPayload: UserFeedbackPayload

      The structured feedback data.

    Returns Promise<void>

    A promise that resolves when the feedback has been processed.

    Async

    Throws

    If the service is not initialized or if an error occurs during feedback processing (e.g., GMIErrorCode.GMI_FEEDBACK_ERROR).

shutdown

  • shutdown(): Promise<void>

  • Initiates a graceful shutdown of the AgentOS service and all its components. This includes shutting down managers, clearing caches, and releasing resources.

    Returns Promise<void>

    A promise that resolves when the shutdown sequence is complete.

    Async

    Throws

    If an error occurs during the shutdown of any critical component.

Settings

Member Visibility

Theme

On This Page

constructorinitializeprocessRequesthandleToolResultlistWorkflowDefinitionsstartWorkflowgetWorkflowlistWorkflowsgetWorkflowProgressupdateWorkflowStatusapplyWorkflowTaskUpdateslistAvailablePersonasgetConversationHistoryreceiveFeedbackshutdown