Skip to main content

Class: AgentOS

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

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:948

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:2624

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:2674

Async

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.

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

getConversationManager()​

getConversationManager(): ConversationManager

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

Explicit runtime getters for devtools integrations such as AgentOS Workbench.

Returns​

ConversationManager

Implementation of​

IAgentOS.getConversationManager

getExtensionManager()​

getExtensionManager(): ExtensionManager

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

Returns​

ExtensionManager

Implementation of​

IAgentOS.getExtensionManager

getExternalToolRegistry()​

getExternalToolRegistry(): ExternalToolRegistry | undefined

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

Returns​

ExternalToolRegistry | undefined

Implementation of​

IAgentOS.getExternalToolRegistry

getGMIManager()​

getGMIManager(): GMIManager

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

Returns​

GMIManager

Implementation of​

IAgentOS.getGMIManager

getHttpHandlers()​

getHttpHandlers(): HttpHandlerPayload[]

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

Active extension HTTP handlers (EXTENSION_KIND_HTTP_HANDLER payloads), in registration order. Empty before initialize() or when none are loaded. Hosts (AgentOSServer, wunderland start, express mounts) iterate these to serve pack-contributed endpoints such as webhooks.

Returns​

HttpHandlerPayload[]

getLearningLayer()​

getLearningLayer(): ILearningLayer | undefined

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

The runtime's learning layer, or undefined when learning is off: no learning option and no layer passed in gmiManagerConfig.learningLayer. A host reads the loop manifest from it; a measurement asserts on it that a runtime it compares has learning off.

Returns​

ILearningLayer | undefined

Implementation of​

IAgentOS.getLearningLayer

getModelProviderManager()​

getModelProviderManager(): AIModelProviderManager

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

Returns​

AIModelProviderManager

Implementation of​

IAgentOS.getModelProviderManager

getPendingExternalToolRequest()​

getPendingExternalToolRequest(conversationId, userId): Promise<AgentOSPendingExternalToolRequest | null>

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

Returns the pending external-tool pause snapshot for a conversation, if one was persisted during an actionable TOOL_CALL_REQUEST pause. A pause saved by a stream an output guardrail blocked is never returned: it is dropped once the stream's turn ends, and this returns null for it meanwhile.

Parameters​

conversationId​

string

userId​

string

Returns​

Promise<AgentOSPendingExternalToolRequest | null>

Implementation of​

IAgentOS.getPendingExternalToolRequest

getRuntimeSnapshot()​

getRuntimeSnapshot(): Promise<AgentOSRuntimeSnapshot>

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

Returns a serializable runtime/devtools snapshot of the initialized AgentOS instance.

Returns​

Promise<AgentOSRuntimeSnapshot>

Implementation of​

IAgentOS.getRuntimeSnapshot

getToolOrchestrator()​

getToolOrchestrator(): IToolOrchestrator

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

Returns​

IToolOrchestrator

Implementation of​

IAgentOS.getToolOrchestrator

getWorkflow()​

getWorkflow(workflowId): Promise<WorkflowInstance | null>

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

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:2608

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:2430

Async Generator

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.

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

handleToolResults()​

handleToolResults(streamId, toolResults): AsyncGenerator<AgentOSResponse, void, undefined>

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

Handles a batch of externally executed tool results that belong to the same paused stream and continues the agent interaction once.

Parameters​

streamId​

string

The original stream ID associated with the paused request.

toolResults​

AgentOSToolResultInput[]

Ordered tool results to apply to the paused turn.

Returns​

AsyncGenerator<AgentOSResponse, void, undefined>

An async generator that yields response chunks after processing the tool results.

Throws​

If the streamId is invalid or the tool result batch is empty.

The batch continues the pause once, as handleToolResult() does: on an open stream, a batch for a pause that is being continued already, or with a result for a call the stream's pause does not hold, yields one error chunk with the code SYS_INVALID_STATE.

Implementation of​

IAgentOS.handleToolResults

initialize()​

