Build a Multi-Agent Orchestrator

In this lab, you'll build a complete multi-agent orchestration framework in TypeScript. You'll implement the core patterns discussed in the lesson: agent definitions with capability declarations, a supervisor that decomposes and routes tasks, handoff protocols, shared state management, parallel execution, circuit breakers, and execution tracing.

This is the architecture behind systems like LangGraph supervisors, OpenAI Swarm, and enterprise customer support platforms.

Architecture Overview

User Request
     |
Supervisor Agent
     |
Task Decomposition
     |
+---------+---------+
|         |         |
Agent A  Agent B  Agent C  (parallel if independent)
|         |         |
+---------+---------+
     |
Result Aggregation
     |
Final Response

FILE 1: Agent Definition Framework

Build the AgentDefinition interface and AgentRegistry class. Each agent has:

• A unique id and human-readable name
• A systemPrompt that defines the agent's behavior
• A capabilities array describing what tasks it can handle (e.g., ["billing", "refunds"])
• A tools array listing which tools the agent has access to
• A modelConfig with model name and temperature settings
• A maxTokenBudget limiting how many tokens this agent can consume per request

The AgentRegistry should:

• Register and unregister agents
• Find agents by capability (return all agents that list a given capability)
• Validate that agent IDs are unique on registration

FILE 2: Supervisor Agent

Build a Supervisor class that orchestrates the multi-agent workflow:

• Task decomposition: Accept a user request and break it into subtasks, each tagged with the required capability
• Agent routing: For each subtask, find the best agent from the registry based on capabilities
• Execution: Run subtasks (delegating to agent handlers), collecting results
• Aggregation: Combine all subtask results into a single coherent response
• Max delegation depth: Prevent the supervisor from recursively delegating beyond a configurable limit

FILE 3: Agent Handoff Protocol

Build a HandoffManager that handles agent-to-agent transfers:

• Create a HandoffRequest with source agent, target agent, reason, conversation history, and task state
• Validate that the target agent has the required capabilities before accepting
• Transfer context (conversation history and accumulated results) to the receiving agent
• Track handoff chain to detect and prevent circular handoffs (A -> B -> A)
• Return a HandoffResult with success/failure status and the receiving agent's response

FILE 4: Shared State Manager

Build a SharedStateManager that provides a thread-safe shared state for all agents:

• get(key) and set(key, value) with versioning (each write increments a version number)
• Conflict resolution with two strategies:
  • last-write-wins: The latest write always takes effect
  • merge: For object values, deep-merge the new value with the existing one
• getVersion(key) to retrieve the current version number for a key
• getHistory(key) to retrieve the history of all writes to a key (value + version + timestamp + agentId)

FILE 5: Parallel Executor

Build a ParallelExecutor that runs independent tasks concurrently:

• Accept a task graph where each task has an id, dependencies (array of task IDs), and an execute function
• Identify which tasks can run in parallel (tasks with all dependencies satisfied)
• Execute ready tasks concurrently using Promise.all
• Wait for dependencies before starting dependent tasks
• Detect circular dependencies and throw an error
• Return all results once the full graph has executed

FILE 6: Circuit Breaker

Build a CircuitBreaker that protects against agent failures:

• Three states: CLOSED (normal), OPEN (failing — reject all calls), HALF_OPEN (testing recovery)
• Track failure count per agent
• Transition from CLOSED to OPEN when failure count exceeds a configurable threshold
• Transition from OPEN to HALF_OPEN after a configurable cooldown period
• Transition from HALF_OPEN to CLOSED on success, or back to OPEN on failure
• When an agent's circuit is OPEN, route to a fallback agent if one is configured
• execute(agentId, fn) wraps an agent call with circuit breaker logic

FILE 7: Execution Trace

Build an ExecutionTracer that records every action in the multi-agent system:

• Track each agent invocation: agent ID, start time, end time, token usage, cost
• Track handoffs: source, target, reason, success/failure
• Track the full execution tree (which agent spawned which subtasks)
• Calculate total cost across all agents (sum of individual agent costs)
• Calculate total duration (wall clock time from first event to last)
• getSummary() returns an object with total cost, total duration, agent invocation count, and per-agent breakdowns

What to Submit

The editor has 7 file sections with TODO comments. Replace each TODO with your TypeScript code. The AI grader will evaluate each section against the rubric.

Hints

• For the parallel executor, use topological sort to determine execution order and detect cycles
• For the circuit breaker, store the last failure time and compare against Date.now() for cooldown
• For shared state conflict resolution, the merge strategy should use a recursive object merge for nested objects
• For loop detection in handoffs, maintain a Set<string> of visited agent IDs per conversation
• Use Promise.all for parallel task execution but be careful to handle individual task failures without rejecting the entire batch