Query Agent Doc Rework

.gitignore

@@ -274,3 +274,5 @@ tests/backups/
 
 # Ignore LLM/agent config files
 .claude/
+
+docs/agents old/*

_build_scripts/update-config-versions.js

@@ -14,7 +14,7 @@ const getRepoVersion = async (repoName, attempt = 1) => {
                     'User-Agent': 'request',
                     'authorization': // Use the github token if available
                         (process.env.GH_API_TOKEN) ?
-                            `Bearer ${ process.env.GH_API_TOKEN }` : ''
+                            `Bearer ${process.env.GH_API_TOKEN}` : ''
                 }
             }
         );
@@ -70,6 +70,8 @@ const appendVersionsToConfig = async (config) => {
     config.typescript_client_version = await getRepoVersion('typescript-client');
     config.helm_version = await getRepoVersion('weaviate-helm');
     config.weaviate_cli_version = await getRepoVersion('weaviate-cli');
+    config.agents_python_version = await getRepoVersion('weaviate-agents-python-client');
+    config.agents_typescript_version = await getRepoVersion('agents-typescript-client');
 
     config.spark_connector_version = await getRepoVersion('spark-connector');
 }
@@ -88,10 +90,10 @@ const updateConfigFile = async () => {
     await appendVersionsToConfig(config);
 
     fs.writeFile(path, JSON.stringify(config, null, 2), (err) => {
-      if (err) return console.log(err);
+        if (err) return console.log(err);
 
-      console.log(`Updating ${path}`)
-      console.log(JSON.stringify(config, null, 2));
+        console.log(`Updating ${path}`)
+        console.log(JSON.stringify(config, null, 2));
     });
 }
 

_includes/agents/query-agent-execution-times.mdx

@@ -4,4 +4,4 @@ This typically requires multiple calls to generative models (e.g. LLMs) and mult
 
 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](/agents/query/usage#stream-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.
+**For long-running or complex queries**, consider using [streaming responses](/agents/guides/ask_mode#streaming) 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.

docs/agents/_includes/_force_pip_install.mdx

@@ -1,7 +1,7 @@
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-#### Troubleshooting: Force `pip` to install the latest version
+#### 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](https://pypi.org/project/weaviate-agents/). If this occurs, additionally try to explicitly upgrade the `weaviate-agents` package:
 

docs/agents/_includes/code/additional_filters.mts

@@ -0,0 +1,85 @@
+import 'dotenv/config'
+import weaviate from 'weaviate-client';
+const { loadClientInternally, populateWeaviate } = await import('./util.mjs').catch(() => import('../docs/agents/_includes/code/util.mjs'));
+const client = await loadClientInternally();
+await populateWeaviate(client, false);
+
+const weatherCollection = client.collections.use('Weather');
+const financialCollection = client.collections.use('FinancialContracts');
+const ecommerceCollection = client.collections.use('ECommerce');
+
+// START OverviewInInit
+import { QueryAgent } from 'weaviate-agents';
+
+const qa = new QueryAgent(client, {
+    collections: [
+        {
+            name: 'Weather',
+            additionalFilters: weatherCollection.filter.byProperty('temperature').greaterThan(10),
+        },
+    ],
+});
+// END OverviewInInit
+
+// START OverviewInRuntime
+const runtimeConfig = {
+    name: 'Weather',
+    additionalFilters: weatherCollection.filter.byProperty('humidity').equal(39),
+};
+
+const response = await qa.ask("Provide a summary of the weather patterns", {
+    collections: [runtimeConfig],
+});
+// END OverviewInRuntime
+
+// START FilterExampleBad
+const badResponse = await qa.ask(
+    `What type of contracts have been signed and who were the authors? 
+    IMPORTANT: Only look at contracts from 2025.`,
+    {
+        collections: ['FinancialContracts'],
+    }
+);
+// END FilterExampleBad
+
+
+// START FilterExampleGood
+import { Filters } from 'weaviate-client';
+const goodResponse = await qa.ask(
+    `What products were sold last month?`,
+    {
+        collections: [
+            {
+                name: 'FinancialContracts',
+                additionalFilters: Filters.and(
+                    financialCollection.filter.byProperty('date').greaterThan(new Date(2025, 0, 1)),
+                    financialCollection.filter.byProperty('date').lessThan(new Date(2026, 0, 1)),
+                ),
+            },
+        ],
+    }
+);
+// END FilterExampleGood
+
+// START BasicFilter
+const basicFilterConfig = {
+    name: 'ECommerce',
+    additionalFilters: ecommerceCollection.filter.byProperty('category').equal('Tops'),
+};
+// END BasicFilter
+
+
+// START NestedFilter
+const nestedFilterConfig = {
+    name: 'ECommerce',
+    additionalFilters: Filters.or(
+        ecommerceCollection.filter.byProperty('category').equal('Shoes'),
+        Filters.and(
+            ecommerceCollection.filter.byProperty('price').greaterThan(50),
+            ecommerceCollection.filter.byProperty('price').lessThan(100),
+        ),
+    ),
+};
+// END NestedFilter
+
+await client.close();

docs/agents/_includes/code/additional_filters.py

@@ -0,0 +1,98 @@
+import sys
+sys.path.insert(0, "docs/agents/_includes/code")
+from util import load_client_internally, populate_weaviate
+client = load_client_internally()
+populate_weaviate(client, False)
+
+# START OverviewInInit
+from weaviate.agents.query import QueryAgent
+from weaviate.agents.classes import QueryAgentCollectionConfig
+from weaviate.classes.query import Filter
+
+qa = QueryAgent(
+    client=client,
+    collections=[
+        QueryAgentCollectionConfig(
+            name="Weather",
+            additional_filters=Filter.by_property("temperature").greater_than(10)
+        ),
+    ],
+    # END OverviewInInit
+    timeout=120,
+    # START OverviewInInit
+)
+# END OverviewInInit
+
+# START OverviewInRuntime
+runtime_config = QueryAgentCollectionConfig(
+    name="Weather",
+    additional_filters=Filter.by_property("humidity").equal(39)
+)
+
+response = qa.ask(
+    query="Provide a summary of the weather patterns", 
+    collections=[runtime_config]
+)
+# END OverviewInRuntime
+
+# START FilterExampleBad
+response = qa.ask(
+    query=(
+        "What type of contracts have been signed and who were the authors?"
+        "IMPORTANT: Only look at contracts from 2025."
+    ),
+    collections=["FinancialContracts"]
+)
+# END FilterExampleBad
+
+
+# START FilterExampleGood
+from datetime import datetime, timezone
+
+start_date = datetime(2025, 1, 1, tzinfo=timezone.utc)
+end_date = datetime(2026, 1, 1, tzinfo=timezone.utc)
+
+response = qa.ask(
+    query="What type of contracts have been signed and who were the authors?",
+    collections=[
+        QueryAgentCollectionConfig(
+            name="FinancialContracts",
+            additional_filters=(
+                Filter.all_of(
+                    [
+                        Filter.by_property("date").greater_than(start_date),
+                        Filter.by_property("date").less_than(end_date)
+                    ]
+                )
+            )
+        )
+    ]
+)
+# END FilterExampleGood
+
+# START BasicFilter
+QueryAgentCollectionConfig(
+    name="ECommerce",
+    additional_filters=Filter.by_property("category").equal("Tops")
+)
+# END BasicFilter
+
+
+# START NestedFilter
+QueryAgentCollectionConfig(
+    name="ECommerce",
+    additional_filters=Filter.any_of(
+        [
+            Filter.by_property("category").equal("Shoes"),
+            Filter.all_of(
+                [
+                    Filter.by_property("price").greater_than(50),
+                    Filter.by_property("price").less_than(100)
+                ]
+            )
+        ]
+    )
+)
+# END NestedFilter
+
+client.close()

docs/agents/_includes/code/advanced_collections.mts

@@ -0,0 +1,50 @@
+const { loadClientInternally, populateWeaviate } = await import('./util.mjs').catch(() => import('../docs/agents/_includes/code/util.mjs'));
+const client = await loadClientInternally();
+await populateWeaviate(client, false);
+
+// START SimpleConfig
+import { QueryAgent } from 'weaviate-agents';
+
+const qaSimple = new QueryAgent(client, {
+    collections: ['ECommerce', 'FinancialContracts'],
+});
+// END SimpleConfig
+
+// START AdvancedConfig
+const qa = new QueryAgent(client, {
+    collections: [
+        // Provide an object to specify further collection configuration
+        {
+            name: 'ECommerce',
+            targetVector: [
+                'name_description_brand_vector'
+            ],
+            viewProperties: [
+                'name',
+                'description',
+                'category',
+                'brand',
+            ],
+        },
+        {
+            name: 'FinancialContracts'
+        },
+    ],
+});
+// END AdvancedConfig
+
+// START RuntimeConfigAsk
+const response = await qa.ask(
+    "Recommend some shoes below $60.", {
+    collections: [
+        {
+            name: 'ECommerce',
+            targetVector: [
+                'name_description_brand_vector'
+            ],
+        }
+    ],
+});
+// END RuntimeConfigAsk
+
+await client.close()

docs/agents/_includes/code/advanced_collections.py

@@ -0,0 +1,63 @@
+import sys
+sys.path.insert(0, "docs/agents/_includes/code")
+from util import load_client_internally, populate_weaviate
+
+client = load_client_internally()
+populate_weaviate(client, False)
+
+from weaviate.agents.query import QueryAgent
+from weaviate.agents.classes import QueryAgentCollectionConfig
+
+
+# START SimpleConfig
+from weaviate.agents.query import QueryAgent
+
+qa = QueryAgent(
+    client=client,
+    collections=["ECommerce", "FinancialContracts"],
+)
+# END SimpleConfig
+
+# START AdvancedConfig
+from weaviate.agents.classes import QueryAgentCollectionConfig
+
+qa = QueryAgent(
+    client=client,
+    collections=[
+        # Use QueryAgentCollectionConfig class to provide further collection configuration
+        QueryAgentCollectionConfig(
+            name="ECommerce", 
+            target_vector=[
+                "name_description_brand_vector"
+            ], 
+            view_properties=[
+                "name",
+                "description",
+                "category",
+                "brand",
+            ],  
+        ),
+        QueryAgentCollectionConfig(
+            name="FinancialContracts"
+        ),
+    ],
+)
+
+# END AdvancedConfig
+
+
+# START RuntimeConfigAsk
+response = qa.ask(
+    "Recommend some shoes below $60.",
+    collections=[
+        QueryAgentCollectionConfig(
+            name="ECommerce",
+            target_vector=[
+                "name_description_brand_vector"
+            ],
+        ),
+    ],
+)
+# END RuntimeConfigAsk
+
+client.close()