Handbook Agents

Overview

Handbook agents are package-owned under packages/domain-handbook/src/agents/** and use the shared agent factory pattern from @maf/platform-runtime/agents/shared/index.

The Handbook package currently registers seven agents:

Agent	Profile ID	Registry ID	Functional group	Tools
Handbook Product Agent	handbook-product-agent	handbook_product-agent	Product Workflows	handbook-search-policy-evidence, handbook-generate-verified-answer
Handbook Source Context Synthesis Agent	handbook-source-context-synthesis-agent	handbook_source-context-synthesis-agent	Source Context	none
Handbook Policy Evidence Gate Agent	handbook-policy-evidence-gate-agent	handbook_policy-evidence-gate-agent	Policy Review	none
Handbook Policy Reconciliation Agent	handbook-policy-reconciliation-agent	handbook_policy-reconciliation-agent	Policy Review	none
Handbook Checklist Verifier Agent	handbook-policy-checklist-verifier-agent	handbook_policy-checklist-verifier-agent	Policy Review	none
Handbook Remediation Drafter Agent	handbook-policy-remediation-drafter-agent	handbook_policy-remediation-drafter-agent	Policy Review	none
Handbook Evidence Synthesis Agent	handbook-policy-evidence-synthesis-agent	handbook_policy-evidence-synthesis-agent	Policy Review	none

Source: packages/domain-handbook/src/agents/index.ts.

Handbook Product Agent

The product agent is a thin adapter over Handbook product-owned tools. Its prompt tells the agent to use only attached Handbook tools for product data and not to invent policy evidence.

Primary use cases:

• inspect and run product workflows
• search policy evidence through the product retrieval contract
• generate verified answer packages grounded in retrieved evidence
• preserve product contract boundaries when called from Admin or route adapters

Source: packages/domain-handbook/src/agents/handbook-product-agent.ts.

Source Context Synthesis Agent

The source-context agent converts cited handbook evidence into structured, provenance-preserving data-point answers. The handbook.extract-source-context.v1 workflow persists those answers as source context memory so later generation and checklist review can reuse uploaded handbook facts without treating them as authoritative policy.

Source: packages/domain-handbook/src/agents/handbook-source-context-agent.ts.

Policy Evidence Gate Agent

The evidence gate agent is scoped to policy review. It decides whether retrieved MSBA policy evidence is plausibly relevant to a handbook segment.

It should:

• select policy evidence only when it can govern, contradict, permit, or constrain the handbook language
• reject weak or off-topic evidence
• treat missing evidence as unresolved review work, not proof that the handbook is wrong
• return only the requested structured JSON

Source: packages/domain-handbook/src/agents/handbook-policy-review-agents.ts.

Checklist, Remediation, And Evidence Synthesis Agents

The remaining policy-review agents separate three reviewer-facing concerns:

• the checklist verifier compares one checklist requirement with cited handbook evidence and reports satisfied, missing, or unverifiable coverage;
• the remediation drafter proposes human-reviewable handbook wording for missing or partial findings and must not present draft text as evidence;
• the evidence synthesis agent turns already-selected evidence into clear reviewer blocks while preserving caveats about weak, truncated, or heading-only evidence.

All three are tool-less structured-output agents. They receive evidence and contracts from the policy-review runner rather than searching independently.

Source: packages/domain-handbook/src/agents/handbook-policy-review-agents.ts.

Policy Reconciliation Agent

The reconciliation agent compares cited handbook evidence with cited MSBA evidence after the evidence gate has selected plausible sources.

It should:

• mark contradicts_policy only for direct semantic conflict
• avoid treating local detail as a contradiction unless MSBA expressly forbids it
• use overstates_policy or needs_manual_review when the evidence is ambiguous
• ground suggested wording in cited evidence only
• return only the requested structured JSON

Source: packages/domain-handbook/src/agents/handbook-policy-review-agents.ts.

Registration And Discovery

buildHandbookAgents() configures and returns all seven agents in the Handbook agent registry. When the Handbook domain is enabled, runtime discovery exposes them through:

• GET /agents.json
• GET /handbook/routes.json
• generated /handbook/agents/{agentSlug}/generate and /handbook/agents/{agentSlug}/stream routes

Use /handbook/routes.json in the target environment for exact route slugs.

Related Docs

Handbook API

Route families that expose Handbook agents, tools, workflows, and Admin BFF behavior

Policy Review

Where evidence-gate and reconciliation agents fit in the review pipeline

Agent Prompt Overrides

Shared profile and prompt override mechanics

Unified Agent Platform

Shared descriptor/factory pattern used by Handbook agents