Overview The Orchestrator class from @agentlib/orchestrator enables you to coordinate multiple agents, running them in parallel or sequentially based on your workflow needs. It uses a planner agent to decide how to delegate tasks to specialized sub-agents.
Constructor import { Orchestrator } from '@agentlib/orchestrator' const orchestrator = new Orchestrator ( planner , config )
The planner agent that coordinates sub-agents. This agent receives special tools to invoke and manage other agents.
config
OrchestratorConfig
required
Configuration object for the orchestrator. agents
Record<string, AgentInstance>
required
Map of agent names to agent instances that can be invoked by the planner.
Maximum number of steps the planner can take.
If true, agent outputs are summarized and injected into the planner’s context for future runs.
If true, automatically registers coordination tools (invoke_agent, wait_for_agent, etc.) for the planner.
Global context object injected into all agents’ system prompts. Useful for sharing configuration or state.
If true, includes last activity from sub-agents in the history.
onStep
(step: any) => Promise<string | void> | string | void
Callback invoked on every agent step. Return 'abort' to cancel the agent’s execution.
Methods run() Execute the planner agent with the given input.
const result = await orchestrator . run ( input )
The user prompt or task to execute.
The final response from the planner agent.
The execution state containing steps, messages, and token usage.
invokeAgent() Manually invoke a sub-agent with a prompt. The agent runs asynchronously in parallel.
await orchestrator . invokeAgent ( 'researcher' , 'Find information about AI safety' )
Name of the agent to invoke (must exist in the agents config).
The prompt to send to the agent.
waitAgent() Wait for a specific agent to complete and retrieve its output.
const output = await orchestrator . waitAgent ( 'researcher' )
Name of the agent to wait for.
The agent’s final output.
waitAll() Wait for all currently running agents to complete.
const results = await orchestrator . waitAll () // { researcher: '...', writer: '...', ... }
Map of agent names to their outputs.
getAgentState() Get the current state of a specific agent.
const state = orchestrator . getAgentState ( 'researcher' )
status
'idle' | 'running' | 'error'
Current status of the agent.
The most recent output from the agent.
Error object if the agent failed.
getAllStates() Get the current states of all agents.
const states = orchestrator . getAllStates ()
Array of all agent states.
clearAgentHistory() Clear the memory/history of a specific agent.
await orchestrator . clearAgentHistory ( 'researcher' )
Name of the agent whose history should be cleared.
getHistory() Retrieve aggregated history from all sub-agents.
const history = await orchestrator . getHistory ()
Array of messages representing the last activity from each agent (if extendedSubBuffers is enabled).
When exposeAgentsAsTools is true (default), the planner automatically receives these tools:
invoke_agent Launch an agent with a specific prompt. The agent runs in parallel.
{ "agentName" : "researcher" , "prompt" : "Research AI safety principles" }
wait_for_agent Wait for a specific agent to finish and retrieve its result.
{ "agentName" : "researcher" }
wait_all_agents Wait for all currently running agents to complete.
get_agent_state Get the current state and last output of a specific agent.
{ "agentName" : "researcher" }
get_all_agent_states Get the current status of all agents.
clear_agent_history Clear the temporary memory of a specific agent.
{ "agentName" : "researcher" }
Events The orchestrator extends EventEmitter and emits the following events:
Emitted when the planner takes a reasoning step.
agent:invoke
{ agent: string; prompt: string }
Emitted when a sub-agent is invoked.
agent:completed
{ agent: string; output: string }
Emitted when a sub-agent completes execution.
agent:step
{ agent: string; step: any }
Emitted when a sub-agent takes a reasoning step.
Emitted when an agent step is summarized (if summarize is enabled).
Emitted when the orchestrator completes execution.
Example import { defineAgent } from '@agentlib/core' import { Orchestrator } from '@agentlib/orchestrator' import { openai } from '@agentlib/openai' // Define specialized agents const researcher = defineAgent ({ name: 'researcher' , description: 'Researches topics and gathers information' , model: openai ( 'gpt-4' ), }) const writer = defineAgent ({ name: 'writer' , description: 'Writes content based on research' , model: openai ( 'gpt-4' ), }) // Define planner agent const planner = defineAgent ({ name: 'planner' , description: 'Coordinates research and writing tasks' , model: openai ( 'gpt-4' ), }) // Create orchestrator const orchestrator = new Orchestrator ( planner , { agents: { researcher , writer , }, summarize: true , context: { project: 'AI Documentation' , audience: 'developers' , }, }) // Listen to events orchestrator . on ( 'agent:step' , ({ agent , step }) => { console . log ( `[ ${ agent } ]` , step . type ) }) // Execute const result = await orchestrator . run ( 'Write a comprehensive guide about transformer architectures' ) console . log ( result . output )
Orchestration Patterns Sequential Execution The planner invokes agents one at a time, waiting for results before proceeding:
1. invoke_agent(researcher, prompt) 2. wait_for_agent(researcher) 3. invoke_agent(writer, prompt_with_research) 4. wait_for_agent(writer)
Parallel Execution The planner invokes multiple agents, then waits for all to complete:
1. invoke_agent(researcher_A, prompt_A) 2. invoke_agent(researcher_B, prompt_B) 3. wait_for_agent(researcher_A) 4. wait_for_agent(researcher_B) 5. invoke_agent(writer, combined_prompt) 6. wait_for_agent(writer)
Mixed Execution Combine parallel and sequential patterns as needed:
1. invoke_agent(researcher_A, prompt_A) 2. invoke_agent(researcher_B, prompt_B) 3. wait_all_agents() 4. invoke_agent(analyzer, analysis_prompt) 5. wait_for_agent(analyzer)