Context-First Agent Design for Content Operations at Scale

sanity · Tech · 2026 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.6 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Content operations over structured CMS data

Sanity needed a Content Agent that could audit, generate, edit, update, export, and mutate large structured content collections without drowning the model in schemas, tool choices, or raw document payloads. Early tool proliferation made the agent less consistent and worse at choosing what to do.

Constraints:

Sanity customers can have hundreds of content types and tens or hundreds of thousands of documents.
Real schemas can include many document types, nested objects, arrays, references, validations, and reusable object types.
Large query results cannot all be pushed into the main context window.
Mutation is risky because Sanity documents are nested and machine-shaped for live collaboration.
The user must be able to verify the set and action before expensive or risky work runs.

Architecture

Sanity shifted from adding more tools to shaping context: show compressed schema shape first, represent large query results as reusable sets with metadata, use code to validate and repair model-drafted GROQ queries, keep one strong main agent with a few broad tools, and use specialized subagents only for clearly bounded mutation tasks.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  main-content-agent["Main content agent"] --> schema-shape-summary["Schema shape summary"]
  main-content-agent --> set-primitive["Set primitive"]
  set-primitive --> user-verification-ui["User verification UI"]
  main-content-agent --> groq-query-validator["GROQ query validator"]
  groq-query-validator --> execution-layer["Execution layer"]
  main-content-agent --> mutation-subagent["Mutation subagent"]
  mutation-subagent --> execution-layer
  set-primitive --> execution-layer

Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component	Role	Interacts with
`Main content agent`	Primary agent that orients, plans, queries, inspects sets, and coordinates content operations.	`Schema shape summary`, `Set primitive`, `GROQ query validator`, `Mutation subagent`, `User verification UI`
`Schema shape summary`	Compressed overview of document types, fields, references, and relationship hints.	`Main content agent`
`Set primitive`	Reusable handle to a large query result with metadata such as counts, ranges, type breakdowns, query, title, and description.	`Main content agent`, `User verification UI`, `Execution layer`
`GROQ query validator`	Code layer that parses, validates, inspects, repairs, serializes, and executes model-drafted GROQ queries.	`Main content agent`, `Execution layer`
`Mutation subagent`	Specialized subagent spawned with local schema/path/document context for difficult Sanity document mutations.	`Main content agent`, `Execution layer`
`Execution layer`	Runs expensive or risky actions: processing sets, mutating many documents, running code, or exporting files.	`Set primitive`, `GROQ query validator`, `Mutation subagent`
`User verification UI`	Lets the user inspect the set and verify that the agent is acting on the correct content slice.	`Set primitive`, `Main content agent`

Data flow

The agent first receives schema summaries and set metadata rather than full raw data. It queries into a set, inspects the set shape, verifies whether it is the right slice, and only then performs deep analysis, code execution, export, or document mutation. For queries, the model drafts GROQ and code parses, repairs, serializes, and executes it.

“So the flow becomes then query the set, understand the shape of the result, decide how you want to work on it, and then only then do deep analysis, fan out the work, or export.”transcript, stated

“Instead of hoping that the model got everything right, we can just parse the GROQ query ourselves. We can validate it, we can inspect the AST, and we can add the fields we want.”transcript, stated

Why this architecture

Sanity found that broad, clear tools plus better context shape outperformed slicing capabilities into many overlapping tools. The architecture gives the model enough structure to orient before fetching details or running expensive actions, keeping context clean and user trust higher.

“Stop slicing capability into smaller and smaller tools, but instead make the tools broader. Make tool boundaries very clear. Remove any overlap. And write much better instructions.”transcript, stated

“If you dump too much raw data into the main context window, the agent will become slower, more expensive, and usually just plain worse.”transcript, stated

Models used: LLM content agent · Specialized mutation subagent · GROQ-aware model behavior

Scale

Sanity customers can have hundreds of content types and tens of thousands of documents.
“Some have hundreds of content types and tens of thousands of documents.”transcript, stated
The set primitive is explicitly meant for hundreds, thousands, or hundreds of thousands of documents.
“How do we let the model work on hundreds, thousands, or hundreds of thousands of documents without pushing all of that into the main context?”transcript, stated
The schema example included 843 incoming references from blog posts to author.
“Author has eight hundred and forty-three incoming references from blog post.”transcript, stated
The system supports bulk operations such as updating hundreds of documents safely.
“updating hundreds of documents safely, or even just stuff like creating a CSV for sales or support.”transcript, stated

Alternatives considered (roads not taken)

Add more small tools

Rejected because: More tools made the agent less consistent and more likely to choose the nearly right tool.

“Now this sounds reasonable while you're building, but in practice, this gets messy very very quickly. It often made our agent less consistent, worse than choosing what to do.”transcript, stated

Dump full schemas into context

Rejected because: Huge schemas expose detail without clarity and cause the model to miss relationships.

“If you just dump all of that into the context, the model sees a lot of detail, but it doesn't see much clarity.”transcript, stated

Push all large query results into the main context

Rejected because: The agent only needs the shape of the result and next action, not thousands of documents in its head.

“The main agent doesn't need to carry all of these thousands of documents in its head. It only needs to know the shape of the result and what the next action is.”transcript, stated