initialize(config): Promise<void>

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

Async

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.

Throws​

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

Implementation of​

IAgentOS.initialize

listAgencies()​

listAgencies(): AgencySession[]

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

Copies of the agencies running now: a workflow's, and every team a persona's GMI launched with launch_agency (agencies.launch), whose entry has metadata.kind: 'launched' and lasts while its team runs.

Returns​

AgencySession[]

The running agencies; empty on a runtime with no agency registry.

listAvailablePersonas()​

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

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

Async

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

Throws​

If the service is not initialized.

Implementation of​

IAgentOS.listAvailablePersonas

listExternalToolsForLLM()​

listExternalToolsForLLM(): ToolDefinitionForLLM[]

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

Returns​

ToolDefinitionForLLM[]

Implementation of​

IAgentOS.listExternalToolsForLLM

listWorkflowDefinitions()​

listWorkflowDefinitions(): WorkflowDefinition[]

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

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:2592

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:2077

Async Generator

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 internal streaming manager.
  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 internal streaming manager. 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.

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:2855

Async

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.

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

resumeExternalToolRequest()​

resumeExternalToolRequest(pendingRequest, toolResults, options?): AsyncGenerator<AgentOSResponse, void, undefined>

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

Resumes a previously persisted external-tool pause after restart using the saved pause snapshot and the host-provided tool results.

Hosts can re-assert runtime-only organization context through options when the resumed turn needs organization-scoped memory or tenant routing.

A pause is resumed once. When the conversation no longer holds the pause the snapshot names (its results were passed on its stream, an output guardrail blocked its stream, a newer turn ended it, or a newer pause replaced it), another resume of it is under way, or a result answers a call the pause does not hold, the stream yields one error chunk with the code SYS_INVALID_STATE and the GMI takes none of the results. Such a resume is refused before the session's GMI is acquired, so it changes neither the conversation nor that GMI. A resume ends the stream the pause was saved on. A resume whose organization the runtime refuses, or whose continuation fails before the conversation records the results, leaves the pause as it was.

The once-only rule holds within one AgentOS instance: instances that share a conversation store do not see each other's resumes, so a deployment with several instances sends one conversation's resumes to one instance at a time.

Parameters​

pendingRequest​

AgentOSPendingExternalToolRequest

toolResults​

AgentOSToolResultInput[]

options?​

AgentOSResumeExternalToolRequestOptions = {}

Returns​

AsyncGenerator<AgentOSResponse, void, undefined>

Implementation of​

IAgentOS.resumeExternalToolRequest

shutdown()​

shutdown(): Promise<void>

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

Async

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.

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:2571

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:2616

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

create()​

static create(overrides?, logger?): Promise<AgentOS>

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

Convenience factory: build an AgentOS instance with a fully-populated default configuration in a single call.

The factory uses createAgentOSConfig under the hood, which reads from the standard environment (DATABASE_URL, provider API keys, etc.) and wires up sane defaults for every sub-system. Any fields passed in overrides are deep-merged onto the generated config so callers can tweak observability, memoryTools, etc. without rebuilding the whole config object themselves. Provenance is an extension pack (createProvenancePack() in extensionManifest), not a config key.

For fine-grained control, fall back to new AgentOS() + initialize(yourConfig).

Parameters​

overrides?​

Partial<AgentOSConfig> & object = {}

Optional partial AgentOSConfig whose fields are shallow-merged onto the auto-generated config. Pass tools / externalTools here to register them at construction time. Pass observability, memoryTools, etc. to opt into subsystems without touching the rest of the defaults.

logger?​

ILogger

Optional logger override.

Returns​

Promise<AgentOS>

A fully-initialised AgentOS instance.

Throws​

If env config is invalid or initialisation fails.

Example​

import { AgentOS } from '@framers/agentos';

// Defaults — reads DATABASE_URL + provider keys from env.
const os = await AgentOS.create();

// With tracing turned on.
const observed = await AgentOS.create({
  observability: { tracing: { enabled: true } },
});