Limitations & troubleshooting

Things to check when the Query Agent isn't behaving as expected, plus the soft usage limits and typical execution timings to keep in mind.

Troubleshooting

The Query Agent is not available

• Agents are not enabled for your organization. Agents is an organization-level page in the Weaviate Cloud console, under Agents in the sidebar. If Enable Agents is off, switch it on — it is set once for the whole organization.
• The instance is not a Weaviate Cloud instance. The Query Agent runs as a Weaviate Cloud service. A locally running Weaviate instance does not support it. See Installation.
• The client package is missing or out of date. Install weaviate-agents alongside the Weaviate client, and check you are on a version that has the feature you are using. See the Python and JavaScript/TypeScript client pages.

You run out of free requests

The free allowance is 1,000 Query Agent requests per organization per month, and it resets monthly. The Agents page in the console shows the allowance, how much of it you have used, and the reset date — check there first when requests start failing.

Requests are not all equal: an Ask query consumes 4 requests, while Search and Suggest Queries consume 1 each. An agent used mostly through Ask reaches the limit about four times faster than the request count suggests. See Usage limits below.

The answer is wrong or the agent searched the wrong collection

• The agent routes queries using each collection's description and its property descriptions. Vague or missing descriptions are the most common cause of a query landing on the wrong collection. See Custom collection descriptions below.
• The agent can only see what its credentials can see. It derives access from the Weaviate client object you pass it, further narrowed by the collection names you give it. A collection missing from an answer is often a permissions or collections argument problem, not a search problem.
• The response object reports the searches the agent actually ran, including the generated queries and filters. Inspect searches on the response to see what the agent did before you change the prompt.

A request times out or takes too long

A single run makes several model calls and several Weaviate queries, so ~10 seconds is normal and complex queries take longer. For long-running queries, use streaming responses, which send progress updates and heartbeats that keep the connection alive. See Execution times below.

Where to see errors

The clients raise an exception carrying the reason for the failure, so log or print the full exception rather than only its type. For usage problems, the Agents page in the console is the place to look. If a failure is not explained by anything above, contact support.

Usage limits

Each Weaviate Cloud organization can make up to 1,000 Query Agent requests per month at no cost.

Requests are consumed based on query type:

• Ask: 4 requests per query
• Search: 1 request per query
• Suggest Queries: 1 request per query

This limit may change in the future. For questions about usage limits, contact product@weaviate.io.

Custom collection descriptions

The Query Agent makes use of each collection's description metadata as well as individual property descriptions in deciding what collection to query.

Both collection descriptions and property descriptions can be updated after the collection has been created. For detailed instructions on updating collection and property descriptions, see the update collection definition documentation.

We are investigating an ability to specify a custom collection description at runtime.

Execution times

The Query Agent performs multiple operations to translate a natural language query into Weaviate queries, and to process the response.

This typically requires multiple calls to generative models (e.g. LLMs) and multiple queries to Weaviate.

As a result, each Query Agent run may take some time to complete. Depending on the query complexity, it may not be uncommon to see execution times of ~10 seconds.

For long-running or complex queries, consider using streaming responses rather than non-streaming requests. Streaming provides progress updates and sends heartbeats to maintain the connection, preventing timeout issues that can occur with long-running non-streaming requests.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.