Use complex multi-agent systems broadly

Rejected because: Subagents lost useful context from the main conversation, so Sanity uses them only where the gain is clear.

“we kept seeing one painful issue, context loss. Now you spend a long time building up useful context in the main agent. Then the main agent spawns the subagent.”transcript, stated

Patterns

`context-compaction` (context)

Sanity compresses schemas into shape summaries and large query results into sets rather than raw data dumps.

“schema overview first, not every detail, just the shape of it.”transcript, stated

“Sets let us work with large content without pushing large content into the context itself.”transcript, stated

`tool-use-orchestration` (orchestration)

The agent relies on fewer broader tools with clear boundaries and instructions instead of many overlapping tools.

“In our case, the best ideas were not adding more tools.”transcript, stated

“Overview first, detail on demand, fewer broader tools, and one strong main agent.”transcript, stated

`structured-output-contract` (reliability)

Model-drafted GROQ is parsed, validated, repaired, serialized, and executed by code rather than blindly trusted.

“The model proposes, but our code actually enforces.”transcript, stated

“let the model do the first draft, let code validate and repair what it can.”transcript, stated

`multi-agent-orchestration` (orchestration)

Sanity keeps one strong main agent and uses specialized subagents only for clear bounded tasks like mutations with exact local context.

“one strong main agent, a very small number of strong tools, and specialized sub-agents Only where we see that the gain is very clear.”transcript, stated

`human-in-the-loop-gate` (governance)

The UI exposes sets so users can verify that the agent is acting on the right content before expensive or risky work.

“We show the user the set in in the UI itself, so the user can open it, they can browse the documents to verify that the agents is working on the actual right slice of content.”transcript, stated

Tradeoffs

Agent context strategy

Chose shape first, detail on demand, execution last over showing raw schemas/results and acting immediately.

Rationale: The shape gives enough orientation to decide whether to inspect, stop, or safely proceed without bloating context.

“the agent doesn't need the full detail at first. It just needs a rough picture.”transcript, stated

“Only after the agent is confident, you run the expensive or the risky work.”transcript, stated

Large-result representation

Chose sets as reusable handles over loading thousands of documents into the model context.

Rationale: Sets preserve query, metadata, and user-verifiable shape while keeping the raw payload out of context.

“a set is just a compressed working memory. It's not the full payload. It's a reusable handle to a query result with some useful metadata attached to it.”transcript, stated

Query execution

Chose model draft plus code validation/repair over shipping model-written GROQ directly.

Rationale: Close queries are not enough when IDs/types are required for linking and safe operations.

“But close isn't enough here. So for example in most flows we require having an ID field and a type field to always be present, but the model might forget these.”transcript, stated

Subagent usage

Chose specialized mutation subagent with local shape over broad multi-agent architecture everywhere.

Rationale: Mutation is hard enough to justify a subagent, but only if it starts with exact local context rather than a generic short instruction.

“for mutation as specialized subagent actually it still helps.”transcript, stated

“Again, the goal isn't to give it all the context. The goal is only to give it the right set of context.”transcript, stated

Gotchas (what bit them)

Overlapping tools degrade action selection.

Root cause: Similar-sounding tools make the model spend effort selecting tools instead of solving the user's problem.

Resolution: Use broader tools with clear boundaries and better instructions.

“A lot of our tools even started sounding similar, and when the tool sounds similar, the model spends effort on tool selection rather than actual the actual user problem at hand.”transcript, stated

Full schema detail hides relationship clarity.

Root cause: Large schemas contain many fields, nested objects, arrays, references, and validations, so raw JSON overwhelms the model.

Resolution: Show a compressed schema graph/overview first and let the model zoom into exact structure only when needed.

“Because a real schema can be huge. It includes many document types, nested objects, arrays, references, validations, reusable object types, etc.”transcript, stated

Subagents can erase accumulated conversation nuance.

Root cause: The main agent may pass only a short instruction, losing tone, structure, intent, and shared working memory.

Resolution: Bias toward one main agent; when using mutation subagents, spawn them with schema type, field path, studio context, and document context.

“all that nuance, all those decisions, all that shared working memory from the main conversation, they will just disappear.”transcript, stated

“We include the relevant schema type, the field path we want to edit, the studio context, and document context.”transcript, stated

Evaluation

The transcript reports qualitative production learning rather than a formal benchmark: fewer broader tools improved consistency, compressed schema views fixed relationship errors, sets enable user verification, and code validation enforces GROQ correctness.

Metrics: tool-selection consistency · schema relationship correctness · set size/count/range/type metadata · user verification before expensive work · query validation/repair success

“this one compressed view fixed a surprising amount of bad behavior for us.”transcript, stated

“We can also estimate the cost before the user actually commits to the job. So the flow becomes Verify the set, verify the action, and then scale up.”transcript, stated

Outcomes

Compressed schema views fixed many relationship-based mistakes.
Sets let the agent work with very large content collections without holding raw documents in context.
Fewer broader tools plus one main agent helped Sanity do more with less tool complexity.

The system is designed for Sanity deployments with hundreds of content types and up to hundreds of thousands of documents; sets provide counts, ranges, and type breakdowns before large work proceeds.