Why Weaviate Query Agents make sense for shopping search

Weaviate’s Query Agent direction makes sense for shopping search because ecommerce queries rarely fit into one retrieval mode.

A shopper can type:

Compare Nova Nest and Echo & Stitch for sustainable shoes under $150.

That request mixes taste, catalog structure, brand knowledge, source references, and commercial rules. Vector search helps with words like “sustainable” and “vintage.” Structured planning should enforce the price ceiling, choose the brand collection, and decide whether the answer has enough source data to mention shipping, discounts, or availability.

That is the useful part of Weaviate’s agent framing. The move goes beyond “let an LLM answer shopping questions.” The better architecture sits closer to the database: let a query planner translate natural language into searches, filters, aggregations, and source-aware responses, then expose enough trace data that an engineer can debug the plan.

The launch condition is traceability: every shopper-facing answer needs an inspectable plan, source IDs, token usage, latency, and a fallback path.

Shopping queries need planning

Most RAG demos ask a model to answer from retrieved documents. Ecommerce search has sharper edges because a wrong answer can turn into a pricing, inventory, or policy problem.

The same query carries several jobs:

Weaviate’s ecommerce recipe is a good example of the gap. It uses product and brand collections from Hugging Face datasets and shows the Query Agent deciding which collection to use, whether to run a search or aggregation, and which filters belong in the operation. The public launch post uses the same ecommerce shape with a query like “Red summer dresses between $45 and $95” to show why semantic retrieval still needs a structured price filter.

Teams usually build that layer themselves. They parse intent, extract filters, pick keyword, vector, or hybrid search, query the database, and pass bounded results into an answer step. Weaviate’s bet is that the Query Agent can own more of that query-understanding work because it already has the schema, collection descriptions, filters, aggregations, BM25, vector search, and hybrid search in one place.

That is a reasonable place for this behavior to live. It also raises the bar for observability.

The plan matters more than the paragraph

The final answer matters less than the plan behind it.

For shopping search, the plan carries more value than the generated paragraph:

def plan_query(query: str) -> tuple[PlannedOperation, ...]:
    filters: list[FilterClause] = []

    budget = extract_budget(query)
    if budget is not None:
        filters.append(FilterClause("price", "<", budget))

    category = extract_category(query)
    if category is not None:
        filters.append(FilterClause("category", "=", category))

    return (
        PlannedOperation(
            operation="search",
            collection="Ecommerce",
            query=extract_style_query(query),
            search_type="hybrid",
            alpha=0.65,
            filters=tuple(filters),
            rationale=(
                "Soft style terms need semantic matching, while price and "
                "category constraints should stay as structured filters."
            ),
        ),
    )

That shape is intentionally boring. It separates soft language from hard constraints. “Sustainable” can participate in semantic matching. price < 150 and category = shoes should survive as structured filters. A named brand comparison may need a second operation against a Brands collection.

The Weaviate docs expose the same kind of surface. A QueryAgentResponse can show the original query, final answer, searches, aggregations, sources, missing information, usage statistics, and total time. That matters because a bad shopping answer has several possible causes:

• The agent searched the wrong collection.
• It treated a hard filter as a soft semantic term.
• It used an aggregation when it needed product-level evidence.
• It generated a claim beyond the retrieved fields.
• It ran long enough that the UI should have switched to a fallback.

With the trace missing, all of those collapse into “the AI got it wrong.” That gives the engineer nothing to debug.

Eval the query plan first

Start evals at the plan layer before grading prose quality.

For this query:

Compare Nova Nest and Echo & Stitch for sustainable shoes under $150

The first regression test should look for the mechanical decisions:

{
  "name": "brand_comparison_shoes",
  "query": "Compare Nova Nest and Echo & Stitch for sustainable shoes under $150",
  "expect_collections": ["Ecommerce", "Brands"],
  "expect_operations": ["search", "lookup"],
  "expect_search_type": "hybrid",
  "expect_filters": [
    { "property_name": "price", "operator": "<", "value": 150 },
    { "property_name": "category", "operator": "=", "value": "shoes" }
  ],
  "expect_sources": true
}

That eval only proves the agent kept the minimum shape of the request intact. The next layer should check source attribution, unsupported claims, missing-information behavior, and whether the response used the comparison frame the shopper asked for.

This is the testing shift agentic search needs. The model-written paragraph can change. The plan should obey invariants.

Latency changes the product shape

The Query Agent examples make the cost and latency tradeoff visible.

In the ecommerce tutorial, one displayed response for “vintage clothes” under $200 includes three LLM requests, 8,109 total tokens, and about 11.6 seconds of total time. The usage docs also show Search mode as retrieval-only, with an example response around 4.7 seconds and 152 total tokens. Those are documentation examples rather than benchmarks, but the product implication is still real: agentic query planning can cost more than ordinary search, and users feel that cost as delay.

That pushes the product design toward two modes:

