Class: AgentOS

Defined in: packages/agentos/src/api/AgentOS.ts:441

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

new AgentOS(logger?): AgentOS

Defined in: packages/agentos/src/api/AgentOS.ts:474

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

Parameters

logger?

ILogger = ...

Returns

AgentOS

Methods

applyWorkflowTaskUpdates()

applyWorkflowTaskUpdates(workflowId, updates): Promise<WorkflowInstance | null>

Defined in: packages/agentos/src/api/AgentOS.ts:1286

Applies task-level updates to a workflow instance.

Parameters

workflowId

string

The workflow instance ID.

updates

WorkflowTaskUpdate[]

Array of task updates to apply.

Returns

Promise<WorkflowInstance | null>

Updated workflow instance or null if not found.

Implementation of

IAgentOS.applyWorkflowTaskUpdates

---

getConversationHistory()

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

Defined in: packages/agentos/src/api/AgentOS.ts:1329

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<ConversationContext | null>

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).

Implementation of

IAgentOS.getConversationHistory

---

getWorkflow()

getWorkflow(workflowId): Promise<WorkflowInstance | null>

Defined in: packages/agentos/src/api/AgentOS.ts:1260

Retrieves a workflow instance by its identifier.

Parameters

workflowId

string

The workflow instance ID.

Returns

Promise<WorkflowInstance | null>

The workflow instance or null if not found.

Implementation of

IAgentOS.getWorkflow

---

getWorkflowProgress()

getWorkflowProgress(workflowId, sinceTimestamp?): Promise<WorkflowProgressUpdate | null>

Defined in: packages/agentos/src/api/AgentOS.ts:1270

Retrieves workflow progress details, including recent events.

Parameters

workflowId

string

The workflow instance ID.

sinceTimestamp?

string

Optional timestamp to get events since.

Returns

Promise<WorkflowProgressUpdate | null>

Progress details or null if not found.

Implementation of

IAgentOS.getWorkflowProgress

---

handleToolResult()

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

Defined in: packages/agentos/src/api/AgentOS.ts:1158

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.

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.

Implementation of

IAgentOS.handleToolResult

---

initialize()

initialize(config): Promise<void>

Defined in: packages/agentos/src/api/AgentOS.ts:489

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.

Implementation of

IAgentOS.initialize

---

listAvailablePersonas()

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

Defined in: packages/agentos/src/api/AgentOS.ts:1306

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

Parameters

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.

Implementation of

IAgentOS.listAvailablePersonas

---

listWorkflowDefinitions()

listWorkflowDefinitions(): WorkflowDefinition[]

Defined in: packages/agentos/src/api/AgentOS.ts:1220

Lists registered workflow definitions available via the extension manager.

Returns

WorkflowDefinition[]

Array of available workflow definitions.

Implementation of

IAgentOS.listWorkflowDefinitions

---

listWorkflows()

listWorkflows(options?): Promise<WorkflowInstance[]>

Defined in: packages/agentos/src/api/AgentOS.ts:1265

Lists workflow instances matching the provided filters.

Parameters

options?

WorkflowQueryOptions

Optional query filters.

Returns

Promise<WorkflowInstance[]>

Array of matching workflow instances.

Implementation of

IAgentOS.listWorkflows

---

processRequest()

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

Defined in: packages/agentos/src/api/AgentOS.ts:959

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.

Implementation of

IAgentOS.processRequest

---

receiveFeedback()

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

Defined in: packages/agentos/src/api/AgentOS.ts:1375

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).

Implementation of

IAgentOS.receiveFeedback

---

shutdown()

shutdown(): Promise<void>

Defined in: packages/agentos/src/api/AgentOS.ts:1400

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.

Implementation of

IAgentOS.shutdown

---

startWorkflow()

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

Defined in: packages/agentos/src/api/AgentOS.ts:1225

Starts a workflow instance using the specified definition and input payload.

Parameters

definitionId

string

The ID of the workflow definition to instantiate.

input

AgentOSInput

The input payload for the workflow.

options?

Optional configuration for the workflow instance.

context?

Record<string, unknown>

conversationId?

string

createdByUserId?

string

metadata?

Record<string, unknown>

roleAssignments?

Record<string, string>

workflowId?

string

Returns

Promise<WorkflowInstance>

The created workflow instance.

Implementation of

IAgentOS.startWorkflow

---

updateWorkflowStatus()

updateWorkflowStatus(workflowId, status): Promise<WorkflowInstance | null>

Defined in: packages/agentos/src/api/AgentOS.ts:1278

Updates the high-level workflow status (e.g., cancel, complete).

Parameters

workflowId

string

The workflow instance ID.

status

WorkflowStatus

The new status to set.

Returns

Promise<WorkflowInstance | null>

Updated workflow instance or null if not found.

Implementation of

IAgentOS.updateWorkflowStatus