Static createConvenience 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).
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.
Optional logger: ILoggerOptional logger override.
A fully-initialised AgentOS instance.
If env config is invalid or initialisation fails.
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 } },
});
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.
The comprehensive configuration object for AgentOS.
A promise that resolves when initialization is complete.
If configuration validation fails or if any critical dependency fails to initialize.
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.
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.
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:
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).
The comprehensive input for the current interaction turn.
An asynchronous generator that yields response chunks. The generator completes when the interaction is finalized or a terminal error occurs.
Chunks of the agent's response as they are processed.
If a critical error occurs during setup or if the
service is not initialized. Errors during GMI processing are typically yielded as
AgentOSErrorChunks.
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:
streamId.streamId.The ID of the existing stream to which the tool result pertains.
The ID of the specific tool call being responded to.
The name of the tool that was executed.
The output data from the tool execution.
Indicates whether the tool execution was successful.
Optional errorMessage: stringAn error message if isSuccess is false.
An asynchronous generator for new response chunks.
New response chunks from the agent after processing the tool result.
If a critical error occurs during setup or if the service is not initialized.
Errors during GMI processing are yielded as AgentOSErrorChunks.
Optional workflowOptional conversationOptional createdOptional context?: Record<string, unknown>Optional roleOptional metadata?: Record<string, unknown>Optional options: WorkflowQueryOptionsCopies 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.
The running agencies; empty on a runtime with no agency registry.
Optional sinceTimestamp: stringAsync Lists all available personas that the requesting user (if specified) has access to.
Optional userId: stringOptional. 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).
A promise that resolves to an array of persona definitions (or partial definitions suitable for public listing).
If the service is not initialized.
Async Retrieves the conversation history for a specific conversation ID, subject to user authorization.
The unique identifier of the conversation to retrieve.
The ID of the user requesting the history. Authorization checks are performed to ensure the user has access to this conversation.
A promise that resolves to the
ConversationContext object if found and accessible, or null otherwise.
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).
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.
The ID of the user providing the feedback.
The session ID to which the feedback pertains.
The persona ID involved in the interaction being reviewed.
The structured feedback data.
A promise that resolves when the feedback has been processed.
If the service is not initialized or if an error occurs
during feedback processing (e.g., GMIErrorCode.GMI_FEEDBACK_ERROR).
Async Initiates a graceful shutdown of the AgentOS service and all its components.
This includes shutting down managers, clearing caches, and releasing resources.
A promise that resolves when the shutdown sequence is complete.
If an error occurs during the shutdown of any critical component.
Implements
Description
The
AgentOSclass 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.