• Search mode for product discovery, filters, result cards, and fast iteration.
• Ask mode for comparisons, summaries, and questions where answer synthesis is worth the extra work.

Weaviate’s API shape already supports that split. search() can return objects and metadata without answer generation. ask() can run the full answer flow. Streaming can help when synthesis is useful. The latency budget remains.

For a public shopping UI, the agent needs a deadline. When it crosses that budget, the product should return filtered product cards, preserve the trace, and let the shopper ask a follow-up.

Schema descriptions become runtime metadata

One small detail in the ecommerce recipe carries a lot of weight: the price field description.

Property(name="price", data_type=DataType.NUMBER, description="price of item in USD")

That looks like documentation. In an agentic database flow, it becomes runtime metadata.

The Query Agent uses collection and property descriptions to decide where to search and how to interpret fields. Vague schema descriptions can become vague behavior. Numeric fields need units and scale. Product descriptions should distinguish canonical catalog data from generated copy. Sponsored placement, return windows, shipping promises, and inventory status should read as explicit fields with product-owned rules, not as hints the model infers from prose.

Schema descriptions deserve the same linting treatment as API contracts:

def lint_collections(collections: Iterable[CollectionDescription]) -> list[SchemaIssue]:
    issues: list[SchemaIssue] = []

    for collection in collections:
        if len(collection.description.split()) < 8:
            issues.append(
                SchemaIssue(
                    severity="error",
                    collection=collection.name,
                    field="<collection>",
                    message="Collection description is too short for agent routing.",
                )
            )

        for prop in collection.properties:
            if prop.data_type == "number" and not description_has_unit(prop):
                issues.append(
                    SchemaIssue(
                        severity="warning",
                        collection=collection.name,
                        field=prop.name,
                        message="Numeric field does not describe its unit or scale.",
                    )
                )

    return issues

That is one of the more interesting parts of Weaviate’s direction. The database schema now acts as both storage metadata and runtime context for the agent.

Managed embeddings reduce glue

Weaviate also keeps pushing more of the retrieval stack into the platform. The platform page positions Weaviate around hybrid search, BM25 plus vectors, filters, RAG, vectorizer modules, backups, multi-tenancy, and deployment options. The Embeddings page adds managed embeddings inside Weaviate Cloud, with Snowflake Arctic text embedding options and a ModernVBERT multimodal option listed on the page.

For a small team, the appeal is clear. One fewer embedding provider integration means fewer API keys, fewer rate-limit paths, and fewer places where ingestion can fail.

The ranking work stays.

Before depending on managed embeddings for a catalog, measure retrieval quality against a baseline, check model portability, confirm data residency requirements, and set a cost ceiling. Managed embeddings reduce glue code. Catalog-specific retrieval quality still needs proof.

Agent Skills solve the coding-agent side

Weaviate Agent Skills solve a related but different context problem: coding agents forget specialized infrastructure details.

The Agent Skills post names the failure modes directly. General coding agents can hallucinate old Weaviate v3 syntax, guess hybrid-search alpha parameters, or miss efficient multivector embedding patterns. The agent-skills repository gives coding agents commands and references for collection creation, schema inspection, keyword, vector, and hybrid search, imports, Query Agent usage, and environment setup.

That is context engineering for code generation. It gives a coding agent the Weaviate-specific working set instead of hoping the base model remembers the current client library.

It still needs normal engineering guardrails: pinned client versions, generated-code tests, review on schema changes, and a separate path for anything that touches production imports.

My launch bar

This direction works because the database already owns many of the pieces a shopping assistant needs: hybrid search, filters, collection metadata, aggregations, embeddings, and source traces.

Launch requires explicit response rules around commercial claims:

answer_rules = {
    "mode": "source_bounded_product_recommendation",
    "must_include": [
        "product_name",
        "price_usd",
        "brand",
        "why_it_matches",
        "source_refs",
    ],
    "must_not_include": [
        "inventory claims",
        "discount claims",
        "shipping promises",
        "personalized claims without profile consent",
    ],
}

Those rules should sit outside the model where possible. The agent can plan retrieval work. Commercial policy belongs in explicit product logic.

Before putting this in front of shoppers, the system needs checks for:

The next useful test is a hosted Weaviate run against a small query set, saving the full QueryAgentResponse for each prompt. The scorecard should cover collection choice, filter extraction, aggregation choice, source IDs, missing-information behavior, token usage, total time, and whether Ask mode earned its cost over Search mode.

Weaviate’s agent direction fits shopping search. It still needs to ship like any other probabilistic system: traces first, evals at the plan layer, latency budgets in the UI, and a boring fallback path.

References

• Weaviate platform
• Weaviate Agents blog
• Weaviate Query Agent ecommerce recipe
• Weaviate Query Agent ecommerce tutorial
• Weaviate Query Agent usage docs
• Weaviate Embeddings
• Weaviate Agent Skills blog
• Weaviate agent-skills repo