GROQ as an Agent Query Language: Why Your AI Needs More Than a Vector Search API

Most AI agents interact with content through a narrow interface. They send a text query to a vector search API and receive a ranked list of text chunks. That is the extent of their retrieval capability.

If the agent needs to filter results by date, price, or category, it has to do it in application code after receiving the chunks. If it needs to follow a reference from a product to its warranty document, it has to make a second API call. If it needs to combine keyword precision with semantic discovery, it needs a separate BM25 index and custom fusion logic.

This is why production agents built on vector search APIs hit an accuracy ceiling: the retrieval interface is too limited. GROQ, the query language built for Sanity’s Content Lake, was designed for exactly this class of problem. It gives agents the ability to filter, project, traverse references, apply hybrid search, and shape the exact JSON payload they need, all in a single request.

With Agent Context, GROQ becomes the native query language for production AI agents.

What Vector Search APIs Cannot Do

A typical vector search API accepts a query string and returns the top K most similar chunks with similarity scores. That is it.

The agent cannot:

• Tell the API to exclude draft documents
• Ask for only products above a certain rating
• Request that the results include the author’s name resolved from a reference
• Combine semantic similarity on the description field with exact keyword matching on the SKU field

Every one of these operations requires additional code outside the search API. This means your agent’s retrieval logic is split between the vector database query and a post-processing layer that filters, enriches, and reshapes the results.

That post-processing layer is where bugs live, where latency accumulates, and where accuracy degrades.

GROQ as a Complete Retrieval Language

GROQ eliminates the post-processing layer entirely.

A single GROQ query can:

• Filter documents by type and status
• Apply semantic similarity scoring with text::semanticSimilarity()
• Boost exact keyword matches with match() and boost()
• Traverse references to resolve related documents
• Project exactly the fields the agent needs

Consider a support agent that needs to find troubleshooting guides for a specific product running a specific firmware version, ranked by relevance to the customer’s description of their problem.

In a vector search API, this requires multiple calls and custom logic. In GROQ, it is one query that:

• Filters by product reference and firmware version
• Scores by semantic similarity on the problem description
• Boosts exact error code matches
• Returns the step-by-step resolution with the product name resolved from the reference

*[_type == "troubleshootingGuide" &&
  references($productId) &&
  firmwareVersion == $firmwareVersion
] | score(
  text::semanticSimilarity(description, $problemDescription),
  match(errorCode, $errorCode) => boost(3)
) {
  _id,
  title,
  steps,
  product->{
    _id,
    name,
    sku
  },
  firmwareVersion,
  score
} | order(score desc)[0...10]

Schema-Aware Query Construction

The real power emerges when GROQ is paired with schema awareness.

Through Agent Context, an AI agent receives a compressed representation of your content model before it writes a single query. It knows which fields are strings, which are numbers, which are references, and which are arrays.

This means the agent can construct GROQ queries that are structurally valid and semantically meaningful:

• It does not search for text that mentions a price. It queries the price field and receives a number.
• It does not hope that a chunk contains the author’s name. It follows the author reference and retrieves the full profile.

This schema-aware query construction is what separates GROQ-powered agents from vector-search-only agents.

Hybrid Search in One Expression

Sanity’s native hybrid search brings semantic discovery and keyword precision into a single GROQ expression.

You use score() to combine semantic similarity scoring with `text::semanticSimilarity()` and keyword precision with `match()` and `boost()` — all in a single expression, with no separate BM25 index or custom rank fusion code required. The table below shows how this compares to a standalone vector search API across key retrieval capabilities: