Weaviate Query Agent: Overview

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.

Architecture

The Query Agent is provided as a service on Weaviate Cloud.

When a user provides a prompt/query, the query agent analyses it and any other known context to autonomously carry out the searches itself.

Query Agent context

The Query agent analyses collection and property descriptions to better understand how to construct relevant queries.

The context may also include previous conversation history, and any other relevant information.

Query Agent: visualized workflow

The Query Agent follows these high-level steps:

• Use appropriate generative models (e.g. large language models) to analyze the task & the required queries. Determine the exact queries to perform. (Steps 1 & 2)
• Send queries to Weaviate. Weaviate vectorizes the queries as needed using the specified vectorizer integration. (Steps 3-5)
• Receive the results from Weaviate, and use appropriate generative models to generate the final respond to the user prompt/query. (Step 6)

Then, the Query Agent returns the answer to the user, as well as intermediate outputs, such as the underlying search results from Weaviate.

Note that the term Query Agent refers to the entire system. The Query Agent may comprise multiple subsystems, such as microservices and/or agents under the hood, each responsible for a specific task.

Querying

The Query Agent supports two query types:

• Search Weaviate with the Query Agent using natural langauge. The Query Agent will process the question, perform the necessary searches in Weaviate, and return the relevant objects.

• Ask the Query Agent a question using natural language. The Query Agent will process the question, perform the necessary searches in Weaviate, and return the answer.

Basic usage

Here is an overview of how to use the this Weaviate Agent. For more detailed information, refer to the Usage page.

Prerequisites

This Agent is available exclusively for use with a Weaviate Cloud instance, and a supported version of the Weaviate client library.

Example usage

Pass an instance of the Weaviate client to the Query Agent, and the Query Agent will extract the necessary information from the client to perform the query.

Python

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"]
)

  API docs

JavaScript/TypeScript

import weaviate, { WeaviateClient, vectors, dataType, configure } from 'weaviate-client';
import { QueryAgent, ChatMessage } 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 queryAgent = new QueryAgent(
    client, {
    collections: ['ECommerce', 'FinancialContracts', 'Weather'],

});

  API docs

Then, provide a natural language query input. The Query Agent will process the query, perform the necessary searches in Weaviate, and return the answer.

Search (retrieval only)

Python

# Perform a search using Search Mode (retrieval only, no answer generation)
search_response = qa.search("Find me some vintage shoes under $70", limit=10)

# Access the search results
for obj in search_response.search_results.objects:
    print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")

  API docs

JavaScript/TypeScript

// Perform a search using Search Mode (retrieval only, no answer generation)
const basicSearchResponse = await qa.search("Find me some vintage shoes under $70", {
    limit: 10
} )

// Access the search results
for (const obj of basicSearchResponse.searchResults.objects) {
    console.log(`Product: ${obj.properties['name']} - ${obj.properties['price']}`)
}

  API docs

The Query Agent can even handle follow-up queries, using the previous response as additional context.

Python

# Perform a follow-up query and include the answer from the previous query
from weaviate.agents.classes import ChatMessage

conversation = [
    ChatMessage(role="assistant", content=response.final_answer),
    ChatMessage(
        role="user",
        content="I like the vintage clothes options, can you do the same again but above $200?",
    ),
]

following_response = qa.ask(conversation)

# Print the response
following_response.display()

  API docs

JavaScript/TypeScript

// Perform a follow-up query and include the answer from the previous query

const basicConversation: ChatMessage[] = [
    {   role: "assistant", content: basicResponse.finalAnswer },
    {
        role: "user",
        content: "I like the vintage clothes options, can you do the same again but above $200?",
    },
]

const followingResponse = await qaWithConfig.ask(basicConversation)

// Print the response
followingResponse.display()

  API docs

Ask (with answer generation)

Python

# Perform a query using Ask Mode (with answer generation)
response = qa.ask(
    "I like vintage clothes and nice shoes. Recommend some of each below $60."
)

# Print the response
response.display()

  API docs

JavaScript/TypeScript

// Perform a query
const basicQuery = "I like vintage clothes and nice shoes. Recommend some of each below $60."
const basicResponse = await qaWithConfig.ask(basicQuery);

basicResponse.display();

  API docs

Further resources

For more detailed information on how to use this Agent, refer to the Usage page.

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.