Designing a Manager-Worker Agent...

A manager-worker system separates decomposition and reconciliation from bounded task execution. The manager should assign typed work units and apply acceptance rules; it should not become an all-powerful agent with every credential.

After this lesson, you can define task envelopes, worker leases, result schemas, and a controlled commit stage.

Create the Task Envelope

{
  "task_id": "catalog-2026-0719-0042",
  "tenant_id": "shop_12",
  "task_type": "review_product_copy",
  "input_refs": ["sku:A14", "policy:v8"],
  "allowed_tools": ["read_product", "read_policy"],
  "deadline": "2026-07-19T12:00:00Z",
  "max_attempts": 2,
  "output_schema": "product_review_v2"
}

Reference authorized data rather than copying a customer database into each task. Sign or protect queue messages where the infrastructure requires it.

Lease Work Safely

A worker claims a task for a limited lease. It heartbeats while active. If the lease expires, another worker may retry with the same task ID and idempotency keys. Workers cannot create new task types or expand tool scope.

Return status, output, evidence references, usage, and error class:

COMPLETED | NEEDS_REVIEW | RETRYABLE_FAILED | PERMANENT_FAILED

The manager validates schema and evidence. A separate commit service applies approved changes with its own authorization.

Prevent Recursive Explosion

Set maximum depth, number of workers, tasks per run, turns per worker, tool calls, tokens/cost, elapsed time, and retries. A worker cannot spawn more workers unless explicitly allowed by a bounded plan. Reject duplicate task identities.

Worked Example

A Rawalpindi accounting firm reviews monthly expense descriptions. The manager creates one task per document reference; workers can read a redacted document and account-code policy, then propose a category with evidence. They cannot post to the ledger.

The manager validates every output. High-confidence routine proposals enter a reviewer queue; low-confidence or policy-conflict cases go to an accountant. Only the accounting service posts after approval. If a worker lease expires, another worker resumes the same task without duplicating the ledger entry.

Failure Cases to Diagnose

Manager holds all secrets: issue scoped identities at execution time.
Work item contains raw sensitive documents: use authorized references.
Two workers commit the same result: separate proposal from idempotent commit.
Worker creates arbitrary subtasks: enforce allowed types and depth.
Manager merges prose inconsistently: validate a versioned schema.
Lease expires during a long tool call: heartbeat and make effects idempotent.
No terminal failure: cap attempts and route to a human.

🇵🇰 Pakistan Angle

For accounting, payroll, medical, legal, lending, hiring, or public-sector work, workers should prepare evidence, not make final professional or rights-affecting decisions. Obtain the appropriate qualified reviewer and preserve the source record.

Queue systems must tolerate intermittent services without double-posting payments, orders, or customer messages. Use PKT deadlines for human operations but UTC timestamps internally, and display both where cross-border staff are involved.

Hands-On Exercise

Define a versioned task envelope and result schema.
Specify lease, heartbeat, retry, and terminal failure.
Separate manager, worker, reviewer, and commit permissions.
Add depth, count, cost, and time budgets.
Test lease expiry, duplicate task, invalid output, and partial commit.

Done means: workers can fail or repeat without duplicate effects, and only a separately authorized commit stage changes business state.

Completion Rubric

Task inputs are authorized references.
Leases and heartbeats support safe recovery.
Outputs use a versioned schema and evidence.
Recursive work has hard limits.
Proposals and commits use separate permissions.
Terminal failures reach a named human queue.

Sources

Key takeaway: managers assign bounded, typed work; workers propose evidence-backed results; only an idempotent, authorized commit path creates effects.

Designing a Manager-Worker Agent Pattern

Turn this lesson into one checked practice output