Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

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.go
index 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.calls
diff --git a/internal/agent/tools/web_search.go b/internal/agent/tools/web_search.go
index 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 tool
type 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 := 0
if 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 output
if 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 text
output := "=== 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 results
formattedResults := make([]map[string]interface{}, 0, len(webResults))
@@ -290,15 +344,30 @@ func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (*typ
return &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.go
index 1da101022..69ebc2f37 100644
--- a/internal/agent/tools/web_search_test.go
+++ b/internal/agent/tools/web_search_test.go
@@ -3,8 +3,10 @@ package tools
import (
"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.go
index 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.md
index 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”伪造为精确发布日期。