From bc36cf93d62a750db843300600827cc1558926a0 Mon Sep 17 00:00:00 2001 From: Connor Shorten Date: Tue, 26 May 2026 08:12:31 -0400 Subject: [PATCH 1/4] Add conversation parameter to suggestQueries Allow users to pass prior chat history so that suggested queries are contextualised as follow-up questions. --- src/query/agent.test.ts | 95 +++++++++++++++++++++++++++++++++++++++++ src/query/agent.ts | 11 +++++ 2 files changed, 106 insertions(+) diff --git a/src/query/agent.test.ts b/src/query/agent.test.ts index 352dbc6..63d2cdb 100644 --- a/src/query/agent.test.ts +++ b/src/query/agent.test.ts @@ -734,3 +734,98 @@ it("suggest queries mode failure propagates QueryAgentError", async () => { }); } }); + +it("suggest queries with conversation includes conversation_context in request body", async () => { + const mockClient = { + getConnectionDetails: jest.fn().mockResolvedValue({ + host: "test-cluster", + bearerToken: "test-token", + headers: { "X-Provider": "test-key" }, + }), + } as unknown as WeaviateClient; + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const capturedBodies: any[] = []; + + const apiSuccess: ApiSuggestQueryResponse = { + queries: [{ query: "Follow-up question?" }], + collection_count: 1, + usage: { + model_units: 1, + usage_in_plan: true, + remaining_plan_requests: 10, + }, + total_time: 0.3, + }; + + global.fetch = jest.fn((url, init?: RequestInit) => { + if (init && init.body) { + capturedBodies.push(JSON.parse(init.body as string)); + } + return Promise.resolve({ + ok: true, + json: () => Promise.resolve(apiSuccess), + } as Response); + }) as jest.Mock; + + const agent = new QueryAgent(mockClient); + + const conversation = [ + { role: "user" as const, content: "What topics are covered?" }, + { + role: "assistant" as const, + content: "The collection covers ML and economics.", + }, + ]; + + await agent.suggestQueries({ + collections: ["test_collection"], + conversation, + }); + + expect(capturedBodies[0].conversation_context).toEqual({ + messages: conversation, + }); +}); + +it("suggest queries without conversation omits conversation_context from request body", async () => { + const mockClient = { + getConnectionDetails: jest.fn().mockResolvedValue({ + host: "test-cluster", + bearerToken: "test-token", + headers: { "X-Provider": "test-key" }, + }), + } as unknown as WeaviateClient; + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const capturedBodies: any[] = []; + + const apiSuccess: ApiSuggestQueryResponse = { + queries: [{ query: "Some query?" }], + collection_count: 1, + usage: { + model_units: 1, + usage_in_plan: true, + remaining_plan_requests: 10, + }, + total_time: 0.2, + }; + + global.fetch = jest.fn((url, init?: RequestInit) => { + if (init && init.body) { + capturedBodies.push(JSON.parse(init.body as string)); + } + return Promise.resolve({ + ok: true, + json: () => Promise.resolve(apiSuccess), + } as Response); + }) as jest.Mock; + + const agent = new QueryAgent(mockClient); + + await agent.suggestQueries({ + collections: ["test_collection"], + }); + + expect(capturedBodies[0].conversation_context).toBeUndefined(); +}); diff --git a/src/query/agent.ts b/src/query/agent.ts index 2f74b7b..ab5a0ea 100644 --- a/src/query/agent.ts +++ b/src/query/agent.ts @@ -462,6 +462,8 @@ export class QueryAgent { * @param options.numQueries - The number of queries to suggest. Defaults to 3. * @param options.instructions - Optional natural language guidance for the style, topic, or * language of the suggested queries. Supplied in addition to the agent's system instructions. + * @param options.conversation - Optional conversation history to contextualise suggested queries + * as follow-up questions. Each element is a {@link ChatMessage} with `role` and `content`. * @returns A {@link SuggestQueryResponse} containing the list of suggested queries, along with * additional metadata if present. * @@ -479,6 +481,7 @@ export class QueryAgent { collections, numQueries, instructions, + conversation, }: QueryAgentSuggestQueriesOptions = {}): Promise { const targetCollections = this.validateCollections(collections); const { requestHeaders, connectionHeaders } = await getHeaders(this.client); @@ -491,6 +494,9 @@ export class QueryAgent { if (instructions !== undefined) { body.instructions = instructions; } + if (conversation !== undefined) { + body.conversation_context = { messages: conversation }; + } const response = await fetch(`${this.agentsHost}/query/suggest_queries`, { method: "POST", @@ -650,4 +656,9 @@ export type QueryAgentSuggestQueriesOptions = { * Supplied in addition to the agent's system instructions. */ instructions?: string; + /** + * Optional conversation history to contextualise suggested queries as follow-up questions. + * Each element is a {@link ChatMessage} with `role` and `content`. + */ + conversation?: ChatMessage[]; }; From c61fe315fdabfa4a21ed5009f6952bd2fa2553f4 Mon Sep 17 00:00:00 2001 From: Connor Shorten Date: Tue, 26 May 2026 08:16:34 -0400 Subject: [PATCH 2/4] fix --- src/query/agent.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/query/agent.ts b/src/query/agent.ts index ab5a0ea..4ffd140 100644 --- a/src/query/agent.ts +++ b/src/query/agent.ts @@ -474,6 +474,10 @@ export class QueryAgent { * collections: ["Products"], * numQueries: 5, * instructions: "Focus on questions about eco-friendly features.", + * conversation: [ + * { role: "user", content: "What topics are covered?" }, + * { role: "assistant", content: "The collection covers ML and economics." }, + * ], * }); * ``` */ From d0646d806987450a75aadf5485bd2a9cbc71b2ae Mon Sep 17 00:00:00 2001 From: Connor Shorten Date: Tue, 26 May 2026 08:20:52 -0400 Subject: [PATCH 3/4] fix --- src/query/agent.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/query/agent.ts b/src/query/agent.ts index 4ffd140..cc1b09d 100644 --- a/src/query/agent.ts +++ b/src/query/agent.ts @@ -28,7 +28,7 @@ import { getHeaders } from "./connection.js"; /** * An agent for executing agentic queries against Weaviate. * - * For more information, see the [Weaviate Agents - Query Agent Docs](https://weaviate.io/developers/agents). + * For more information, see the [Weaviate Agents - Query Agent docs](https://weaviate.io/developers/agents). */ export class QueryAgent { private collections?: (string | QueryAgentCollectionConfig)[]; From 9112e5b52511f5f61a64b3f8cd1cb422e0dd4d13 Mon Sep 17 00:00:00 2001 From: Connor Shorten Date: Tue, 26 May 2026 08:53:41 -0400 Subject: [PATCH 4/4] come on npm --- src/query/agent.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/query/agent.ts b/src/query/agent.ts index cc1b09d..4ffd140 100644 --- a/src/query/agent.ts +++ b/src/query/agent.ts @@ -28,7 +28,7 @@ import { getHeaders } from "./connection.js"; /** * An agent for executing agentic queries against Weaviate. * - * For more information, see the [Weaviate Agents - Query Agent docs](https://weaviate.io/developers/agents). + * For more information, see the [Weaviate Agents - Query Agent Docs](https://weaviate.io/developers/agents). */ export class QueryAgent { private collections?: (string | QueryAgentCollectionConfig)[];