AI Engineer Portal

Your personal operating system for career transition.

Private mode

Exercise

Multi-agent handoff protocol

Multi-Agent Handoff Protocol

As agent systems grow, a single monolithic agent becomes unwieldy. The multi-agent pattern splits work among specialist agents (e.g., a researcher, a coder, a reviewer) with a coordinator that routes tasks and aggregates results. The critical engineering challenge is the handoff protocol: how agents pass context to each other cleanly.

What you are building

Create a multi-agent handoff system with:

Agent base class — each agent has a name, a description of its capabilities, and a handle(task) method.
HandoffContext — a structured object that carries the task description, conversation history, intermediate results, and metadata between agents.
Coordinator — routes tasks to the appropriate specialist based on task type, collects results, and handles failures (retry, skip, or escalate).
Handoff protocol — when an agent cannot complete a task, it returns a HandoffRequest indicating which specialist should take over and what context to pass.
Result aggregation — the coordinator collects results from multiple agents and produces a unified response.

Why this matters

Multi-agent architectures are how production AI systems handle complex workflows: customer support (triage agent -> specialist agent -> quality review agent), code generation (planner -> coder -> tester), research (search agent -> analysis agent -> writing agent). The handoff protocol is where most multi-agent systems break — context gets lost, errors cascade, and the coordinator loses track of state.

Constraints

Each agent must be independently testable with mock inputs.
The coordinator must handle agent failures without crashing the entire workflow.
HandoffContext must be serializable (to dict) for logging and debugging.
Support a maximum depth for handoff chains to prevent infinite delegation.

Agents / advanced / Step 6 of 8

Practice stage

Agent architecture patterns

Hint

Focus on explicit control surfaces — function schemas, state machines, and structured outputs. Agents are most useful when the task requires dynamic tool selection or multi-step reasoning. Start with the simplest pattern (single tool call) before reaching for ReAct loops.

Next drill

Agent evaluation harness

Success criteria

- Tools return structured, typed responses
- Agent completes the task within a bounded number of steps
- All tool calls include error handling and retries
- Memory/state management prevents unbounded context growth

Review checklist

- Tool schemas validate inputs and handle errors gracefully
- Agent loop has explicit termination conditions
- State is serializable and inspectable between steps
- Cost and token usage are tracked per invocation
- Fallback behavior exists for tool call failures

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Callable
from enum import Enum

class TaskStatus(Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    FAILED = "failed"
    HANDED_OFF = "handed_off"

@dataclass
class HandoffContext:
    """Context passed between agents during handoffs."""
    task_description: str
    conversation_history: list[dict[str, str]] = field(default_factory=list)
    intermediate_results: dict[str, Any] = field(default_factory=dict)
    metadata: dict[str, Any] = field(default_factory=dict)
    handoff_chain: list[str] = field(default_factory=list)

def to_dict(self) -> dict:
        """Serialize for logging."""
        # TODO: return serializable dict
        raise NotImplementedError

@dataclass
class AgentResult:
    """Result from an agent's work on a task."""
    status: TaskStatus
    output: Any = None
    error: str | None = None
    handoff_request: HandoffRequest | None = None

@dataclass
class HandoffRequest:
    """Request to hand off work to another agent."""
    target_agent: str
    reason: str
    context_updates: dict[str, Any] = field(default_factory=dict)

class BaseAgent:
    """Base class for specialist agents."""

def __init__(self, name: str, capabilities: list[str]) -> None:
        self.name = name
        self.capabilities = capabilities

def can_handle(self, task_type: str) -> bool:
        """Check if this agent can handle the given task type."""
        # TODO: check against capabilities
        raise NotImplementedError

def handle(self, context: HandoffContext) -> AgentResult:
        """Process a task. Override in subclasses."""
        raise NotImplementedError

class Coordinator:
    """Routes tasks to specialist agents and aggregates results."""

def __init__(self, agents: list[BaseAgent], max_handoff_depth: int = 5) -> None:
        self.agents = {agent.name: agent for agent in agents}
        self.max_handoff_depth = max_handoff_depth

def route(self, task_type: str) -> BaseAgent | None:
        """Find the best agent for a task type."""
        # TODO: match task_type against agent capabilities
        raise NotImplementedError

def execute(self, task_description: str, task_type: str) -> AgentResult:
        """Execute a task through the agent network."""
        # TODO: create HandoffContext
        # TODO: route to initial agent
        # TODO: handle handoff chain up to max_handoff_depth
        # TODO: aggregate results
        raise NotImplementedError

Practice

Generate a variation

Generate a new exercise variation to deepen understanding or practice a related concept.

Attempt history

Recent submissions

Before you submit, decide what a strong answer should make obvious to the reviewer.

No attempts yet.