Class: AgentOSOrchestrator
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:279
Description
The AgentOSOrchestrator is responsible for unifying the request handling
pipeline for AgentOS. It bridges the high-level AgentOSInput from the
public API to the internal GMI processing logic. It ensures that user
requests are routed to the correct GMI, manages the GMI's turn lifecycle,
and handles the complex dance of tool calls and streaming responses.
Constructors
Constructor
new AgentOSOrchestrator():
AgentOSOrchestrator
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:305
Returns
AgentOSOrchestrator
Methods
broadcastWorkflowUpdate()
broadcastWorkflowUpdate(
update):Promise<void>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:458
Parameters
update
Returns
Promise<void>
discardBlockedToolCalls()
discardBlockedToolCalls(
agentOSStreamId,toolCallIds,refusal):Promise<boolean>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:717
Drops the pause a stream saved after an output guardrail blocked the stream. With toolCallIds, the calls the
block withheld from the caller (the verdict's toolCallIds), it drops the pause that holds one of them; without,
for a block that withheld no call (a streamed delta, or the chunk of calls the runtime runs itself, after which the
turn goes on inside the runtime), it drops the pause the stream saves whatever calls it holds. It waits for the
stream's turn or resumed turn to end, since a turn can save its pause after it streams the call or after the
block; then, when the conversation's pending request is this stream's, it records a refused tool result for each
call of the pause, clears the pending request and closes the stream, so the call can be neither continued on the
stream nor resumed from the conversation. Anything else is left as it is. From the call until the drop ends, the
stream is held as blocked (see isStreamBlocked): a pause the turn saves meanwhile is not offered, resumed
or continued. The stream is closed even when the store refuses the conversation's save; the stored conversation
then keeps the pause until the conversation is saved again.
Parameters
agentOSStreamId
string
The stream the guardrail blocked.
toolCallIds
The ids of the calls the block withheld, or undefined for a block that withheld none.
readonly string[] | undefined
refusal
What the refused tool results say.
Returns
Promise<boolean>
Whether a pause was dropped.
Throws
The store's error when it refuses the save, after the pause is dropped in memory and the stream closed.
getStreamIdentity()
getStreamIdentity(
streamId): {conversationId:string;personaId:string;sessionId:string;userId:string; } |null
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:505
Who a live stream belongs to, for the guardrails that judge its continuation; null once the stream has ended.
Parameters
streamId
string
Returns
{ conversationId: string; personaId: string; sessionId: string; userId: string; } | null
initialize()
initialize(
config,dependencies):Promise<void>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:318
Async
Initializes the AgentOSOrchestrator with its configuration and dependencies. This method must be called successfully before orchestrating any turns.
Parameters
config
Configuration settings for the orchestrator.
dependencies
AgentOSOrchestratorDependencies
Required services.
Returns
Promise<void>
A Promise that resolves when initialization is complete.
Throws
If any critical dependency is missing or config is invalid.
isStreamBlocked()
isStreamBlocked(
agentOSStreamId):boolean
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:747
Whether an output guardrail blocked the stream and the pause it saves is being dropped: until the drop ends, that
pause is not offered by getPendingExternalToolRequest(), a resume of it is refused, and tool results do not
continue the stream. Before initialize() no stream has run, so none is blocked.
Parameters
agentOSStreamId
string
Returns
boolean
orchestrateResumedToolResults()
orchestrateResumedToolResults(
pendingRequest,toolResults,options?,guards?):Promise<string>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:599
Resumes a pause from its snapshot on a new stream. The pause is taken before the stream is made or the session's GMI acquired, so a resume of a pause the conversation no longer holds, whose stream an output guardrail blocked, or that another resume holds, or with a result for a call the pause does not hold, is refused with nothing changed.
Parameters
pendingRequest
AgentOSPendingExternalToolRequest
toolResults
options?
AgentOSResumeExternalToolRequestOptions = {}
guards?
AgentOSOrchestratorGuards = {}
Returns
Promise<string>
The new stream's id.
Throws
INVALID_STATE when the pause is not taken.
orchestrateToolResult()
orchestrateToolResult(
agentOSStreamId,toolCallId,toolName,toolOutput,isSuccess,errorMessage?):Promise<void>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:1264
Handles the result of an external tool execution, feeding it back into the relevant GMI instance for continued processing. Delegates to ExternalToolResultHandler.
Parameters
agentOSStreamId
string
toolCallId
string
toolName
string
toolOutput
any
isSuccess
boolean
errorMessage?
string
Returns
Promise<void>
orchestrateToolResults()
orchestrateToolResults(
agentOSStreamId,toolResults,guards?):Promise<void>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:1282
Handles one or more external tool results in batch. Delegates to ExternalToolResultHandler.
Parameters
agentOSStreamId
string
toolResults
guards?
AgentOSOrchestratorGuards = {}
Returns
Promise<void>
orchestrateTurn()
orchestrateTurn(
input,guards?):Promise<string>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:522
Async
Orchestrates a full logical turn for a user request. This involves managing GMI interaction, tool calls, and streaming responses. Instead of directly yielding, it uses the StreamingManager to push chunks.
Parameters
input
The comprehensive input for the current turn.
guards?
AgentOSOrchestratorGuards = {}
Returns
Promise<string>
The ID of the stream to which responses will be pushed.
Throws
If critical initialization or setup fails.
shutdown()
shutdown():
Promise<void>
Defined in: packages/agentos/src/api/runtime/AgentOSOrchestrator.ts:1303
Async
Shuts down the AgentOSOrchestrator. Currently, this mainly involves clearing active stream contexts. Dependencies like GMIManager are assumed to be shut down by AgentOS.
Returns
Promise<void>
A promise that resolves when shutdown is complete.