Weaviate Query Agent: Usage
Sign up here for notifications on Weaviate Agents, or visit this page to see the latest updates and provide feedback.
The Weaviate Query Agent is a pre-built agentic service designed to answer natural language queries based on the data stored in Weaviate Cloud.
The user simply provides a prompt/question in natural language, and the Query Agent takes care of all intervening steps to provide an answer.
This page describes how to use the Query Agent to answer natural language queries, using your data stored in Weaviate Cloud.
Prerequisites
Weaviate instance
This Agent is available exclusively for use with a Weaviate Cloud instance. Refer to the Weaviate Cloud documentation for more information on how to set up a Weaviate Cloud instance.
You can try this Weaviate Agent with a free Sandbox instance on Weaviate Cloud.
Client library
At this time, this Agent is available only for Python and JavaScript. Support for other languages will be added in the future.
For Python, you can install the Weaviate client library with the optional agents extras to use Weaviate Agents. This will install the weaviate-agents package along with the weaviate-client package. For JavaScript, you can install the weaviate-agents package alongside the weaviate-client package.
Install the client library using the following command:
- Python
- JavaScript/TypeScript
pip install -U weaviate-client[agents]
Troubleshooting: Force pip to install the latest version
For existing installations, even pip install -U "weaviate-client[agents]" may not upgrade weaviate-agents to the latest version. If this occurs, additionally try to explicitly upgrade the weaviate-agents package:
pip install -U weaviate-agents
Or install a specific version:
pip install -U weaviate-agents==0.8.2
npm install weaviate-agents@latest
Instantiate the Query Agent
Basic instantiation
Provide:
- Target Weaviate Cloud instance details (e.g. the
WeaviateClientobject). - A default list of the collections to be queried
- Python
- JavaScript/TypeScript
import os
import weaviate
from weaviate.classes.init import Auth
from weaviate.agents.query import QueryAgent
headers = {
# Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
"X-INFERENCE-PROVIDER-API-KEY": os.environ.get("YOUR_INFERENCE_PROVIDER_KEY", ""),
}
client = weaviate.connect_to_weaviate_cloud(
cluster_url=os.environ.get("WEAVIATE_URL"),
auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
headers=headers,
)
# Instantiate a new agent object
qa = QueryAgent(
client=client, collections=["ECommerce", "FinancialContracts", "Weather"]
)
import weaviate, { WeaviateClient, vectorizer, dataType, configure } from 'weaviate-client';
import { QueryAgent } from 'weaviate-agents';
const headers = {
// Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
// "X-INFERENCE-PROVIDER-API-KEY": process.env.YOUR_INFERENCE_PROVIDER_KEY,
};
const client = await weaviate.connectToWeaviateCloud(process.env.WEAVIATE_URL as string, {
authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_ADMIN_KEY as string),
headers
});
// Instantiate a new agent object
const qa = new QueryAgent(
client, {
collections: ['ECommerce', 'FinancialContracts', 'Weather'],
});
Configure collections
The list of collections to be queried are further configurable with:
- Tenant names (required for a multi-tenant collection)
- Target vector(s) of the collection to query (optional)
- List of property names for the agent to use (optional)
- Python
- JavaScript/TypeScript
from weaviate.agents.query import QueryAgent
from weaviate.agents.classes import QueryAgentCollectionConfig
qa = QueryAgent(
client=client,
collections=[
QueryAgentCollectionConfig(
name="ECommerce", # The name of the collection to query
target_vector=["name_description_brand_vector"], # Target vector name(s) for collections with named vectors
view_properties=["description"], # Optional list of property names the agent can view
# Optional tenant name for collections with multi-tenancy enabled
# tenant="tenantA"
),
QueryAgentCollectionConfig(name="FinancialContracts"),
QueryAgentCollectionConfig(name="Weather"),
],
)
const qaWithConfig = new QueryAgent(client, {
collections: [
{
name: 'ECommerce',
targetVector: ['name_description_brand_vector'],
viewProperties: ['description']
// tenant: 'tenantA' // Optional for multi-tenancy
},
{ name: 'FinancialContracts' },
{ name: 'Weather' }
]
});
The Query Agent derives its access credentials from the Weaviate client object passed to it. This can be further restricted by the collection names provided to the Query Agent.
For example, if the associated Weaviate credentials' user has access to only a subset of collections, the Query Agent will only be able to access those collections.
Additional options
The Query Agent can be instantiated with additional options, such as:
system_prompt: A custom system prompt to replace the default system prompt provided by the Weaviate team (systemPromptfor JavaScript).timeout: The maximum time the Query Agent will spend on a single query, in seconds (server-side default: 60).
Async Python client
For usage example with the async Python client, see the Async Python client section.
Perform queries
Provide a natural language query to the Query Agent. The Query Agent will process the query, perform the necessary searches in Weaviate, and return the answer.
This is a synchronous operation. The Query Agent will return the answer to the user as soon as it is available.
The Query Agent will formulate its strategy based on your query. So, aim to be unambiguous, complete, yet concise in your query as much as possible.
- Python
- JavaScript/TypeScript
# Perform a query
response = qa.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60."
)
# Print the response
response.display()
// Perform a query
const basicResponse = await qaWithConfig.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60."
);
basicResponse.display();
Configure collections at runtime
The list of collections to be queried can be overridden at query time, as a list of names, or with further configurations:
Specify collection names only
This example overrides the configured Query Agent collections for this query only.
- Python
- JavaScript/TypeScript
response = qa.run(
"What kinds of contracts are listed? What's the most common type of contract?",
collections=["FinancialContracts"],
)
response.display()
const contractResponse = await qa.run(
"What kinds of contracts are listed? What's the most common type of contract?",
{ collections: ['FinancialContracts'] }
);
contractResponse.display();
Configure collections in detail
This example overrides the configured Query Agent collections for this query only, specifying additional options where relevant, such as:
- Target vector
- Properties to view
- Target tenant
- Python
- JavaScript/TypeScript
from weaviate_agents.classes import QueryAgentCollectionConfig
response = qa.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60.",
collections=[
# Use QueryAgentCollectionConfig class to provide further collection configuration
QueryAgentCollectionConfig(
name="ECommerce", # The name of the collection to query
target_vector=["name_description_brand_vector"], # Optional target vector name(s) for collections with named vectors
view_properties=["name", "description", "category", "brand"], # Optional list of property names the agent can view
),
QueryAgentCollectionConfig(
name="FinancialContracts", # The name of the collection to query
# Optional tenant name for collections with multi-tenancy enabled
# tenant="tenantA"
),
],
)
response.display()
const clothingResponse = await qaWithConfig.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60.",
{
collections: [
{
name: 'ECommerce',
targetVector: ['name_description_brand_vector'],
viewProperties: ['name', 'description', 'category', 'brand']
},
{
name: 'FinancialContracts'
}
]
});
clothingResponse.display();
Follow-up queries
The Query Agent can even handle follow-up queries, using the previous response as additional context.
- Python
- JavaScript/TypeScript
# Perform a follow-up query to 'I like vintage clothes and nice shoes. Recommend some of each below $60.'
following_response = qa.run(
"I like the vintage clothes options, can you do the same again but above $200?",
context=response,
)
# Print the response
response.display()
const followUpResponse = await qaWithConfig.run(
"I like the vintage clothes options, can you do the same again but above $200?",
{ context: basicResponse }
);
followUpResponse.display();
Stream responses
The Query Agent can also stream responses, allowing you to receive the answer as it is being generated.
- Python
- JavaScript/TypeScript
from weaviate.agents.classes import ProgressMessage, StreamedTokens
for output in qa.stream(
query,
# Setting this to false will skip ProgressMessages, and only stream
# the StreamedTokens / the final QueryAgentResponse
include_progress=True # Default is True
):
if isinstance(output, ProgressMessage):
# The message is a human-readable string, structured info available in output.details
print(output.message)
elif isinstance(output, StreamedTokens):
# The delta is a string containing the next chunk of the final answer
print(output.delta, end='', flush=True)
else:
# This is the final response, as returned by QueryAgent.run()
output.display()
// Setting includeProgress to false will skip progressMessages, and only stream
// the streamedTokens / the final response.
for await (const event of qa.stream(query, { includeProgress: true })) { // This is true by default, this example is just being explicit
if (event.outputType === "progressMessage") {
// The message is a human-readable string, structured info available in event.details
console.log(event.message);
} else if (event.outputType === "streamedTokens") {
// The delta is a string containing the next chunk of the final answer
process.stdout.write(event.delta);
} else {
// This is the final response, as returned by QueryAgent.run()
event.display();
}
}
Inspect responses
The response from the Query Agent will contain the final answer, as well as additional supporting information.
The supporting information may include searches or aggregations carried out, what information may have been missing, and how many LLM tokens were used by the Agent.
Helper function
Try the provided helper functions (e.g. .display() method) to display the response in a readable format.
- Python
- JavaScript/TypeScript
# Perform a query
response = qa.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60."
)
# Print the response
response.display()
// Perform a query
const basicResponse = await qaWithConfig.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60."
);
basicResponse.display();
This will print the response and a summary of the supporting information found by the Query Agent.
Example output
╭──────────────────────────────────────────────────────── 🔍 Original Query ─────────────────────────────────────────────────────────╮
│ │
│ I like vintage clothes and and nice shoes. Recommend some of each below $60. │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────── 📝 Final Answer ──────────────────────────────────────────────────────────╮
│ │
│ For vintage clothes under $60, here are some great options: │
│ │
│ 1. **Vintage Scholar Turtleneck** - $55.00: This piece from the Dark Academia collection offers comfort with a stylish pleated │
│ detail, perfect for a scholarly wardrobe (available in black and grey). │
│ 2. **Retro Pop Glitz Blouse** - $46.00: Part of the Y2K collection, this blouse adds shimmer and features a dramatic collar for a │
│ pop culture-inspired look (available in silver). │
│ 3. **Retro Glitz Halter Top** - $29.98: Embrace early 2000s glamour with this halter top, suitable for standing out with its shiny │
│ pastel fabric (available in pink and purple). │
│ 4. **Metallic Pastel Dream Cardigan** - $49.00: This cardigan features a metallic sheen and is perfect for a colorful, nostalgic │
│ touch (available in blue and pink). │
│ │
│ For nice shoes under $60: │
│ │
│ 1. **Mystic Garden Strappy Flats** - $59.00: These gold flats feature delicate vine and floral patterns, ideal for adding a touch │
│ of magic to your outfit. │
│ 2. **Garden Serenade Sandals** - $56.00: These sandals from the Cottagecore collection have ivy-green straps with cream floral │
│ patterns, embodying a romantic countryside aesthetic. │
│ 3. **Forest Murmur Sandals** - $59.00: With a soft green hue and gold accents, these sandals from the Fairycore collection are │
│ both elegant and whimsical. │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 🔭 Searches Executed 1/2 ─────────────────────────────────────────────────────╮
│ │
│ QueryResultWithCollection( │
│ queries=['vintage clothes'], │
│ filters=[[IntegerPropertyFilter(property_name='price', operator=<ComparisonOperator.LESS_THAN: '<'>, value=60.0)]], │
│ filter_operators='AND', │
│ collection='Ecommerce' │
│ ) │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── 🔭 Searches Executed 2/2 ─────────────────────────────────────────────────────╮
│ │
│ QueryResultWithCollection( │
│ queries=['nice shoes'], │
│ filters=[[IntegerPropertyFilter(property_name='price', operator=<ComparisonOperator.LESS_THAN: '<'>, value=60.0)]], │
│ filter_operators='AND', │
│ collection='Ecommerce' │
│ ) │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ 📊 No Aggregations Run │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────── 📚 Sources ────────────────────────────────────────────────────────────╮
│ │
│ - object_id='3e3fc965-0a08-4095-b538-5362404a4aab' collection='Ecommerce' │
│ - object_id='3ce04def-fe06-48bd-ba0e-aa491ba2b3c5' collection='Ecommerce' │
│ - object_id='cece6613-0ad8-44a5-9da3-a99bcbe67141' collection='Ecommerce' │
│ - object_id='1be234ae-7665-4e8c-9758-07ba87997ca1' collection='Ecommerce' │
│ - object_id='5ee7874b-e70b-4af7-b053-cce74c10e406' collection='Ecommerce' │
│ - object_id='c7dd08d3-fe8e-44c2-8f99-8271c3ba24ee' collection='Ecommerce' │
│ - object_id='5f35dc8f-18f5-4388-845d-0383927dfee0' collection='Ecommerce' │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
📊 Usage Statistics
┌────────────────┬──────┐
│ LLM Requests: │ 4 │
│ Input Tokens: │ 8621 │
│ Output Tokens: │ 504 │
│ Total Tokens: │ 9125 │
└────────────────┴──────┘
Total Time Taken: 15.80s
Inspection example
This example outputs:
- The original user query
- The answer provided by the Query Agent
- Searches & aggregations (if any) conducted by the Query Agent
- Any missing information
- Python
- JavaScript/TypeScript
print("\n=== Query Agent Response ===")
print(f"Original Query: {response.original_query}\n")
print("🔍 Final Answer Found:")
print(f"{response.final_answer}\n")
print("🔍 Searches Executed:")
for collection_searches in response.searches:
for result in collection_searches:
print(f"- {result}\n")
if response.has_aggregation_answer:
print("📊 Aggregation Results:")
for collection_aggs in response.aggregations:
for agg in collection_aggs:
print(f"- {agg}\n")
if response.missing_information:
if response.is_partial_answer:
print("⚠️ Answer is Partial - Missing Information:")
else:
print("⚠️ Missing Information:")
for missing in response.missing_information:
print(f"- {missing}")
console.log('\n=== Query Agent Response ===');
console.log(`Original Query: ${basicResponse.originalQuery}\n`);
console.log('🔍 Final Answer Found:');
console.log(`${basicResponse.finalAnswer}\n`);
console.log('🔍 Searches Executed:');
for (const collectionSearches of basicResponse.searches) {
for (const result of collectionSearches) {
console.log(`- ${result.queries}\n`);
}
}
if (basicResponse.hasAggregationAnswer) {
console.log('📊 Aggregation Results:');
for (const collectionAggs of basicResponse.aggregations) {
for (const agg of collectionAggs) {
console.log(`- ${agg}\n`);
}
}
}
if (basicResponse.missingInformation && basicResponse.missingInformation.length > 0) {
if (basicResponse.isPartialAnswer) {
console.log('⚠️ Answer is Partial - Missing Information:');
} else {
console.log('⚠️ Missing Information:');
}
for (const missing of basicResponse.missingInformation) {
console.log(`- ${missing}`);
}
}
Usage - Async Python client
If you are using the async Python Weaviate client, the instantiation pattern remains similar. The difference is use of the AsyncQueryAgent class instead of the QueryAgent class.
The resulting async pattern works as shown below:
- Python
import asyncio
import os
import weaviate
from weaviate.agents.query import AsyncQueryAgent
async_client = weaviate.use_async_with_weaviate_cloud(
cluster_url=os.environ.get("WEAVIATE_URL"),
auth_credentials=os.environ.get("WEAVIATE_API_KEY"),
headers=headers,
)
async def query_vintage_clothes(async_query_agent: AsyncQueryAgent):
response = await async_query_agent.run(
"I like vintage clothes and nice shoes. Recommend some of each below $60."
)
return ("Vintage Clothes", response)
async def query_financial_data(async_query_agent: AsyncQueryAgent):
response = await async_query_agent.run(
"What kinds of contracts are listed? What's the most common type of contract?",
)
return ("Financial Contracts", response)
async def run_concurrent_queries():
try:
await async_client.connect()
async_qa = AsyncQueryAgent(
async_client,
collections=[
QueryAgentCollectionConfig(
name="ECommerce", # The name of the collection to query
target_vector=["name_description_brand_vector"], # Optional target vector name(s) for collections with named vectors
view_properties=["name", "description", "category", "brand"], # Optional list of property names the agent can view
),
QueryAgentCollectionConfig(
name="FinancialContracts", # The name of the collection to query
# Optional tenant name for collections with multi-tenancy enabled
# tenant="tenantA"
),
],
)
# Wait for both to complete
vintage_response, financial_response = await asyncio.gather(
query_vintage_clothes(async_qa),
query_financial_data(async_qa)
)
# Display results
print(f"=== {vintage_response[0]} ===")
vintage_response[1].display()
print(f"=== {financial_response[0]} ===")
financial_response[1].display()
finally:
await async_client.close()
asyncio.run(run_concurrent_queries())
Streaming
The async Query Agent can also stream responses, allowing you to receive the answer as it is being generated.
- Python
async def stream_query(async_query_agent: AsyncQueryAgent):
async for output in async_query_agent.stream(
"What are the top 5 products sold in the last 30 days?",
# Setting this to false will skip ProgressMessages, and only stream
# the StreamedTokens / the final QueryAgentResponse
include_progress=True # Default is True
):
if isinstance(output, ProgressMessage):
# The message is a human-readable string, structured info available in output.details
print(output.message)
elif isinstance(output, StreamedTokens):
# The delta is a string containing the next chunk of the final answer
print(output.delta, end='', flush=True)
else:
# This is the final response, as returned by QueryAgent.run()
output.display()
async def run_streaming_query():
try:
await async_client.connect()
async_qa = AsyncQueryAgent(
async_client,
collections=[
QueryAgentCollectionConfig(
name="ECommerce", # The name of the collection to query
target_vector=["name_description_brand_vector"], # Optional target vector name(s) for collections with named vectors
view_properties=["name", "description", "category", "brand"], # Optional list of property names the agent can view
),
QueryAgentCollectionConfig(
name="FinancialContracts", # The name of the collection to query
# Optional tenant name for collections with multi-tenancy enabled
# tenant="tenantA"
),
]
)
await stream_query(async_qa)
finally:
await async_client.close()
asyncio.run(run_streaming_query())
Limitations & Troubleshooting
Sign up here for notifications on Weaviate Agents, or visit this page to see the latest updates and provide feedback.
Usage limits
The current usage limit is 500 Query Agent queries per day per Weaviate Cloud organization.
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.
Questions and feedback
The official changelog for Weaviate Agents can be found here. If you have feedback, such as feature requests, bug reports or questions, please submit them here, where you will be able to see the status of your feedback and vote on others' feedback.
If you have any questions or feedback, let us know in the user forum.