npm install @agentlib/orchestrator

import { createAgent } from '@agentlib/core'
import { Orchestrator } from '@agentlib/orchestrator'
import { openai } from '@agentlib/openai'

// Create specialized agents
const researcher = createAgent({
  name: 'researcher',
  description: 'Finds and analyzes information',
  model: openai({ apiKey: process.env.OPENAI_API_KEY! }),
  tools: [searchTool]
})

const writer = createAgent({
  name: 'writer',
  description: 'Creates written content',
  model: openai({ apiKey: process.env.OPENAI_API_KEY! })
})

// Create planner agent
const planner = createAgent({
  name: 'planner',
  description: 'Coordinates research and writing tasks',
  model: openai({ apiKey: process.env.OPENAI_API_KEY! }),
  reasoning: 'planner'
})

// Create orchestrator
const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer }
})

// Run coordinated task
const result = await orchestrator.run(
  'Research AI trends and write a blog post'
)
console.log(result.output)

interface OrchestratorConfig {
  /** Map of agent name to agent instance */
  agents?: Record<string, AgentInstance>
  
  /** Global context shared across all agents */
  context?: Record<string, any>
  
  /** Auto-expose agents as tools to planner (default: true) */
  exposeAgentsAsTools?: boolean
  
  /** Enable automatic summarization of agent outputs */
  summarize?: boolean
  
  /** Include sub-agent buffers in context */
  extendedSubBuffers?: boolean
  
  /** Callback for each agent step */
  onStep?: (step: ReasoningStep & { agent: string }) => 'abort' | void
}

const planner = createAgent({
  name: 'planner',
  description: 'Orchestrates multiple specialized agents',
  model: openai({ apiKey: process.env.OPENAI_API_KEY! }),
  reasoning: 'planner' // Recommended
})

const agents = {
  researcher: createAgent({
    name: 'researcher',
    description: 'Expert at finding information',
    tools: [webSearchTool, wikiTool]
  }),
  
  analyst: createAgent({
    name: 'analyst',
    description: 'Analyzes data and trends',
    tools: [calculatorTool, chartTool]
  }),
  
  writer: createAgent({
    name: 'writer',
    description: 'Creates polished written content'
  })
}

// Planner can call:
invoke_agent({
  agentName: 'researcher',
  prompt: 'Find latest AI breakthroughs'
})

// Must be called after invoke_agent:
const result = await wait_for_agent({ agentName: 'researcher' })

const results = await wait_all_agents()
// Returns: { researcher: '...', writer: '...' }

const state = await get_agent_state({ agentName: 'researcher' })
// Returns: { name: 'researcher', status: 'running', lastOutput: '...' }

const states = await get_all_agent_states()
// Returns array of AgentState objects

await clear_agent_history({ agentName: 'researcher' })

const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer }
})

await orchestrator.run(`
  1. Use researcher to find AI trends
  2. Use writer to create a blog post based on research
`)

await orchestrator.run(`
  Research AI trends in healthcare AND education,
  then synthesize findings
`)

const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer },
  context: {
    company: 'Acme Corp',
    audience: 'enterprise developers',
    style: 'technical but accessible'
  }
})

### Global Context (READ ONLY):
{
  "company": "Acme Corp",
  "audience": "enterprise developers",
  "style": "technical but accessible"
}

// These agents will have independent memory
const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer }
})

// Multiple calls to same agent maintain context
await orchestrator.run('Ask researcher about AI')
await orchestrator.run('Ask researcher to elaborate') // Remembers previous

await orchestrator.clearAgentHistory('researcher')

const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer },
  summarize: true
})

import { Orchestrator } from '@agentlib/orchestrator'

const orchestrator = new Orchestrator(planner, config)

// Agent invoked
orchestrator.on('agent:invoke', ({ agent, prompt }) => {
  console.log(`Starting ${agent}: ${prompt}`)
})

// Agent completed
orchestrator.on('agent:completed', ({ agent, output }) => {
  console.log(`${agent} finished: ${output}`)
})

// Agent step
orchestrator.on('agent:step', ({ agent, step }) => {
  console.log(`[${agent}] ${step.type}:`, step)
})

// Planner step
orchestrator.on('planner:step', ({ step }) => {
  console.log(`[planner] ${step.type}:`, step)
})

// Step summary (if summarize: true)
orchestrator.on('step:summary', (summary) => {
  console.log('Summary:', summary)
})

// Orchestrator finished
orchestrator.on('finished', ({ output }) => {
  console.log('Done:', output)
})

const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer },
  onStep: (step) => {
    console.log(`[${step.agent}] ${step.type}`)
    
    // Abort on certain conditions
    if (step.type === 'error') {
      return 'abort'
    }
  }
})

// Manually invoke an agent
await orchestrator.invokeAgent('researcher', 'Find AI trends')

// Wait for specific agent
const output = await orchestrator.waitAgent('researcher')

// Wait for all
const allOutputs = await orchestrator.waitAll()

// Get state
const state = orchestrator.getAgentState('researcher')
const allStates = orchestrator.getAllStates()

const orchestrator = new Orchestrator(planner, {
  agents: { researcher, writer },
  extendedSubBuffers: true
})

// Planner can see last activity from each agent
const history = await orchestrator.getHistory()

interface AgentState {
  name: string
  status: 'idle' | 'running' | 'error'
  lastOutput?: string
  error?: Error
}

const orchestrator = new Orchestrator(planner, {
  agents: {
    researcher: createAgent({ /* ... */ }),
    writer: createAgent({ /* ... */ }),
    editor: createAgent({ /* ... */ })
  }
})

await orchestrator.run('Write a technical blog post about Rust')

const orchestrator = new Orchestrator(planner, {
  agents: {
    vision: createAgent({ tools: [imageAnalysisTool] }),
    text: createAgent({ tools: [textAnalysisTool] }),
    synthesis: createAgent({ /* ... */ })
  }
})

await orchestrator.run('Analyze this image and caption')

const orchestrator = new Orchestrator(planner, {
  agents: {
    classifier: createAgent({ /* categorize issue */ }),
    knowledge: createAgent({ tools: [kbSearchTool] }),
    responder: createAgent({ /* draft response */ })
  }
})

await orchestrator.run('Help customer with login issue')