Agentic Atlas patterns for agentic design
current field map

← the survey

  1. example of Heavy Agent

    The Docs Expert

    Hook

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Thesis

    A large reference of about 8k tokens is baked into an agent definition whose narrow job is answering questions about it accurately; the orchestrator sends one question and gets back a distilled answer, and never reads the reference into its own window.

    Laws & fences

    • The defining weight is authored, the baked-in reference, which is what makes this a heavy agent rather than a runtime sweep; the same authored weight can go stale, so when the underlying docs change the agent file must be maintained.
    • Loading the full reference inline costs the orchestrator's window about 8,000 tokens that stay and crowd the rest of the workflow; dispatching the docs expert costs about 250 tokens for the question and the distilled answer, while the 8k burns in the subagent's fresh window.
    • Dispatching again for another fact reloads the reference in a fresh sub-window, a per-dispatch fixed cost, but the orchestrator still never carries the 8k.
    • How the answer is shaped or verified on the way back is the return boundary, owned by neighboring patterns, contract-documentation among them, rather than by this pattern; the heavy agent ends at the offload.

    When to reach

    • Reach for it when an orchestrator mid-task needs one fact out of a large reference and answering from its own window would mean admitting the whole reference to reach the part that answers it.
    • Skip it when the reference outgrows a window or churns faster than you would re-author the agent file; that case is reference-data's territory rather than this pattern's, served by the librarian, a subagent composed with reference-data that fetches the relevant volume at runtime and returns the raw slice rather than a distilled answer.

  2. Reference Data

  3. Heavy Agent

  4. Subagent Offload

  5. Parallel Audit Investigation

  6. The Contract

  7. Cost Relocation

  8. field notes

    • “the travelling declared-shape contract specialization”

    • “validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied”

The card, in place · its connections drawn edges from atlas_links docs-expert-agent

Contextthe setup

context-the-setup.md

Bake a large reference into an agent definition — an API spec, a library's docs, an internal system's manual. Call it ~8k tokens of authored weight: endpoints, parameters, version notes, gotchas, worked snippets. The agent's job is narrow: answer questions about that reference accurately.

(One concrete instantiation: a "Claude-API expert" agent with model IDs, pricing, params, streaming, tool use, and caching baked in. The teaching is the generic move, not the specific docs — swap in any large reference.)

Problem signal

problem-signal.md

An orchestrator is mid-task and needs one fact:

"What's the current model ID for the top-tier model, and how do I enable prompt caching?"

One fact, out of ~8k of reference. Answered from the orchestrator's own window, the whole reference has to be admitted to reach the part that answers it.

Choicewhy it's a *heavy* agent (not just subagent offload)

choice-why-it-s-a-heavy-agent-not-just-subagent-offload.md

The defining weight here is authored — the baked-in reference — exactly Heavy Agent's defining feature, not a runtime sweep (contrast Parallel Audit Investigation under Subagent Offload). Same offload mechanic, authored heaviness. That authored weight is also what can go stale: when the underlying docs change, the agent file must be maintained.

Beforethe reference read into the orchestrator's window

before-the-reference-read-into-the-orchestrator-s-window.md

The shape being replaced is the obvious one: the orchestrator reads the reference in. All ~8k of authored weight lands in its own window — and it stays there, crowding the rest of the workflow.

Implementationthe dispatch

implementation-the-dispatch.md

It invokes the docs expert by type with just that question. It does not read the reference into its own window.

Resultthe economics, made visible

result-the-economics-made-visible.md
Approach Orchestrator window cost
Load the full reference inline ~8,000 tokens — and it stays, crowding the rest of the workflow
Dispatch the docs expert ~250 tokens — question + distilled answer

The 8k of authored weight burns in the subagent's fresh window — for free from the orchestrator's side. The orchestrator's context grows only by the question and the answer. Dispatch again for another fact and the reference reloads in a fresh sub-window (per-dispatch fixed cost — Tradeoff #1), but the orchestrator still never carries the 8k.

Verificationwhat this example deliberately leaves out

verification-what-this-example-deliberately-leaves-out.md

How the answer is shaped or verified on the way back. That is the return boundary — owned by The Contract / the travelling declared-shape contract specialization / validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied neighbors, not by this pattern. Heavy agent ends at the offload.

Lessonsthe expert, not the librarian

lessons-the-expert-not-the-librarian.md

Two service counters answer questions about a big reference, and this example is only one of them. The expert has the material in their head — authored into the agent definition — and answers from it; nothing is fetched. The librarian has memorized nothing: they know where everything is and fetch you the relevant volume at runtime. In tree terms the librarian is a subagent composed with Reference Data — pay-later machinery running inside a pay-elsewhere window — and you get back the raw slice, not a distilled answer. Reach for the librarian when the reference outgrows a window, or churns faster than you'd re-author the agent file; that case is reference-data's territory (its declared too-big-to-frontload example), not this pattern's.

The relationships ledger

Evidence-bearing references

Relationships

Every connection keeps the section where it was found. The map above orients; this ledger carries the evidence.

Outbound references 7

  1. in-slice · occurrence 1

    Heavy Agent

    the authored-heavy specialization

    Evidence: Choice · occurrence 1

  2. in-slice · occurrence 2

    Parallel Audit Investigation

    a full agent investigates in parallel; its working set stays elsewhere and only the verdict returns

    Evidence: Choice · occurrence 2

  3. in-slice · occurrence 3

    Subagent Offload

    the dispatch-elsewhere branch

    Evidence: Choice · occurrence 3

  4. in-slice · occurrence 1

    The Contract

    expectations at a seam, from informal prose to enforced structure

    Evidence: Verification · occurrence 1

  5. undisclosed · occurrence 2

    Undisclosed relationship

    the travelling declared-shape contract specialization

    Evidence: Verification · occurrence 2

  6. undisclosed · occurrence 3

    Undisclosed relationship

    validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied

    Evidence: Verification · occurrence 3

  7. in-slice · occurrence 1

    Reference Data

    the authored-heavy specialization: disk-resident, grep-addressable — pay for the size of the answer

    Evidence: Lessons · occurrence 1

Inbound references 5

  1. in-slice · occurrence 1

    Cost Relocation

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Evidence: Examples · occurrence 1

  2. in-slice · occurrence 1

    Heavy Agent

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Evidence: Examples · occurrence 1

  3. in-slice · occurrence 2

    Reference Data

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Evidence: Examples · occurrence 2

  4. in-slice · occurrence 5

    Reference Data

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Evidence: Relationships · occurrence 5

  5. in-slice · occurrence 2

    Subagent Offload

    a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs

    Evidence: Examples · occurrence 2

↑ back to the top ← the survey

Node docs-expert-agent · corpus 31de4cb · Catalog revision 35263c4c415da742953d0462804fb14424e2244dae4c63efd27e468988de70ab