# Introduction Weaviate Cloud only The Query Agent runs agentic search over your Weaviate Cloud database. Ask a question in natural language and the agent automatically decides which collections to search, which filters and sorts to apply, and which search types to use — all in a single call. :::callout{intent="info" title="Free tier"} Up to 250 ask queries or 1000 search queries per month, no credit card required. [Get started →](quickstart.md) ::: :::code-group{sync="languages"} ```python title="Python" from weaviate.agents.query import QueryAgent qa = QueryAgent( client=client, # your Weaviate cloud client collections=["FinancialContracts"] ) res = qa.ask("Find all contracts signed in 2025") res.display() ``` ```typescript title="JavaScript/TypeScript" import { QueryAgent } from 'weaviate-agents'; const qa = new QueryAgent( client, // your Weaviate cloud client { collections: ['FinancialContracts'], } ); const res = await qa.ask("Find all contracts signed in 2025"); res.display(); ``` ::: :::callout{intent="tip" title="Looking for agent memory?"} [Engram](../engram/overview.md) is a managed memory service that gives your agents persistent, searchable memory across conversations and users. ::: ## How the Query Agent works :::accordion{title="Example output"} ``` ╭───────────────────────────────────────────── 💬 Ask Mode Response ──────────────────────────────────────────────╮ │ │ │ The most expensive blue t-shirt is **Neotech Noir Tee** by **Vivid Verse**, priced at **$46.00**. │ │ │ │ Details: │ │ - **Product ID:** 9f9fe575-be97-46d9-a5ca-ff41ae57bef4 │ │ - **Colors:** black, blue │ │ - **Category:** Tops │ │ - **Subcategory:** T-Shirts │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭───────────────────────────────────────────────── 🔭 Search 1/1 ─────────────────────────────────────────────────╮ │ │ │ QueryResultWithCollectionNormalized( │ │ query=None, │ │ filters=FilterAndOr( │ │ combine='AND', │ │ filters=[ │ │ TextPropertyFilter( │ │ property_name='subcategory', │ │ operator=, │ │ value=['blue'] │ │ ) │ │ ] │ │ ), │ │ collection='ECommerce', │ │ sort_property=QuerySort(property_name='price', order='descending', tie_break=None), │ │ uuid_value=None │ │ ) │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭────────────────────────────────────────────── 📊 Aggregation 1/1 ───────────────────────────────────────────────╮ │ │ │ AggregationResultWithCollectionNormalized( │ │ groupby_property=None, │ │ aggregation=IntegerPropertyAggregation(property_name='price', metrics=), │ │ filters=FilterAndOr( │ │ combine='AND', │ │ filters=[ │ │ TextPropertyFilter( │ │ property_name='category', │ │ operator=, │ │ value=['blue'] │ │ ) │ │ ] │ │ ), │ │ collection='ECommerce' │ │ ) │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` ::: ## What is the Query Agent? ![Weaviate Query Agent from a user perspective](/assets/docs/query-agent/_includes/query_agent_architecture_light.png "Weaviate Query Agent from a user perspective") ![Weaviate Query Agent from a user perspective](/assets/docs/query-agent/_includes/query_agent_architecture_dark.png "Weaviate Query Agent from a user perspective") The Weaviate Query Agent connects to your pre-existing Weaviate database and transforms natural language queries into actionable searches using an LLM. It can perform multiple searches and aggregations across one or more collections, dynamically deciding which collection(s) to search on, creating custom filters, group bys, sorts, and search types, all depending on a single natural language question. It is designed as a pre-built agentic service for your data, with two main modes: - [**Ask Mode**](../modes/ask-mode.md): Return a natural language answer after searching your data. Chat-like; best for end-user-facing apps where the user wants a written response instead of raw data. - [**Search Mode**](../modes/search-mode.md): Return the raw matching objects directly from your collection(s), with filters, sorts, and search types chosen for you. Lookup-like; best for internal search, dashboards, or the retrieval step in a larger pipeline. ### Example use cases - **Customer-facing chat assistant** (Ask Mode) — Answer questions like _"Recommend me vintage shoes under $70 in size 9"_ with a written response, sourced from your product catalog. - **Natural-language filter on an internal dashboard** (Search Mode) — Turn _"orders flagged last week from EU customers"_ into a filtered Weaviate query and render the rows in your UI. - **Retrieval step inside your own RAG or agent stack** (Search Mode) — Fetch the most relevant objects via the agent, then pass them to a downstream generative step you control. ## Get started :::callout{intent="info" title="Query Agent in cloud"} [You can try the Query Agent without any setup on Weaviate Cloud. Simply go to the 'Agents' tab to start asking questions about data in your collections.](/go/console?utm_content=agents) ::: You need a Weaviate Cloud cluster — [the free tier is free forever](https://weaviate.io/pricing). With a cluster and some data, install [the Python or TypeScript client](installation.md) and you can run your first query in minutes. Already have a cluster but no data? Upload via CSV in the cloud console, or [via the Weaviate APIs](../how-to-manage-objects/create.md). ## Further resources - [**Quickstart**](quickstart.md) — Set up the client and run your first ask and search calls. - [**Modes**](../modes/index.md) — Detailed pages on Ask Mode, Search Mode, and other modes. - [**Configuration**](../agents-configuration/instantiation.md) — Constructor options, collection configuration, additional filters, system prompts, and conversational inputs. - [**Recipes**](../tutorials-and-guides/index.md) — End-to-end example notebooks. ## 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=