Multi-Agent Coordination

Hierarchy Setup reportsTo

Example Agent Definitions

Three agent definition files establishing an orchestrator → manager → worker chain:

---
name: orchestrator
description: Top-level coordinator that breaks work into streams
model: opus
maxTurns: 50
---

You coordinate complex projects by breaking them into work streams
and delegating to specialized managers. You synthesize results from
managers into cohesive deliverables.

---
name: research-manager
description: Manages research tasks and coordinates research workers
model: sonnet
maxTurns: 30
reportsTo: orchestrator
skills:
  - github-operations
---

You manage research workflows. When given a research objective,
break it into focused tasks and delegate to research workers.
Aggregate findings into structured reports.

---
name: research-worker
description: Executes focused research tasks
model: haiku
maxTurns: 20
reportsTo: research-manager
skills:
  - github-operations
---

You execute focused research tasks. Gather information, analyze it,
and return structured findings to your manager.

Resulting Hierarchy

orchestrator          (root -- no reportsTo)
  |
  +-- research-manager  (reportsTo: orchestrator)
        |
        +-- research-worker  (reportsTo: research-manager)

The AgentRegistry.canDelegateTo(from, to) method validates that the target agent's reportsTo matches the delegating agent's name. See packages/core/src/agents/registry.ts.

Delegation Patterns Primitives

Maximus provides two coordination primitives:

How Delegation Works

The Delegator class (packages/core/src/delegation/delegator.ts) executes this sequence:

Fan-Out Parallel

const results = await Promise.all([
  delegator.delegate({
    fromAgent: "research-manager",
    toAgent: "worker-1",
    prompt: "Research topic A",
    traceId,
  }),
  delegator.delegate({
    fromAgent: "research-manager",
    toAgent: "worker-2",
    prompt: "Research topic B",
    traceId,
  }),
]);

Context Passing

const result = await delegator.delegate({
  fromAgent: "orchestrator",
  toAgent: "research-manager",
  prompt: `Analyze the quarterly report. Here is the summary from finance:

  ${financeResult.output}`,
  traceId,
});

Results Flow Back

Error Handling

Task Lifecycle States

State Machine

              +----------+
              |  created |
              +----+-----+
                   |
              +----v-----+
              | assigned  |
              +----+-----+
                   |
           +------v-------+
           | in-progress   |
           +---+-------+---+
               |       |
        +------v--+ +--v------+
        |completed| |  failed |
        +---------+ +---------+

Transitions are strictly enforced. The only valid paths are:

No skipping states. See packages/core/src/tasks/lifecycle.ts for the VALID_TRANSITIONS map.

Task Fields

Each task tracks these fields (defined in packages/shared/src/tasks.ts):

TaskStore API

The TaskStore class (packages/core/src/tasks/store.ts) provides:

Tasks are stored in-memory for v1. They are queryable via the REST API while the server is running.

Safety Budgets & Breakers

Token Budgets

await delegator.delegate({
  fromAgent: "orchestrator",
  toAgent: "research-manager",
  prompt: "...",
  traceId,
  budgetCeiling: 100000, // Max tokens for this entire chain
});

If the chain's accumulated usage reaches or exceeds the ceiling, BudgetExceededError is thrown.

Circuit Breakers

Two circuit breakers prevent runaway delegation:

When either limit is reached, CircuitBreakerError is thrown with the reason (max_depth or max_concurrent) and the current value.

Agent Write Lock

Error Types

import {
  HierarchyViolationError,
  CircuitBreakerError,
  BudgetExceededError,
} from "@maximus/core";

try {
  await delegator.delegate(request);
} catch (error) {
  if (error instanceof HierarchyViolationError) {
    // fromAgent cannot delegate to toAgent
  } else if (error instanceof CircuitBreakerError) {
    // error.reason: "max_depth" | "max_concurrent"
    // error.value: current depth or concurrent count
  } else if (error instanceof BudgetExceededError) {
    // error.used: tokens used so far
    // error.ceiling: configured ceiling
  }
}

Observability Tracing

Trace IDs

const traceId = nanoid(); // Generated once at root
await delegator.delegate({
  fromAgent: "orchestrator",
  toAgent: "manager",
  prompt: "...",
  traceId,
});
// All child tasks and events carry this traceId

Event Interface

Every AgentEvent (defined in packages/shared/src/events.ts) carries traceId and parentSessionId fields:

interface AgentEvent {
  id: string;
  timestamp: number;
  sessionId: string;
  agentName: string;
  type: AgentEventType;
  payload: Record<string, unknown>;
  traceId?: string;
  parentSessionId?: string;
}

Task Lifecycle Events

Events emitted by the Delegator:

Agent Session Events

Structured Logging

REST API Reference

Health Check

# GET /api/health
curl http://localhost:3000/api/health

Response:

{ "status": "ok", "timestamp": 1710936000000 }

List Tasks

# All tasks
curl http://localhost:3000/api/tasks

# Filter by trace ID
curl "http://localhost:3000/api/tasks?traceId=abc123"

