---
title: "The Docs Expert · example of Heavy Agent · Agentic Atlas"
description: "The Docs Expert: an agent with large docs built in, so the orchestrator asks instead of loading them."
canonical: "https://agentic-atlas.dev/nodes/docs-expert-agent"
last-updated: "2026-09-23"
---

1. [Agentic Atlas](https://agentic-atlas.dev/)
2. [Patterns in the Agentic Atlas](https://agentic-atlas.dev/atlas)
3. [Cost Relocation](https://agentic-atlas.dev/nodes/cost-relocation)
4. [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload)
5. [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)
6. The Docs Expert
1. example of [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)
   # The Docs Expert
   **How can an orchestrator get one fact from large docs without loading them into its context?**
   In this example, asking a docs-built-in agent costs the orchestrator about 250 tokens for question and answer, versus about 8,000 loaded inline.
   Hook
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Laws & fences
   - What makes it a heavy agent is weight written into its definition, not material gathered at runtime.
   - The built-in reference can go stale, so the agent file must be updated when the underlying docs change.
   - A docs expert answers from docs written into its definition, while a librarian agent fetches raw slices at runtime.
   - Each new dispatch reloads the reference in a fresh subagent, but the orchestrator still never carries it.
   - Shaping or checking the answer on its way back belongs to other patterns, not this one.
   When to reach
   - Reach for this when an orchestrator needs one fact from a large reference it would otherwise load whole.
   - Skip this when the reference outgrows a context window or changes faster than you would update the agent file.
   Provenance
   [docs-expert-agent/implementation-the-dispatch](https://agentic-atlas.dev/nodes/docs-expert-agent#implementation-the-dispatch) · v1.0.11
   Addresses
   atlas_cards docs-expert-agent
2. [Reference Data](https://agentic-atlas.dev/nodes/reference-data)
3. [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)
4. [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload)
5. [Parallel Audit Investigation](https://agentic-atlas.dev/nodes/parallel-audit-investigation)
6. [The Contract](https://agentic-atlas.dev/nodes/contract-documentation)
7. [Cost Relocation](https://agentic-atlas.dev/nodes/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

On this plate

[context-the-setup](https://agentic-atlas.dev/nodes/docs-expert-agent#context-the-setup) [problem-signal](https://agentic-atlas.dev/nodes/docs-expert-agent#problem-signal) [choice-why-it-s-a-heavy-agent-not-just-subagent-offload](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) [before-the-reference-read-into-the-orchestrator-s-window](https://agentic-atlas.dev/nodes/docs-expert-agent#before-the-reference-read-into-the-orchestrator-s-window) [implementation-the-dispatch](https://agentic-atlas.dev/nodes/docs-expert-agent#implementation-the-dispatch) [result-the-economics-made-visible](https://agentic-atlas.dev/nodes/docs-expert-agent#result-the-economics-made-visible) [verification-what-this-example-deliberately-leaves-out](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) [lessons-the-expert-not-the-librarian](https://agentic-atlas.dev/nodes/docs-expert-agent#lessons-the-expert-not-the-librarian) [relationships](https://agentic-atlas.dev/nodes/docs-expert-agent#relationships)

Every section is addressable on its own. Read only the ground you need.

## Context — the setup

[Permalink to Context — the setup section](https://agentic-atlas.dev/nodes/docs-expert-agent#context-the-setup)

Bake a large reference into an [agent definition](https://agentic-atlas.dev/glossary/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

[Permalink to Problem signal section](https://agentic-atlas.dev/nodes/docs-expert-agent#problem-signal)

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](https://agentic-atlas.dev/glossary/window-context-window), the whole reference has to be admitted to reach the part that answers it.

## Choice — why it's a \*heavy\* agent (not just subagent offload)

[Permalink to Choice — why it's a \*heavy\* agent (not just subagent offload) section](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload)

The defining weight here is **authored** — the baked-in reference — exactly [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)'s defining feature, not a runtime sweep (contrast [Parallel Audit Investigation](https://agentic-atlas.dev/nodes/parallel-audit-investigation) under [Subagent Offload](https://agentic-atlas.dev/nodes/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.

## Before — the reference read into the orchestrator's window

[Permalink to Before — the reference read into the orchestrator's window section](https://agentic-atlas.dev/nodes/docs-expert-agent#before-the-reference-read-into-the-orchestrator-s-window)

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](https://agentic-atlas.dev/glossary/workflow).

## Implementation — the dispatch

[Permalink to Implementation — the dispatch section](https://agentic-atlas.dev/nodes/docs-expert-agent#implementation-the-dispatch)

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

## Result — the economics, made visible

[Permalink to Result — the economics, made visible section](https://agentic-atlas.dev/nodes/docs-expert-agent#result-the-economics-made-visible)

| 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](https://agentic-atlas.dev/glossary/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.

## Verification — what this example deliberately leaves out

[Permalink to Verification — what this example deliberately leaves out section](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out)

How the answer is shaped or verified on the way back. That is the **[return](https://agentic-atlas.dev/glossary/return) boundary** — owned by [The Contract](https://agentic-atlas.dev/nodes/contract-documentation) / *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.

## Lessons — the expert, not the librarian

[Permalink to Lessons — the expert, not the librarian section](https://agentic-atlas.dev/nodes/docs-expert-agent#lessons-the-expert-not-the-librarian)

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](https://agentic-atlas.dev/nodes/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](https://agentic-atlas.dev/nodes/heavy-agent)
   subagents that carry heavy baked-in instructions the orchestrator never loads
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 1
2. in-slice · occurrence 2
   [Parallel Audit Investigation](https://agentic-atlas.dev/nodes/parallel-audit-investigation)
   a full investigation's working set stays in another agent's window; only its verdict returns
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 2
3. in-slice · occurrence 3
   [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload)
   handing work to a subagent so its material never fills the orchestrator's context
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 3
4. in-slice · occurrence 1
   [The Contract](https://agentic-atlas.dev/nodes/contract-documentation)
   the agreement on an artifact's shape and use whenever one component hands it to another
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 1
5. undisclosed · occurrence 2
   Undisclosed relationship
   the travelling declared-shape contract specialization
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · 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](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 3
7. in-slice · occurrence 1
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data)
   a reference corpus too big to load into the context window at any price
   Evidence: [Lessons](https://agentic-atlas.dev/nodes/docs-expert-agent#lessons-the-expert-not-the-librarian) · occurrence 1

### Inbound references 5

1. in-slice · occurrence 1
   [Cost Relocation](https://agentic-atlas.dev/nodes/cost-relocation#examples)
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Evidence: [Examples](https://agentic-atlas.dev/nodes/cost-relocation#examples) · occurrence 1
2. in-slice · occurrence 1
   [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent#examples)
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Evidence: [Examples](https://agentic-atlas.dev/nodes/heavy-agent#examples) · occurrence 1
3. in-slice · occurrence 2
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data#examples)
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Evidence: [Examples](https://agentic-atlas.dev/nodes/reference-data#examples) · occurrence 2
4. in-slice · occurrence 5
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data#relationships)
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/reference-data#relationships) · occurrence 5
5. in-slice · occurrence 2
   [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload#examples)
   an agent with large docs built in, so the orchestrator asks instead of loading them
   Evidence: [Examples](https://agentic-atlas.dev/nodes/subagent-offload#examples) · occurrence 2

[↑ back to the top](https://agentic-atlas.dev/nodes/docs-expert-agent#content) [← the survey](https://agentic-atlas.dev/atlas)

Node docs-expert-agent · corpus 78c0e17 · Catalog revision e0cb75881244b1a82193ca738b82a0d508dd62e822524ae82873ec79d51dbb61