Dynamic Map-Reduce via Send API

Overview

What changes, why it matters, and when to migrate.

Option 1 implements the VC Deep Research Agent using LangGraph's Send API for dynamic map-reduce dispatch. The pipeline is functionally identical to Option 2 — same state schema, same agents, same report output, same Azure deployment.

The one capability Option 1 adds is meaningful: optional agents can be skipped entirely per-run based on data availability. In Option 2, all 8 agents always execute — optional ones return no_data. In Option 1, skipped agents are never dispatched — no node execution, no tool calls, no latency.

What Option 1 Adds

• True dynamic skipping: a name-only run dispatches 4–5 agents instead of 8 — skipped agents contribute zero latency
• Per-run agent selection: Market, Legal, and Financial can be enabled or disabled at run time without graph changes
• Leaner graph definition: ~8 lines of wiring replaces ~20 lines of addEdge() calls
• No agent rewrites: all 8 agent files carry forward unchanged from Option 2

Key Differences from Option 2

Side-by-side comparison of every dimension that changes.

Architecture & Graph Topology

The critical change: orchestrator returns a Send[] list instead of dispatching unconditionally.

The Orchestrator Node (the change that matters)

// orchestrator.ts (Option 1 — replaces Option 2's unconditional dispatch)
import { Send } from "@langchain/langgraph";

function orchestrate(state: ResearchState): Send[] {
  // Fan out only to agents in enabledAgents — others are never dispatched
  return state.enabledAgents
    .filter(name => name !== "claims")   // Claims dispatched after checkpoint
    .map(name => new Send(name, state));
}

graph.addConditionalEdges(
  "orchestrator",
  orchestrate,
  [...agentNames]  // all possible target nodes must be declared at build time
);

Graph Topology (runtime, all agents enabled)

Checkpoint Node (replaces Barrier)

In Option 2, a static barrier waits for all 7 first-wave agents. In Option 1, a checkpoint node receives the merged partial state from all dispatched first-wave agents and re-dispatches Claims:

// checkpoint.ts — replaces barrier.ts
function checkpointNode(state: ResearchState): Send[] {
  // All dispatched first-wave agents have written — Claims can now run
  return [new Send("claims", state)];
}

graph.addConditionalEdges("checkpoint", checkpointNode, ["claims"]);

Dynamic Agent Skipping

How enabledAgents is determined and which runs benefit most.

Skipping Logic

// orchestrator.ts — building enabledAgents before dispatching
function buildEnabledAgents(
  profile: CompanyProfile,
  rawInput: RawInput,
  options: RunOptions
): AgentName[] {
  const required: AgentName[] = ["company", "founders", "digital", "news"];

  // Claims requires claimedMetrics — skip on pure name-only input
  if (rawInput.type !== "name" || profile.domain) {
    required.push("claims");
  }

  const optional: AgentName[] = [
    ...(options.includeMarket   ? ["market"]    : []),
    ...(options.includeLegal    ? ["legal"]     : []),
    // Financial data is rarely public for pre-seed — skip unless explicitly requested
    ...(options.includeFinancial && profile.stage !== "pre-seed" ? ["financial"] : []),
  ];

  return [...required, ...optional];
}

Skipping Scenarios

State Schema Changes

Identical to Option 2 — one behavioural difference only.

The ResearchState interface is identical to Option 2. The only difference is how enabledAgents is populated at runtime:

Optional result fields (marketFindings, legalFindings, financialFindings) remain null when the corresponding agent is skipped. The Reducer handles null identically in both options — no Reducer changes required.

Graph Wiring

The only file that changes — replacing Option 2's addEdge() block entirely.

// graph.ts (Option 1 — replaces Option 2 wiring block entirely)
import { Send } from "@langchain/langgraph";

const agentNames: AgentName[] = [
  "company", "founders", "market", "digital", "news", "legal", "financial"
];

// Dynamic fan-out: orchestrator returns Send[] at runtime
graph.addConditionalEdges("orchestrator", orchestrate, agentNames);

// All dispatched first-wave agents converge at checkpoint
agentNames.forEach(a => graph.addEdge(a, "checkpoint"));

// Checkpoint re-dispatches Claims after all first-wave agents write
graph.addConditionalEdges("checkpoint", checkpointNode, ["claims"]);

// Sequential tail — unchanged from Option 2
graph.addEdge("claims", "reducer");
graph.addEdge("reducer", "report");

Line count: Option 2 wiring is ~20 lines (10 addEdge() calls). Option 1 wiring is ~8 lines.

Files Added / Removed

Migration Path from Option 2

Prerequisites, steps, and rollback procedure.

Prerequisites — confirm all before migrating

• All 8 agents passing tests on real deal data (not just mocks)
• no_data paths for Market, Legal, Financial confirmed clean in Reducer
• Barrier node pattern validated — Claims consistently sees complete state from all 7 first-wave agents
• LangGraph version confirmed ≥ 0.2 in production Container App
• Team has LangSmith / LangGraph Studio access for runtime topology inspection
• Dynamic skipping measured to meaningfully reduce latency or tool costs (measure before migrating)

Migration Steps

1. Add import { Send } from "@langchain/langgraph" to orchestrator.ts and graph.ts
2. Write buildEnabledAgents() in orchestrator.ts
3. Write src/checkpoint.ts (replaces barrier.ts)
4. Replace the addEdge() block in graph.ts with Option 1 wiring (see §6)
5. Delete barrier.ts; register checkpointNode in graph
6. Update tests: add cases for name-only runs (Claims skipped), pre-seed runs (Financial skipped)
7. Run full test suite — all existing tests must pass unchanged
8. Deploy to staging; run 3+ real deals comparing Option 1 vs Option 2 output

Rollback

If Option 1 produces unexpected behaviour, rollback is restoring the 20-line addEdge() block in graph.ts and reverting to barrier.ts. No agent files, no Reducer, no frontend changes required.

Runtime Behaviour Differences

What changes at runtime and what the VC sees.

SSE Event Stream

agent_started and agent_done events are only emitted for dispatched agents. The VC's progress bar shows fewer agents completing on skipped runs — this is correct and expected. The report gracefully omits sections for null results, identical to Option 2's no_data treatment.

Cosmos DB State

Skipped agents leave their result fields as null in ResearchState. Option 2 fills those fields with { status: "no_data", ... } objects. Net effect on storage: negligible.

Execution Timing

First-wave agents still run in parallel. The only timing difference: skipped agents contribute zero latency (no node initialization, no tool calls, no LangGraph overhead).

Open Questions

Issues specific to Option 1 that require resolution before migration.

References

• option2.html — Option 2 (Fixed Branches) full specification; build this first
• Foundation/technical_draft/source/design-spec.md — source design spec (both options)
• Foundation/technical_draft/implementation-plans/plan-a-core-pipeline.md — Plan A implementation tasks
• Foundation/technical_draft/implementation-plans/plan-b-azure-integration.md — Plan B Azure integration
• Foundation/technical_draft/implementation-plans/plan-c-report-frontend.md — Plan C report frontend