Weaviate Cloud only The Query Agent can suggest queries based on the data in your collections. This is useful for helping users discover what kinds of questions they can ask, or for generating example queries for a new dataset. ## Usage The method can be called with a set of instructions and/or specifications: :::code-group{sync="languages"} ```python title="Python" from weaviate.agents.query import QueryAgent qa = QueryAgent(client=client) response = qa.suggest_queries( collections=["FinancialContracts"], num_queries=3, instructions="High-level themes and open-ended exploration", ) ``` ```typescript title="JavaScript/TypeScript" import weaviate from 'weaviate-client'; import { QueryAgent } from 'weaviate-agents'; ``` ::: Or can be called without any additional arguments, to use the defaults. :::code-group{sync="languages"} ```python title="Python" qa = QueryAgent(client=client, collections=["FinancialContracts"]) qa.suggest_queries() ``` ```typescript title="JavaScript/TypeScript" qa = new QueryAgent(client, { collections: ['FinancialContracts'], }); await qa.suggestQueries(); ``` ::: ### Parameters Suggest Queries can be called with the following arguments: ::::tabs{sync="languages"} :::tab{title="Python"} | Parameter | Type | Description | | -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `collections` | `list[str \| QueryAgentCollectionConfig] \| None` | Override the collections configured at instantiation. [See the page on collection configuration for more detail](../agents-configuration/advanced-collections.md). | | `num_queries` | `int` | The number of queries to suggest (default: `3`). | | `instructions` | `str \| None` | Guide the style or focus of the suggested queries. This is provided in addition to any system instructions. Useful for e.g. specifying language. | | `conversation` | `list[ChatMessage] \| None` | A conversation history used to generate follow-up query suggestions. | ::: :::tab{title="JavaScript/TypeScript"} | Parameter | Type | Description | | -------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `collections` | `(string \| QueryAgentCollectionConfig)[]` | Override the collections configured at instantiation. [See the page on collection configuration for more detail](../agents-configuration/advanced-collections.md). | | `numQueries` | `number` | The number of queries to suggest (default: `3`). | | `instructions` | `string` | Guide the style or focus of the suggested queries. This is provided in addition to any system instructions. Useful for e.g. specifying language. | | `conversation` | `ChatMessage[]` | A conversation history used to generate follow-up query suggestions. | ::: :::: ### Follow-up queries You can pass a `conversation` to Suggest Queries to generate follow-up query suggestions based on the conversation history. This is useful for guiding users toward relevant next questions after an initial exchange. The `conversation` parameter accepts a list of `ChatMessage` objects, using the same format as [multi-turn conversations](../agents-configuration/multi-turn-conversations.md). :::code-group{sync="languages"} ```python title="Python" from weaviate.agents.classes import ChatMessage # Build a conversation history conversation = [ ChatMessage(role="user", content="What are some popular machine learning frameworks?"), ChatMessage( role="assistant", content="Some popular ML frameworks include TensorFlow, PyTorch, and JAX.", ), ] # Suggest follow-up queries based on the conversation context response = qa.suggest_queries( conversation=conversation, num_queries=3, ) for suggested_query in response.queries: print(suggested_query.query) ``` ```typescript title="JavaScript/TypeScript" import { ChatMessage } from 'weaviate-agents'; // Build a conversation history const suggestConversation: ChatMessage[] = [ { role: 'user', content: 'What are some popular machine learning frameworks?', }, { role: 'assistant', content: 'Some popular ML frameworks include TensorFlow, PyTorch, and JAX.', }, ]; // Suggest follow-up queries based on the conversation context const suggestWithConvoResponse = await qa.suggestQueries({ conversation: suggestConversation, numQueries: 3, }); for (const suggestedQuery of suggestWithConvoResponse.queries) { console.log(suggestedQuery.query); } ``` ::: ## Response The `SuggestQueryResponse` class has the following properties: ::::tabs{sync="languages"} :::tab{title="Python"} | Field | Type | Description | | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `queries` | `list[SuggestedQuery]` | A list of `SuggestedQuery` objects, each with a single property `query`, a suggested query that the user could run against their data. | | `collection_count` | `int` | The number of collections that were considered when generating the suggested queries. | | `usage` | `ModelUnitUsage` | A `ModelUnitUsage` instance providing detail on the model units used during the run. The `model_units` are effectively token usage measurements normalized by cost. | | `total_time` | `float` | Total time taken (seconds). | [See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.SuggestQueryResponse) ::: :::tab{title="JavaScript/TypeScript"} | Field | Type | Description | | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `queries` | `SuggestedQuery[]` | A list of `SuggestedQuery` objects, each with a single property `query`, a suggested query that the user could run against their data. | | `collectionCount` | `number` | The number of collections that were considered when generating the suggested queries. | | `usage` | `ModelUnitUsage` | A `ModelUnitUsage` object providing detail on the model units used during the run. The `modelUnits` are effectively token usage measurements normalized by cost. | | `totalTime` | `number` | Total time taken (seconds). | [See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/SuggestQueryResponse.html) ::: :::: ## Async ::::tabs{sync="languages"} :::tab{title="Python"} In Python, the above examples use the synchronous client, but Suggest Queries can also be called asynchronously. This requires the `AsyncQueryAgent` class (instantiated the same way as its sync counterpart) together with an async Weaviate client. ```python import os import weaviate from weaviate.classes.init import Auth from weaviate.agents.query import AsyncQueryAgent async_client = weaviate.use_async_with_weaviate_cloud( cluster_url=os.environ.get("WEAVIATE_URL"), auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")), ) await async_client.connect() async_qa = AsyncQueryAgent(client=async_client) ``` The `.suggest_queries()` method must be awaited: ```python await async_qa.suggest_queries( collections=["FinancialContracts"], num_queries=3, instructions="High-level themes and open-ended exploration", ) ``` ::: :::tab{title="JavaScript/TypeScript"} In JavaScript/TypeScript, the `QueryAgent` is asynchronous by default — the examples in the previous sections already are asynchronous, and no separate async setup is needed. ::: :::: ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=