reopt-context-routing

---
name: reopt-context-routing
description: When the scope of context transferred during an inter-agent handoff is unclear. Designing the logic that passes conversation history and intermediate results to the next agent. When token cost explodes or response quality degrades from context pollution.
---

# Context Routing

OCLS phase: **LAYER** · Design information flow so each participant receives exactly what it needs.

## Core rules

- Declare explicitly, per agent, which context items its responsibility requires.
- At handoff, filter and structure context against "what does this agent need to know right now."
- Add a verification rule that refuses the handoff when a required item is missing.
- Account for the LLM's attention budget and context rot — maximize the desired outcome with the smallest high-signal token set.
- Apply progressive disclosure — don't load everything at once; navigate to what's needed.

## Judgment question

**What must this agent not be unaware of right now?**

## Application check

1. What is the minimum context the receiving agent needs to decide?
2. Is the transfer format structured (JSON, schema)?
3. Have unnecessary history and metadata been removed?
4. What happens when a required item is missing?

## Code example

```typescript
// ❌ Forward the full conversation as-is — 3× the token cost, context pollution
responseAgent.handle({ fullHistory: conversation });

// ✅ Structured handoff payload sized to the receiving agent's responsibility
interface IntakeToResponse {
  category: "shipping-delay" | "refund" | "general";
  sentiment: "neutral" | "frustrated" | "satisfied";
  keyFacts: string[];         // 3–5 facts needed for the decision
  priorResolutions: string[]; // summary of prior attempts
  // The raw conversation history is not forwarded.
}

function filterForResponse(c: Conversation): IntakeToResponse {
  return {
    category: c.classification.category,
    sentiment: c.sentiment.latest,
    keyFacts: extractFacts(c).slice(0, 5),
    priorResolutions: summarize(c.actions),
  };
}

const payload = filterForResponse(conversation);
if (payload.keyFacts.length === 0) throw new HandoffRejected("no keyFacts");
responseAgent.handle(payload);
```

## Antipatterns

**Customer support**: forwarding the full conversation history to every agent makes the Response Agent overreact to old complaints and offer unnecessary compensation. Context pollution degrades quality quietly, which makes root cause hard to find.

**Search systems**: in a retrieve → rerank → summarize pipeline, forwarding the full source documents at every stage causes token cost to compound. Filter each stage down to the fields it needs (scores, metadata, snippets).

## Invocation example

```
"Apply Context Routing to the Intake → Response handoff.
We're currently forwarding the full conversation history. Define a structured
payload type that includes only the fields Response needs to decide."
```

## Related patterns

- Responsibility Partitioning — the responsibility boundary is the basis for the context filter
- State and Memory Control — rules for transferring short-term state vs long-term memory