Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(agent): align web_search count limit with the configured maximum (#4011)
Jundong Zhang40eb34bc849c
diff --git a/internal/agent/tools/web_pages_test.go b/internal/agent/tools/web_pages_test.goindex 4a3ee37f2..d955e57c1 100644--- a/internal/agent/tools/web_pages_test.go+++ b/internal/agent/tools/web_pages_test.go@@ -139,8 +139,11 @@ func TestSearchOptionsAndExplicitPageContent(t *testing.T) {require.Contains(t, model, `status="success" verified="true"`)require.Contains(t, model, rows[0]["full_output_path"])require.Contains(t, model, "still useful")+ // Only values with no nearest legal alternative stay failures: an unsupported+ // filter value has nothing to fall back to. An over-maximum count is clamped+ // instead (see TestAgentWebSearchClampsCountToConfiguredMaximum).for _, args := range []string{- `{"query":"q","count":0}`, `{"query":"q","count":6}`,+ `{"query":"q","count":0}`,`{"query":"q","country":"bad"}`, `{"query":"q","freshness":"tomorrow"}`,} {calls := svc.callsdiff --git a/internal/agent/tools/web_search.go b/internal/agent/tools/web_search.goindex 551543991..df4f14a47 100644--- a/internal/agent/tools/web_search.go+++ b/internal/agent/tools/web_search.go@@ -48,7 +48,7 @@ var webSearchTool = BaseTool{// WebSearchInput defines the input parameters for web search tooltype WebSearchInput struct {Query string `json:"query" jsonschema:"Search query string"`- Count *int `json:"count,omitempty" jsonschema:"1 to configured maximum (at most 20)"`+ Count *int `json:"count,omitempty" jsonschema:"Number of results to return (1 to the configured maximum)"`Country string `json:"country,omitempty" jsonschema:"Two-letter code or ALL (Brave, Serply); omit for default"`Freshness string `json:"freshness,omitempty" jsonschema:"pd/pw/pm/py; Brave also accepts YYYY-MM-DDtoYYYY-MM-DD"`Content bool `json:"content,omitempty" jsonschema:"Fetch page excerpts; default false"`@@ -75,6 +75,8 @@ func NewWebSearchTool(}maxResults = min(maxResults, 20)tool.description = fmt.Sprintf(tool.description, maxResults)+ // The static schema cannot express the configured maximum; rewrite the count description.+ tool.schema = patchWebSearchCountSchema(tool.schema, maxResults)return &WebSearchTool{BaseTool: tool,@@ -85,6 +87,31 @@ func NewWebSearchTool(}}+// patchWebSearchCountSchema rewrites the count description with the effective+// maximum. Any parse failure returns the schema unchanged.+func patchWebSearchCountSchema(raw json.RawMessage, maxResults int) json.RawMessage {+ var schema map[string]any+ if err := json.Unmarshal(raw, &schema); err != nil {+ return raw+ }+ props, ok := schema["properties"].(map[string]any)+ if !ok {+ return raw+ }+ count, ok := props["count"].(map[string]any)+ if !ok {+ return raw+ }+ count["description"] = fmt.Sprintf(+ "Number of results to return, 1 to %d (the configured maximum). Omit to use the maximum.",+ maxResults)+ patched, err := json.Marshal(schema)+ if err != nil {+ return raw+ }+ return patched+}+// WithPageReader shares page snapshots and full-output storage with web_fetch.func (t *WebSearchTool) WithPageReader(reader *WebFetchTool) *WebSearchTool {t.pages = reader@@ -106,13 +133,32 @@ func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (*typ}maxResults := t.maxResults+ countClamped := false+ countRequested := 0if input.Count != nil {- if *input.Count < 1 || *input.Count > maxResults {+ requested := *input.Count+ switch {+ case requested < 1:+ logger.Warnf(ctx, "[Tool][WebSearch] count %d is below the minimum 1", requested)return &types.ToolResult{Success: false, Error: fmt.Sprintf("count must be between 1 and %d", maxResults),}, nil+ case requested > maxResults:+ countClamped = true+ countRequested = requested+ logger.Warnf(ctx, "[Tool][WebSearch] count %d exceeds the configured maximum %d; clamped",+ requested, maxResults)+ default:+ maxResults = requested}- maxResults = *input.Count+ }+ // A clamped count is stated twice on purpose: Output serves the UI, logs and the+ // zero-result fallback, while Data reaches the model through the rendered+ // retrieval block (sourceOutput tools never see Output once there is a row).+ clampNote := ""+ if countClamped {+ clampNote = fmt.Sprintf("Note: requested count %d is outside 1-%d and was clamped to %d.\n",+ countRequested, t.maxResults, maxResults)}filters := types.WebSearchFilters{Country: strings.ToUpper(strings.TrimSpace(input.Country)), Freshness: strings.TrimSpace(input.Freshness),@@ -211,14 +257,18 @@ func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (*typ// Format outputif len(webResults) == 0 {+ output := fmt.Sprintf("No web search results found for query: %s", query)+ if clampNote != "" {+ output += "\n" + clampNote+ }return &types.ToolResult{Success: true,- Output: fmt.Sprintf("No web search results found for query: %s", query),- Data: map[string]interface{}{+ Output: output,+ Data: t.countClampData(map[string]interface{}{"query": query,"results": []interface{}{},"count": 0,- },+ }, countClamped, countRequested),}, nil}@@ -230,7 +280,11 @@ func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (*typ// Build output textoutput := "=== Web Search Results ===\n"output += fmt.Sprintf("Query: %s\n", query)- output += fmt.Sprintf("Found %d result(s)\n\n", len(webResults))+ output += fmt.Sprintf("Found %d result(s)\n", len(webResults))+ if countClamped {+ output += clampNote+ }+ output += "\n"// Format resultsformattedResults := make([]map[string]interface{}, 0, len(webResults))@@ -290,15 +344,30 @@ func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (*typreturn &types.ToolResult{Success: true,Output: output,- Data: map[string]interface{}{+ Data: t.countClampData(map[string]interface{}{"query": query,"results": formattedResults,"count": len(webResults),"display_type": "web_search_results",- },+ }, countClamped, countRequested),}, nil}+// countClampData records a clamped count in Data so the model-side renderer can+// restate it inside the retrieval block. Tools with sourceOutput enabled never+// expose ToolResult.Output to the model once there is at least one row.+func (t *WebSearchTool) countClampData(+ data map[string]interface{}, clamped bool, requested int,+) map[string]interface{} {+ if !clamped {+ return data+ }+ data["count_clamped"] = true+ data["count_requested"] = requested+ data["count_maximum"] = t.maxResults+ return data+}+func (t *WebSearchTool) fetchLeadingPages(ctx context.Context, results []*types.WebSearchResult) []*webFetchItemResult {n := min(webSearchContentMaxPages, len(results))pages := make([]*webFetchItemResult, n)diff --git a/internal/agent/tools/web_search_test.go b/internal/agent/tools/web_search_test.goindex 1da101022..69ebc2f37 100644--- a/internal/agent/tools/web_search_test.go+++ b/internal/agent/tools/web_search_test.go@@ -3,8 +3,10 @@ package toolsimport ("context""encoding/json"+ "fmt""testing"+ "github.com/Tencent/WeKnora/internal/modelcontext""github.com/Tencent/WeKnora/internal/types""github.com/Tencent/WeKnora/internal/types/interfaces""github.com/stretchr/testify/assert"@@ -96,3 +98,107 @@ func TestAgentWebSearchContentFetchesLeadingPagesOnly(t *testing.T) {assert.Equal(t, "skipped", rows[4]["page_status"])assert.Equal(t, "d", rows[3]["snippet"])}++// TestAgentWebSearchClampsCountToConfiguredMaximum an over-maximum count is+// clamped to the configured maximum instead of failing the whole call, and the+// correction reaches both the UI-facing output and the rendered model view.+func TestAgentWebSearchClampsCountToConfiguredMaximum(t *testing.T) {+ svc := &searchOnlyWebService{results: []*types.WebSearchResult{+ {URL: "https://example.com/a"},+ {URL: "https://example.com/b"},+ {URL: "https://example.com/c"},+ }}+ tool := NewWebSearchTool(svc, 2, "provider-1")+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))++ result, err := tool.Execute(ctx, json.RawMessage(`{"query":"q","count":3}`))+ require.NoError(t, err)+ require.True(t, result.Success)+ require.Equal(t, 1, svc.calls, "the search must still run")+ require.Equal(t, 2, svc.config.MaxResults, "count must clamp to the maximum")+ require.Contains(t, result.Output, "requested count 3 is outside 1-2 and was clamped to 2.")+ require.Equal(t, true, result.Data["count_clamped"])+ require.Equal(t, 3, result.Data["count_requested"])+ require.Equal(t, 2, result.Data["count_maximum"])++ // The model reads the rendered retrieval block, not Output, once a row exists.+ model := modelcontext.NewRegistry(true).ModelToolResultForTool(ToolWebSearch, result)+ require.Contains(t, model, `<count_clamped requested="3" maximum="2">`)+}++// TestAgentWebSearchRejectsNonPositiveCount a count below 1 is a malformed+// argument, not a near miss: it fails before the provider is called.+func TestAgentWebSearchRejectsNonPositiveCount(t *testing.T) {+ svc := &searchOnlyWebService{results: []*types.WebSearchResult{{URL: "https://example.com/a"}}}+ tool := NewWebSearchTool(svc, 2, "provider-1")+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))++ for _, count := range []int{-1, 0} {+ svc.calls = 0+ result, err := tool.Execute(ctx, json.RawMessage(fmt.Sprintf(`{"query":"q","count":%d}`, count)))+ require.NoError(t, err)+ require.False(t, result.Success, "count=%d must fail", count)+ require.Contains(t, result.Error, "count must be between 1 and 2")+ require.Equal(t, 0, svc.calls, "count=%d must not reach the provider", count)+ }+}++// TestAgentWebSearchClampNoteSurvivesEmptyResults the zero-result early return+// must carry the same correction as the normal path.+func TestAgentWebSearchClampNoteSurvivesEmptyResults(t *testing.T) {+ svc := &searchOnlyWebService{}+ tool := NewWebSearchTool(svc, 2, "provider-1")+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))++ result, err := tool.Execute(ctx, json.RawMessage(`{"query":"q","count":5}`))+ require.NoError(t, err)+ require.True(t, result.Success)+ require.Equal(t, 1, svc.calls)+ require.Equal(t, 2, svc.config.MaxResults)+ require.Contains(t, result.Output, "was clamped to 2.")+ require.Equal(t, true, result.Data["count_clamped"])++ model := modelcontext.NewRegistry(true).ModelToolResultForTool(ToolWebSearch, result)+ require.Contains(t, model, "was clamped to 2.")+}++// TestAgentWebSearchCountWithinRangeIsHonoured an in-range count is honoured as given, with no note.+func TestAgentWebSearchCountWithinRangeIsHonoured(t *testing.T) {+ svc := &searchOnlyWebService{results: []*types.WebSearchResult{+ {URL: "https://example.com/a"},+ {URL: "https://example.com/b"},+ }}+ tool := NewWebSearchTool(svc, 5, "provider-1")+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))++ result, err := tool.Execute(ctx, json.RawMessage(`{"query":"q","count":1}`))+ require.NoError(t, err)+ require.True(t, result.Success)+ require.Equal(t, 1, svc.config.MaxResults)+ require.NotContains(t, result.Output, "was clamped")+}++// TestPatchWebSearchCountSchema the effective maximum must reach the schema, and+// any malformed input leaves the schema unchanged rather than breaking the tool.+func TestPatchWebSearchCountSchema(t *testing.T) {+ raw := json.RawMessage(`{"type":"object","properties":{` ++ `"query":{"type":"string"},"count":{"type":"integer","description":"old"}},"required":["query"]}`)++ var schema map[string]any+ require.NoError(t, json.Unmarshal(patchWebSearchCountSchema(raw, 7), &schema))+ props, ok := schema["properties"].(map[string]any)+ require.True(t, ok)+ count, ok := props["count"].(map[string]any)+ require.True(t, ok)+ assert.Equal(t,+ "Number of results to return, 1 to 7 (the configured maximum). Omit to use the maximum.",+ count["description"])+ assert.Equal(t, "object", schema["type"])+ assert.Equal(t, []any{"query"}, schema["required"])++ broken := json.RawMessage(`not json`)+ assert.Equal(t, broken, patchWebSearchCountSchema(broken, 7))++ noProperties := json.RawMessage(`{"type":"object"}`)+ assert.Equal(t, noProperties, patchWebSearchCountSchema(noProperties, 7))+}diff --git a/internal/modelcontext/model_output.go b/internal/modelcontext/model_output.goindex 7de0fad62..28539e5fe 100644--- a/internal/modelcontext/model_output.go+++ b/internal/modelcontext/model_output.go@@ -58,7 +58,8 @@ func (r *sourceRegistry) ModelOutput(result *types.ToolResult) string {return annotateGraphResult(r.modelKnowledgeOutput("graph", mapsValue(result.Data["results"]), result.Output), result.Data)case "web_search_results":- return r.modelWebSearchOutput(mapsValue(result.Data["results"]), result.Output)+ return annotateWebSearchNotes(+ r.modelWebSearchOutput(mapsValue(result.Data["results"]), result.Output), result.Data)case "database_query":return r.modelDatabaseQueryOutput(mapsValue(result.Data["rows"]), result.Output)default:@@ -418,6 +419,25 @@ func annotateSearchNotes(output string, data map[string]interface{}) string {return strings.TrimSuffix(output, "</retrieval>") + b.String() + "</retrieval>"}+// annotateWebSearchNotes restates a clamped count inside the retrieval block.+// web_search also writes the note into ToolResult.Output, but once there is at+// least one row the model only sees this rendered view, so the note has to+// travel in Data — the same reason annotateSearchNotes reads Data, not Output.+func annotateWebSearchNotes(output string, data map[string]interface{}) string {+ if !boolValue(data, "count_clamped") || !strings.HasSuffix(output, "</retrieval>") {+ return output+ }+ requested := intValue(data, "count_requested")+ maximum := intValue(data, "count_maximum")+ if requested < 1 || maximum < 1 {+ return output+ }+ note := fmt.Sprintf(" <count_clamped requested=\"%d\" maximum=\"%d\">The requested count is "++ "outside 1-%d and was clamped to %d. Ask for a value in range, or omit count to use the "++ "maximum.</count_clamped>\n", requested, maximum, maximum, maximum)+ return strings.TrimSuffix(output, "</retrieval>") + note + "</retrieval>"+}+func viewForRow(row map[string]interface{}, mode string) string {if stringValue(row, "content") != "" {return "full"diff --git a/website-docs/03-features/11-web-search.md b/website-docs/03-features/11-web-search.mdindex c630081a1..12f765256 100644--- a/website-docs/03-features/11-web-search.md+++ b/website-docs/03-features/11-web-search.md@@ -102,7 +102,7 @@ flowchart TD{"query":"Rust release notes","country":"DE","freshness":"pw","content":true}```-- `count` 指定结果数量,范围是 1 到当前 Agent 配置的最大结果数(最多 20);省略时沿用现有 Agent 默认值。+- `count` 指定结果数量,范围是 1 到当前 Agent 配置的最大结果数(最多 20);省略时沿用现有 Agent 默认值。超出上限时截断到上限,并在模型可见的输出里附一句纠正提示,不会让整轮调用失败;小于 1 的取值返回参数错误。- `country` / `freshness` 通过 Brave 与 Serply 提供商生效。地区接受两字母代码或 `ALL`,时效接受 `pd` / `pw` / `pm` / `py` 或 `YYYY-MM-DDtoYYYY-MM-DD`。省略 `country` 时不向 Brave 传该参数(Brave 自身默认 US);显式 `ALL` 表示全球结果。Serply 的 `country` 映射为 Google 的 `gl`(省略或 `ALL` 时不传 `gl`,由 Google 决定地区),`freshness` 只接受 `pd` / `pw` / `pm` / `py`。其它提供商暂不支持这些过滤,显式传入时返回错误,不会静默忽略。参数取值参见 [Brave 官方 API 文档](https://api-dashboard.search.brave.com/api-reference/web/search/get)。- `content` 默认关闭。设为 `true` 时,并行抓取前 3 条结果的正文(整批 15 秒预算,每页最多 5,000 字符摘录);其余结果保留搜索摘要,需用 `web_fetch` 继续读页。抓取失败仍保留摘要;完整正文地址通过 `full_output_path` 返回。搜索和独立 `web_fetch` 共用本轮快照,短超时不会取消正在进行的共享抓取。- Brave 的相对 `age` 原样保留,避免把“2 days ago”伪造为精确发布日期。