Multi-Agent Research Pipeline

Defines all shared data structures: AgentDefinition, ResearchTask, AgentResult, and ResearchReport. The AgentDefinition config pattern is the exam's primary tool design concept — it enforces least-privilege access at the structural level.

• AgentDefinition fields: name, role, system_prompt, allowed_tools (list), max_tokens, temperature — all configuration for one subagent type
• allowed_tools: company researcher gets ["web_search", "web_fetch"]; financial analyst gets ["web_search", "financial_data"]; market analyst gets ["web_search", "market_data"] — no agent can use tools outside its mandate
• ResearchTask fields: task_id, task_type, query, context (injected explicitly, not inherited), priority, max_retries
• AgentResult fields: task_id, agent_type, success, content, sources, coverage (full/partial/none), error_type (for failure analysis)

The SubagentExecutor class runs individual subagent tasks. The critical exam concept here is context isolation — each subagent is a fresh Claude instance that receives only its system prompt and the Task prompt. It has no memory of coordinator decisions, other subagents, or previous pipeline runs.

• Context isolation: no shared memory between subagents; coordinator state is invisible to subagents; each subagent starts fresh
• Explicit context injection: company_name, industry, focus areas are passed in the Task prompt text — not assumed from coordinator conversation history
• Context budget management: company_researcher max_tokens=4096 (broad coverage); financial_analyst max_tokens=2048 (structured data); market_analyst max_tokens=3072

# WRONG: assuming subagent inherits coordinator context
task_prompt = "Research the company's financials."

# RIGHT: inject all context explicitly in the Task prompt
task_prompt = f"""
Company: {company_name}
Industry: {industry}
Focus areas: revenue, growth rate, profitability
Task: Research recent financial performance.
Sources: SEC filings, earnings reports.
Return format: JSON with fields: revenue, growth, key_metrics
"""

The ResearchCoordinator is the hub. It orchestrates the pipeline: checks state, spawns parallel subagents via Task tool, waits for results, handles failures via the anti-abort pattern, then triggers synthesis. The exam's most tested D1 concept: parallel spawning and failure handling.

• Anti-abort pattern: if 1 of 3 subagents fails, coordinator uses the 2 successful results, annotates gaps, continues pipeline rather than rejecting all work done
• Failure triage: TRANSIENT errors (rate limit, timeout) → retry with exponential backoff; PERMISSION errors → skip with annotation; BUSINESS errors → annotate and continue
• State checkpoint: save results to manifest.json before synthesis so a crash during synthesis doesn't re-run subagent tasks
• Hub role: only the coordinator has the Task tool; subagents are workers with domain-specific tools only

# Parallel spawning — ALL Task calls in ONE response
# These run concurrently, not sequentially
results = await asyncio.gather(
    executor.run(company_task),   # Task call 1
    executor.run(market_task),    # Task call 2
    executor.run(financial_task), # Task call 3
    return_exceptions=True       # don't abort on single failure
)

Detects contradictions between subagent results for the same factual claim. When two sources disagree, the system preserves both values rather than silently resolving to one. This is the "epistemic honesty" principle — annotated uncertainty is better than false confidence.

• ConflictingClaim structure: field_name, value_a (with source_a, date_a), value_b (with source_b, date_b), conflict_type, recommended_action
• Temporal threshold: sources from the same year → flag as conflict; sources 1+ year apart → temporal_explanation (both may be correct at their respective times)
• 10% numeric threshold: small variation (<10%) for revenue/users = rounding differences, not a real conflict; large variation (>10%) = flag for review

Synthesizes results from all subagents into a ResearchReport. Implements coverage annotations for incomplete data and the "KEY FINDINGS at top, ACTION ITEMS at bottom" layout for long-context reliability.

• Lost-in-the-middle mitigation: KEY FINDINGS at top of report, ACTION ITEMS at bottom, CONFLICTS at top of relevant sections — the model attends to beginning and end of context most reliably
• Partial section annotation: "Company Overview [partial — financial_data agent failed; revenue data missing; market position data complete]"
• None annotation: "Regulatory Compliance [coverage: none — no relevant tool available for regulatory database lookup]"
• Human review trigger: any conflict → add to review_required list with explanation; any partial coverage on critical fields → flag

Fault-tolerant state management. Saves each agent's result to a per-agent JSON file and tracks completion in manifest.json. On resumption, completed tasks are skipped, failed/running tasks are restarted, and tasks not in the manifest run fresh — enabling cheap incremental recovery from crashes.

• manifest.json: top-level index of task IDs → status (completed/running/failed/not_started), timestamps, file paths to results
• Per-agent result files: results/{task_id}.json — complete AgentResult object, loaded on resume
• Resume logic: "completed" → skip and load from file; "running" → restart (crash during execution); "not in manifest" → run fresh
• Crash safety: save to file BEFORE updating manifest → prevents corrupted partial state

# Resume logic from manifest
for task_id, status in manifest.items():
    if status == "completed":
        results[task_id] = load_result(task_id)  # skip re-run
    elif status == "running":
        pending.append(task_id)  # crashed; restart
    # not in manifest → run fresh (appended to pending)

Pipeline configuration: max parallel agents (3), retry limits per agent (3), conflict numeric threshold (10%), temporal conflict threshold (365 days), output paths. The 3-agent parallel limit prevents API rate limiting while maximizing throughput for typical research pipelines.

• Increase max_parallel_agents for data pipelines with many independent tasks
• Lower numeric_conflict_threshold (e.g., 5%) for high-stakes financial analysis where small discrepancies matter
• Adjust temporal_conflict_threshold based on industry — fast-moving tech sectors may warrant 180 days

Demonstrates the pipeline on 3 scenarios: fresh run (all agents succeed), resume (simulated crash after 2 of 3 agents), and conflict detection (company researcher and financial analyst return conflicting revenue figures).

• Scenario 1 — fresh_run: TechCorp Inc., all 3 agents succeed, full coverage synthesis, no conflicts
• Scenario 2 — resume_after_crash: StartupXYZ, agents 1+2 complete and saved, agent 3 crashes → on resume, agents 1+2 loaded from disk, agent 3 re-executed
• Scenario 3 — conflict_detection: MegaCorp Ltd., company research says revenue $2.1B, financial agent says $3.4B → ConflictingClaim generated, flagged in report, human review required