From 22e8f9701a6cab954d04a31d132eb4cd3a917c8f Mon Sep 17 00:00:00 2001
From: chengke <404835780@qq.com>
Date: Tue, 11 Aug 2026 15:51:18 +0800
Subject: [PATCH 1/2] fix: omit Knowledge.search useAgentic so API map-nav
 default applies

Stop coercing undefined to false, which forced classic retrieval for the
Knowledge helper while the retrieval API defaults to map-nav.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/knowledge/__tests__/knowledge.test.ts | 24 +++++++++++++++++++++++
 src/knowledge/knowledge.ts                |  3 ++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/src/knowledge/__tests__/knowledge.test.ts b/src/knowledge/__tests__/knowledge.test.ts
index 09259bc..7edf1f6 100644
--- a/src/knowledge/__tests__/knowledge.test.ts
+++ b/src/knowledge/__tests__/knowledge.test.ts
@@ -780,6 +780,30 @@ describe('Knowledge', () => {
     });
   });
 
+  it('should omit useAgentic when unset so API map-nav default applies', async () => {
+    const cacheDirectory = await createTempDirectory();
+    const { client, retrievalQuery } = createClient(createParseResult());
+    const knowledge = new Knowledge(client, { cacheDirectory });
+    await knowledge.parseToLocalCache({
+      url: 'https://example.com/report.md',
+      localDocumentId: 'local-report',
+    });
+
+    await knowledge.search({
+      query: 'margin',
+      namespace: 'support-center',
+      localDocumentIds: ['local-report'],
+      topK: 2,
+    });
+
+    expect(retrievalQuery).toHaveBeenCalledWith({
+      query: 'margin',
+      namespace: 'support-center',
+      topK: 2,
+      useAgentic: undefined,
+    });
+  });
+
   it('should search through Knowhere API retrieval', async () => {
     const cacheDirectory = await createTempDirectory();
     const { client, retrievalQuery } = createClient(createParseResult());
diff --git a/src/knowledge/knowledge.ts b/src/knowledge/knowledge.ts
index 7dde3b0..a7c9003 100644
--- a/src/knowledge/knowledge.ts
+++ b/src/knowledge/knowledge.ts
@@ -482,7 +482,8 @@ export class Knowledge {
       query: params.query,
       namespace: params.namespace,
       topK: params.topK,
-      useAgentic: params.useAgentic ?? false,
+      // Omit when undefined so the API default (map-nav) applies; false → classic.
+      useAgentic: params.useAgentic,
     });
     const documentByServerId = new Map(
       localDocuments

From 712cc84e2a306370b5a1d40f63b36756ec9fd98e Mon Sep 17 00:00:00 2001
From: chengke <404835780@qq.com>
Date: Tue, 11 Aug 2026 15:57:19 +0800
Subject: [PATCH 2/2] chore: add changeset for Knowledge.search useAgentic
 default

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/knowledge-search-omit-use-agentic.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/knowledge-search-omit-use-agentic.md

diff --git a/.changeset/knowledge-search-omit-use-agentic.md b/.changeset/knowledge-search-omit-use-agentic.md
new file mode 100644
index 0000000..9bb24c4
--- /dev/null
+++ b/.changeset/knowledge-search-omit-use-agentic.md
@@ -0,0 +1,5 @@
+---
+"@ontos-ai/knowhere-sdk": patch
+---
+
+Omit unset `useAgentic` in `Knowledge.search` so the API map-nav default applies instead of forcing classic retrieval.