# Filter by agent name
curl "http://localhost:3000/api/tasks?agentName=research-manager"

# Filter by status
curl "http://localhost:3000/api/tasks?status=completed"

# Combine filters
curl "http://localhost:3000/api/tasks?traceId=abc123&status=in-progress"

Response:

{
  "tasks": [
    {
      "id": "task_abc",
      "parentTaskId": null,
      "agentName": "research-manager",
      "status": "completed",
      "prompt": "Analyze the quarterly report",
      "result": "Key findings: ...",
      "traceId": "abc123",
      "tokenUsage": 1500,
      "createdAt": 1710936000000,
      "updatedAt": 1710936005000,
      "completedAt": 1710936005000
    }
  ]
}

Get Task by ID

# GET /api/tasks/:id
curl http://localhost:3000/api/tasks/task_abc

Response:

{
  "task": {
    "id": "task_abc",
    "agentName": "research-manager",
    "status": "completed",
    "prompt": "Analyze the quarterly report",
    "result": "Key findings: ...",
    "traceId": "abc123",
    "tokenUsage": 1500,
    "createdAt": 1710936000000,
    "updatedAt": 1710936005000,
    "completedAt": 1710936005000
  }
}

Returns 404 if the task does not exist.

List Agents

# GET /api/agents
curl http://localhost:3000/api/agents

Response:

{
  "agents": [
    {
      "name": "orchestrator",
      "description": "Top-level coordinator",
      "model": "opus",
      "skills": []
    },
    {
      "name": "research-manager",
      "description": "Manages research tasks",
      "model": "sonnet",
      "reportsTo": "orchestrator",
      "skills": ["github-operations"]
    }
  ]
}

Get Org Chart

# GET /api/agents/org-chart
curl http://localhost:3000/api/agents/org-chart

Response:

{
  "agents": [
    { "name": "orchestrator", "description": "Top-level coordinator" },
    { "name": "research-manager", "reportsTo": "orchestrator", "description": "Manages research tasks" },
    { "name": "research-worker", "reportsTo": "research-manager", "description": "Executes research tasks" }
  ]
}

WebSocket Event Streaming Real-time

Connecting

# Using wscat
wscat -c ws://localhost:3000/ws

Frame Format

All messages are JSON frames with the WebSocketFrame structure (packages/server/src/ws/frames.ts):

interface WebSocketFrame {
  type: "event" | "connected" | "error";
  event?: string;       // Event type (for "event" frames)
  payload: Record<string, unknown>;
  seq: number;          // Sequential frame number
}

Welcome Frame

On connection, clients receive a welcome frame:

{
  "type": "connected",
  "payload": { "message": "Connected to Maximus event stream" },
  "seq": 0
}

Event Frames

Task and agent events are delivered as frames with sequential numbering:

{
  "type": "event",
  "event": "task:created",
  "payload": {
    "id": "evt_abc",
    "timestamp": 1710936000000,
    "sessionId": "",
    "agentName": "research-manager",
    "type": "task:created",
    "payload": { "taskId": "task_abc", "parentTaskId": null },
    "traceId": "abc123"
  },
  "seq": 1
}

Sequential Numbering

Backpressure Handling

Client-Side Filtering

The server broadcasts all events to all connected clients. Filter on the client side by inspecting the payload fields:

const ws = new WebSocket("ws://localhost:3000/ws");

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);
  if (frame.type !== "event") return;

  // Filter by trace ID
  if (frame.payload.traceId === "abc123") {
    console.log(`[${frame.event}]`, frame.payload);
  }

  // Filter by agent name
  if (frame.payload.agentName === "research-manager") {
    console.log(`[${frame.event}]`, frame.payload);
  }
};

Quick Start Example End-to-End

1. Define Agents

2. Start the Server

import { AgentEngine } from "@maximus/core";
import { createApp } from "@maximus/server";

const engine = new AgentEngine({
  agentsDir: "./agents",
  skillsDir: "./skills",
});
await engine.initialize();

const { server } = createApp(engine);
server.listen(3000, () => {
  console.log("Maximus running on http://localhost:3000");
});

3. Delegate Work

import { nanoid } from "nanoid";

const delegator = engine.getDelegator();
const traceId = nanoid();

const result = await delegator.delegate({
  fromAgent: "orchestrator",
  toAgent: "research-manager",
  prompt: "Research the top 3 competitors and summarize their strengths",
  traceId,
});

console.log("Result:", result.output);

4. Query via REST API

# Check all tasks in the delegation chain
curl "http://localhost:3000/api/tasks?traceId=${TRACE_ID}"

# View the org chart
curl http://localhost:3000/api/agents/org-chart

# Check system health
curl http://localhost:3000/api/health

5. Observe via WebSocket

# Stream events in real-time
wscat -c ws://localhost:3000/ws

You will see frames for task:created, task:assigned, session:start, agent:message, task:completed, and more — all carrying the traceId for correlation.

Related Documentation