fix(go-agent): add Google search wrapper component and tool registry (#16768)

### Summary

- Implemented googleComponent wrapper to bridge the canvas component
contract with Eino's SerpApi-backed GoogleTool.
- Added parameter alias mapping (query to q, max_results to num) and
content formatting logic to match Python search result representation.
- Registered the "Google" component and the "google" tool factory in the
Go agent runtime to support web search nodes.

<img width="1776" height="1092" alt="image"
src="https://github.com/user-attachments/assets/e295ab88-e48c-4fe2-bcb7-47ca5b977c9b"
/>

internal/agent/component/fixture_stubs.go

@@ -518,5 +518,6 @@ func init() {
 	Register(componentNameIteration, NewIterationStub)
 	Register(componentNameIterationItem, NewIterationItemStub)
 	Register("BGPT", newBGPTComponent)
+	Register("Google", newGoogleComponent)
 	Register("YahooFinance", newYahooFinanceComponent)
 }

internal/agent/component/google_component_test.go

@@ -0,0 +1,71 @@
+//
+//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+package component
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+func TestGoogleComponent_RegisteredAndInputForm(t *testing.T) {
+	c, err := New("Google", map[string]any{
+		"api_key":  "",
+		"country":  "us",
+		"language": "en",
+	})
+	if err != nil {
+		t.Fatalf("New(Google): %v", err)
+	}
+	if got := c.Name(); got != "Google" {
+		t.Fatalf("Name() = %q, want Google", got)
+	}
+	formGetter, ok := c.(interface{ GetInputForm() map[string]any })
+	if !ok {
+		t.Fatal("Google component does not expose GetInputForm")
+	}
+	form := formGetter.GetInputForm()
+	if _, ok := form["q"]; !ok {
+		t.Fatalf("GetInputForm missing q: %+v", form)
+	}
+	if _, ok := c.Outputs()["formalized_content"]; !ok {
+		t.Fatal("Outputs() missing formalized_content")
+	}
+	if _, ok := c.Outputs()["json"]; !ok {
+		t.Fatal("Outputs() missing json")
+	}
+}
+
+func TestGoogleComponent_MissingAPIKeyMatchesToolError(t *testing.T) {
+	c, err := New("Google", map[string]any{})
+	if err != nil {
+		t.Fatalf("New(Google): %v", err)
+	}
+	out, err := c.Invoke(context.Background(), map[string]any{"q": "ragflow"})
+	if err != nil {
+		t.Fatalf("Invoke returned error: %v", err)
+	}
+	if got, _ := out["_ERROR"].(string); !strings.Contains(got, "api_key") {
+		t.Fatalf("_ERROR = %q, want api_key error (out=%+v)", got, out)
+	}
+	if got, ok := out["formalized_content"].(string); !ok || got != "" {
+		t.Fatalf("formalized_content = %#v, want empty string", out["formalized_content"])
+	}
+	if got := anySlice(out["json"]); len(got) != 0 {
+		t.Fatalf("json len = %d, want 0", len(got))
+	}
+}

internal/agent/component/tool_dispatch_test.go

@@ -79,3 +79,30 @@ func TestPhase3_6_ToolDSLLoading(t *testing.T) {
 		t.Errorf("Tools not preserved: %v", captured.Tools)
 	}
 }
+
+func TestAgent_GoogleToolDSLParamsLoading(t *testing.T) {
+	c := NewAgentComponent(AgentParam{
+		ModelID:   "stub",
+		MaxRounds: 1,
+		Tools:     []string{"google"},
+		ToolParams: map[string]map[string]any{
+			"google": {
+				"api_key":  "KEY",
+				"country":  "us",
+				"language": "en",
+			},
+		},
+	})
+	form := c.GetInputForm()
+	googleForm, ok := form["google"].(map[string]any)
+	if !ok {
+		t.Fatalf("GetInputForm missing google tool form: %+v", form)
+	}
+	if _, ok := googleForm["q"]; !ok {
+		t.Fatalf("google tool form missing q: %+v", googleForm)
+	}
+
+	if _, err := buildAgentTools(c.param); err != nil {
+		t.Fatalf("buildAgentTools with google params: %v", err)
+	}
+}

internal/agent/component/universe_a_wrappers.go

@@ -122,6 +122,132 @@ func (c *tavilySearchComponent) Stream(_ context.Context, _ map[string]any) (<-c
 	return nil, nil
 }
 
+// googleComponent wraps internal/agent/tool/GoogleTool for canvas execution and
+// adapts the tool envelope to the Google component outputs.
+type googleComponent struct {
+	inner  *agenttool.GoogleTool
+	params map[string]any
+}
+
+func newGoogleComponent(params map[string]any) (Component, error) {
+	cloned := make(map[string]any, len(params))
+	for k, v := range params {
+		cloned[k] = v
+	}
+	return &googleComponent{inner: agenttool.NewGoogleTool(), params: cloned}, nil
+}
+
+func (c *googleComponent) Name() string { return "Google" }
+
+func (c *googleComponent) Inputs() map[string]string {
+	return map[string]string{
+		"q":        "Search query.",
+		"api_key":  "SerpApi API key.",
+		"start":    "Result offset.",
+		"num":      "Maximum number of results.",
+		"country":  "Google country code.",
+		"language": "Google language code.",
+	}
+}
+
+func (c *googleComponent) GetInputForm() map[string]any {
+	return agenttool.NewGoogleTool().InputForm()
+}
+
+func (c *googleComponent) Outputs() map[string]string {
+	return map[string]string{
+		"formalized_content": "Rendered search results for downstream LLM prompts.",
+		"json":               "Raw Google organic result list.",
+	}
+}
+
+func (c *googleComponent) Invoke(ctx context.Context, inputs map[string]any) (map[string]any, error) {
+	merged := make(map[string]any, len(c.params)+len(inputs)+2)
+	for k, v := range c.params {
+		merged[k] = v
+	}
+	for k, v := range inputs {
+		merged[k] = v
+	}
+	if _, ok := merged["q"]; !ok {
+		if query, ok := merged["query"]; ok {
+			merged["q"] = query
+		}
+	}
+	if _, ok := merged["num"]; !ok {
+		if maxResults, ok := merged["max_results"]; ok {
+			merged["num"] = maxResults
+		}
+	}
+
+	argsJSON, _ := json.Marshal(merged)
+	out, err := c.inner.InvokableRun(ctx, string(argsJSON))
+	decoded := parseToolEnvelope(out)
+	results := anySlice(decoded["organic_results"])
+	if len(results) == 0 {
+		results = anySlice(decoded["results"])
+	}
+	formalized := renderGoogleResults(results)
+	if existing, _ := decoded["_ERROR"].(string); strings.TrimSpace(existing) != "" {
+		return map[string]any{"formalized_content": formalized, "json": results, "_ERROR": existing}, nil
+	}
+	if err != nil {
+		if len(decoded) > 0 {
+			return map[string]any{"formalized_content": formalized, "json": results, "_ERROR": decoded["_ERROR"]}, nil
+		}
+		return nil, fmt.Errorf("canvas: Google: %w", err)
+	}
+	return map[string]any{"formalized_content": formalized, "json": results}, nil
+}
+
+func (c *googleComponent) Stream(_ context.Context, _ map[string]any) (<-chan map[string]any, error) {
+	return nil, nil
+}
+
+func renderGoogleResults(results []any) string {
+	if len(results) == 0 {
+		return ""
+	}
+	blocks := make([]string, 0, len(results))
+	for _, item := range results {
+		m, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		title := strings.TrimSpace(stringParam(m["title"]))
+		link := strings.TrimSpace(stringParam(m["link"]))
+		content := strings.TrimSpace(stringParam(m["snippet"]))
+		if content == "" {
+			content = strings.TrimSpace(googleAboutDescription(m["about_this_result"]))
+		}
+		if content == "" {
+			continue
+		}
+		lines := []string{}
+		if title != "" {
+			lines = append(lines, "Title: "+title)
+		}
+		if link != "" {
+			lines = append(lines, "URL: "+link)
+		}
+		lines = append(lines, "Content: "+content)
+		blocks = append(blocks, strings.Join(lines, "\n"))
+	}
+	return strings.Join(blocks, "\n\n")
+}
+
+func googleAboutDescription(v any) string {
+	about, ok := v.(map[string]any)
+	if !ok {
+		return ""
+	}
+	source, ok := about["source"].(map[string]any)
+	if !ok {
+		return ""
+	}
+	return stringParam(source["description"])
+}
+
 // tavilyExtractComponent delegates to internal/agent/tool/TavilyExtractTool.
 type tavilyExtractComponent struct {
 	inner  *agenttool.TavilyExtractTool
@@ -1181,6 +1307,7 @@ func (c *yahooFinanceComponent) Stream(_ context.Context, _ map[string]any) (<-c
 var (
 	_ Component = (*retrievalComponent)(nil)
 	_ Component = (*tavilySearchComponent)(nil)
+	_ Component = (*googleComponent)(nil)
 	_ Component = (*tavilyExtractComponent)(nil)
 	_ Component = (*exesqlComponent)(nil)
 	_ Component = (*codeExecComponent)(nil)
@@ -1190,5 +1317,6 @@ var (
 // Compile-time check that the eino InvokableTool methods we call
 // are reachable (catches a future refactor that renames them).
 var _ einotool.InvokableTool = (*agenttool.TavilyTool)(nil)
+var _ einotool.InvokableTool = (*agenttool.GoogleTool)(nil)
 var _ einotool.InvokableTool = (*agenttool.TavilyExtractTool)(nil)
 var _ einotool.InvokableTool = (*agenttool.YahooFinanceTool)(nil)

internal/agent/component/verify_p1_test.go

@@ -9,11 +9,12 @@ import (
 // TestVerifyRegistration_P1 verifies all components are registered,
 // case-insensitive, and returned in sorted order. The expected count is
 // read from plan §2.11.10 — P0 (8) + P1 (5) + P2 (4) + P3 (2) + P4 (3) = 22
-// at plan completion, plus 7 v1 fixture stubs (Retrieval, TavilySearch,
-// ExeSQL, Generate, Answer, Iteration, IterationItem) registered by
-// v1_stubs.go to keep the dsl-examples e2e suite compiling. The test
-// allows counts between 12 (P0+P1 minus the removed ExitLoop) and 30
-// (the 22 plan components + the 7 v1 stubs + Parallel) to roll
+// at plan completion, plus v1 fixture wrappers/stubs (including Retrieval,
+// TavilySearch, TavilyExtract, ExeSQL, Google, BGPT, YahooFinance, Generate,
+// Answer, Iteration, and IterationItem) registered by fixture_stubs.go to keep
+// the dsl-examples and canvas tool surface compiling. The test allows counts
+// between 12 (P0+P1 minus the removed ExitLoop) and 34 (the 22 plan components
+// plus the wrappers/stubs currently registered by fixture_stubs.go) to roll
 // forward as subsequent batches land.
 //
 // Note: ExitLoop is intentionally NOT in the registry anymore. The
@@ -44,8 +45,8 @@ func TestVerifyRegistration_P1(t *testing.T) {
 	if len(missing) > 0 {
 		t.Fatalf("missing P0/P1 components: %v (have %d: %v)", missing, len(names), names)
 	}
-	if got := len(names); got < 12 || got > 33 {
-		t.Errorf("expected 12-33 registered (current plan scope + v1 wrappers/stubs), got %d: %v", got, names)
+	if got := len(names); got < 12 || got > 34 {
+		t.Errorf("expected 12-34 registered (current plan scope + v1 wrappers/stubs), got %d: %v", got, names)
 	}
 
 	// ExitLoop must NOT be in the registry (legacy compat lives at

internal/agent/tool/google.go

@@ -22,6 +22,8 @@ import (
 	"fmt"
 	"net/http"
 	"net/url"
+	"strconv"
+	"strings"
 
 	"github.com/cloudwego/eino/components/tool"
 	"github.com/cloudwego/eino/schema"
@@ -29,53 +31,38 @@ import (
 
 const googleToolName = "google"
 
-const googleToolDescription = "Search the web via Google Programmable Search (CSE). Returns items[].{title, link, snippet}."
+const googleToolDescription = "Search the web via Google using SerpApi. Returns organic_results[].{title, link, snippet}."
 
-// googleParams is the JSON shape the model sends into InvokableRun. The
-// api_key (CX search-engine id) and cx are both required by the upstream
-// API; api_key is the Programmable Search API key and cx is the
-// search-engine ID.
+// googleParams is the JSON shape the model or canvas sends into InvokableRun.
 type googleParams struct {
-	APIKey     string `json:"api_key"`
-	CX         string `json:"cx"`
-	Query      string `json:"query"`
-	MaxResults int    `json:"max_results"`
+	APIKey   string `json:"api_key"`
+	Q        string `json:"q"`
+	Start    int    `json:"start"`
+	Num      int    `json:"num"`
+	Country  string `json:"country"`
+	Language string `json:"language"`
 }
 
-// googleResult mirrors one element of the upstream `items` array.
-type googleResult struct {
-	Title   string `json:"title"`
-	Link    string `json:"link"`
-	Snippet string `json:"snippet"`
-}
+type googleResult map[string]any
 
-// googleResponse is the upstream Programmable Search envelope. We only
-// model the fields we care about.
 type googleResponse struct {
-	Items []googleResult `json:"items"`
+	OrganicResults []googleResult `json:"organic_results"`
 }
 
-// googleEnvelope is what the model sees.
 type googleEnvelope struct {
 	Results []googleResult `json:"results"`
 	Error   string         `json:"_ERROR,omitempty"`
 }
 
-// GoogleTool is the Google
-// Programmable Search tool.
-// It performs a GET against the CSE endpoint using the shared
-// HTTPHelper.
 type GoogleTool struct {
-	helper *HTTPHelper
+	helper   *HTTPHelper
+	defaults googleParams
 }
 
-// NewGoogleTool returns a GoogleTool using the default HTTPHelper.
 func NewGoogleTool() *GoogleTool {
 	return NewGoogleToolWith(NewHTTPHelper())
 }
 
-// NewGoogleToolWith returns a GoogleTool that uses the provided
-// HTTPHelper. Useful for tests.
 func NewGoogleToolWith(h *HTTPHelper) *GoogleTool {
 	if h == nil {
 		h = NewHTTPHelper()
@@ -83,71 +70,103 @@ func NewGoogleToolWith(h *HTTPHelper) *GoogleTool {
 	return &GoogleTool{helper: h}
 }
 
-// Info returns the tool's metadata for the chat model.
+func NewGoogleToolWithDefaults(h *HTTPHelper, defaults googleParams) *GoogleTool {
+	if h == nil {
+		h = NewHTTPHelper()
+	}
+	return &GoogleTool{helper: h, defaults: defaults}
+}
+
 func (g *GoogleTool) Info(_ context.Context) (*schema.ToolInfo, error) {
 	return &schema.ToolInfo{
 		Name: googleToolName,
 		Desc: googleToolDescription,
 		ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-			"query": {
+			"q": {
 				Type:     schema.String,
-				Desc:     "Search query",
+				Desc:     "The search keywords to execute with Google. The keywords should be the most important words/terms(includes synonyms) from the original request.",
 				Required: true,
 			},
-			"api_key": {
-				Type:     schema.String,
-				Desc:     "Google Programmable Search API key.",
-				Required: true,
-			},
-			"cx": {
-				Type:     schema.String,
-				Desc:     "Google Programmable Search engine ID (cx).",
-				Required: true,
-			},
-			"max_results": {
+			"start": {
 				Type:     schema.Integer,
-				Desc:     "Maximum number of results to return. Defaults to 5 (max 10 per request).",
+				Desc:     "Parameter defines the result offset. It skips the given number of results. It's used for pagination. (e.g., 0 (default) is the first page of results, 10 is the 2nd page of results, 20 is the 3rd page of results, etc.). Google Local Results only accepts multiples of 20(e.g. 20 for the second page results, 40 for the third page results, etc.) as the start value.",
+				Required: false,
+			},
+			"num": {
+				Type:     schema.Integer,
+				Desc:     "Parameter defines the maximum number of results to return. (e.g., 10 (default) returns 10 results, 40 returns 40 results, and 100 returns 100 results). The use of num may introduce latency, and/or prevent the inclusion of specialized result types. It is better to omit this parameter unless it is strictly necessary to increase the number of results per page. Results are not guaranteed to have the number of results specified in num.",
 				Required: false,
 			},
 		}),
 	}, nil
 }
 
-// buildGoogleURL constructs the CSE query URL. The Programmable Search
-// API caps `num` at 10; we clamp to that range to avoid upstream errors.
-func buildGoogleURL(apiKey, cx, query string, maxResults int) string {
-	if maxResults <= 0 {
-		maxResults = 5
+// InputForm returns the Google fields exposed through Agent tool aggregation.
+func (g *GoogleTool) InputForm() map[string]any {
+	return map[string]any{
+		"q": map[string]any{
+			"name": "Query",
+			"type": "line",
+		},
+		"start": map[string]any{
+			"name":  "From",
+			"type":  "integer",
+			"value": 0,
+		},
+		"num": map[string]any{
+			"name":  "Limit",
+			"type":  "integer",
+			"value": 12,
+		},
 	}
-	if maxResults > 10 {
-		maxResults = 10
-	}
-	q := url.Values{}
-	q.Set("key", apiKey)
-	q.Set("cx", cx)
-	q.Set("q", query)
-	q.Set("num", fmt.Sprintf("%d", maxResults))
-	return "https://www.googleapis.com/customsearch/v1?" + q.Encode()
 }
 
-// InvokableRun performs the Google Programmable Search.
+var googleEndpoint = "https://serpapi.com/search.json"
+
+func buildGoogleURL(p googleParams) string {
+	query := strings.TrimSpace(p.Q)
+	num := p.Num
+	if num <= 0 {
+		num = 6
+	}
+	country := strings.TrimSpace(p.Country)
+	if country == "" {
+		country = "us"
+	}
+	language := strings.TrimSpace(p.Language)
+	if language == "" {
+		language = "en"
+	}
+
+	q := url.Values{}
+	q.Set("api_key", p.APIKey)
+	q.Set("engine", "google")
+	q.Set("q", query)
+	q.Set("google_domain", "google.com")
+	q.Set("gl", country)
+	q.Set("hl", language)
+	q.Set("start", strconv.Itoa(p.Start))
+	q.Set("num", strconv.Itoa(num))
+	return googleEndpoint + "?" + q.Encode()
+}
+
 func (g *GoogleTool) InvokableRun(ctx context.Context, argsJSON string, _ ...tool.Option) (string, error) {
 	var p googleParams
 	if err := json.Unmarshal([]byte(argsJSON), &p); err != nil {
 		return googleErrJSON(fmt.Errorf("google: parse arguments: %w", err)),
 			fmt.Errorf("google: parse arguments: %w", err)
 	}
-	if p.Query == "" {
+	p = mergeGoogleDefaults(g.defaults, p)
+	if strings.TrimSpace(p.Q) == "" {
 		return googleErrJSON(fmt.Errorf("query is required")),
 			fmt.Errorf("google: query is required")
 	}
-	if p.APIKey == "" || p.CX == "" {
-		return googleErrJSON(fmt.Errorf("google: api_key and cx are required")),
-			fmt.Errorf("google: api_key and cx are required")
+	if strings.TrimSpace(p.APIKey) == "" {
+		return googleErrJSON(fmt.Errorf("google: api_key is required")),
+			fmt.Errorf("google: api_key is required")
 	}
 
-	endpoint := buildGoogleURL(p.APIKey, p.CX, p.Query, p.MaxResults)
-	resp, err := g.helper.Do(ctx, http.MethodGet, endpoint, "", "", nil)
+	resp, err := g.helper.Do(ctx, http.MethodGet, buildGoogleURL(p), "", "", nil)
 	if err != nil {
 		return googleErrJSON(err), err
 	}
@@ -163,7 +182,29 @@ func (g *GoogleTool) InvokableRun(ctx context.Context, argsJSON string, _ ...too
 		return googleErrJSON(fmt.Errorf("google: decode response: %w", err)),
 			fmt.Errorf("google: decode response: %w", err)
 	}
-	return googleJSON(googleEnvelope{Results: raw.Items}), nil
+	return googleJSON(googleEnvelope{Results: raw.OrganicResults}), nil
+}
+
+func mergeGoogleDefaults(defaults, p googleParams) googleParams {
+	if p.APIKey == "" {
+		p.APIKey = defaults.APIKey
+	}
+	if p.Q == "" {
+		p.Q = defaults.Q
+	}
+	if p.Start == 0 {
+		p.Start = defaults.Start
+	}
+	if p.Num == 0 {
+		p.Num = defaults.Num
+	}
+	if p.Country == "" {
+		p.Country = defaults.Country
+	}
+	if p.Language == "" {
+		p.Language = defaults.Language
+	}
+	return p
 }
 
 func googleJSON(env googleEnvelope) string {

internal/agent/tool/google_test.go

@@ -31,45 +31,33 @@ func TestGoogle_BuildURL(t *testing.T) {
 
 	cases := []struct {
 		name     string
-		apiKey   string
-		cx       string
-		query    string
-		max      int
+		params   googleParams
 		wantNum  string
 		wantHost string
 	}{
 		{
-			name:     "default",
-			apiKey:   "KEY",
-			cx:       "CXID",
-			query:    "ragflow",
-			max:      0,
-			wantNum:  "5",
-			wantHost: "www.googleapis.com",
+			name:     "python defaults",
+			params:   googleParams{APIKey: "KEY", Q: "ragflow"},
+			wantNum:  "6",
+			wantHost: "serpapi.com",
 		},
 		{
-			name:     "clamped high",
-			apiKey:   "K",
-			cx:       "C",
-			query:    "x",
-			max:      50,
-			wantNum:  "10",
-			wantHost: "www.googleapis.com",
+			name:     "canvas num country language",
+			params:   googleParams{APIKey: "K", Q: "x y", Num: 12, Start: 10, Country: "cn", Language: "zh-cn"},
+			wantNum:  "12",
+			wantHost: "serpapi.com",
 		},
 		{
-			name:     "explicit low",
-			apiKey:   "K",
-			cx:       "C",
-			query:    "x y",
-			max:      3,
+			name:     "agent aliases",
+			params:   googleParams{APIKey: "K", Q: "x", Num: 3},
 			wantNum:  "3",
-			wantHost: "www.googleapis.com",
+			wantHost: "serpapi.com",
 		},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
-			got := buildGoogleURL(tc.apiKey, tc.cx, tc.query, tc.max)
+			got := buildGoogleURL(tc.params)
 			u, err := url.Parse(got)
 			if err != nil {
 				t.Fatalf("url.Parse(%q): %v", got, err)
@@ -77,18 +65,15 @@ func TestGoogle_BuildURL(t *testing.T) {
 			if u.Host != tc.wantHost {
 				t.Errorf("host = %q, want %q", u.Host, tc.wantHost)
 			}
-			if u.Path != "/customsearch/v1" {
-				t.Errorf("path = %q, want /customsearch/v1", u.Path)
+			if u.Path != "/search.json" {
+				t.Errorf("path = %q, want /search.json", u.Path)
 			}
 			q := u.Query()
-			if q.Get("key") != tc.apiKey {
-				t.Errorf("key = %q, want %q", q.Get("key"), tc.apiKey)
+			if q.Get("api_key") != tc.params.APIKey {
+				t.Errorf("api_key = %q, want %q", q.Get("api_key"), tc.params.APIKey)
 			}
-			if q.Get("cx") != tc.cx {
-				t.Errorf("cx = %q, want %q", q.Get("cx"), tc.cx)
-			}
-			if q.Get("q") != tc.query {
-				t.Errorf("q = %q, want %q", q.Get("q"), tc.query)
+			if q.Get("engine") != "google" {
+				t.Errorf("engine = %q, want google", q.Get("engine"))
 			}
 			if q.Get("num") != tc.wantNum {
 				t.Errorf("num = %q, want %q", q.Get("num"), tc.wantNum)
@@ -103,7 +88,7 @@ func TestGoogle_ParseResults(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{
-			"items": [
+			"organic_results": [
 				{"title":"RAGFlow","link":"https://ragflow.io","snippet":"Open source RAG engine"},
 				{"title":"GitHub","link":"https://github.com/infiniflow/ragflow","snippet":"Source code"}
 			]
@@ -116,7 +101,7 @@ func TestGoogle_ParseResults(t *testing.T) {
 	})
 	tool := NewGoogleToolWith(helper)
 	out, err := tool.InvokableRun(context.Background(),
-		`{"query":"ragflow","api_key":"K","cx":"C","max_results":5}`)
+		`{"q":"ragflow","api_key":"K","num":5,"country":"us","language":"en"}`)
 	if err != nil {
 		t.Fatalf("InvokableRun: %v", err)
 	}
@@ -131,29 +116,28 @@ func TestGoogle_ParseResults(t *testing.T) {
 	if len(env.Results) != 2 {
 		t.Fatalf("Results len = %d, want 2", len(env.Results))
 	}
-	if env.Results[0].Title != "RAGFlow" {
-		t.Errorf("Results[0].Title = %q, want RAGFlow", env.Results[0].Title)
+	if env.Results[0]["title"] != "RAGFlow" {
+		t.Errorf("Results[0].title = %q, want RAGFlow", env.Results[0]["title"])
 	}
-	if env.Results[1].Link != "https://github.com/infiniflow/ragflow" {
-		t.Errorf("Results[1].Link = %q, want https://github.com/infiniflow/ragflow", env.Results[1].Link)
+	if env.Results[1]["link"] != "https://github.com/infiniflow/ragflow" {
+		t.Errorf("Results[1].link = %q, want https://github.com/infiniflow/ragflow", env.Results[1]["link"])
 	}
 }
 
-func TestGoogle_RequiresAPIKeyAndCX(t *testing.T) {
+func TestGoogle_RequiresAPIKey(t *testing.T) {
 	t.Parallel()
 
 	tool := NewGoogleTool()
-	_, err := tool.InvokableRun(context.Background(),
-		`{"query":"x","api_key":"","cx":""}`)
+	_, err := tool.InvokableRun(context.Background(), `{"q":"x","api_key":""}`)
 	if err == nil {
-		t.Fatal("expected error for missing api_key and cx")
+		t.Fatal("expected error for missing api_key")
 	}
-	if !strings.Contains(err.Error(), "api_key") || !strings.Contains(err.Error(), "cx") {
-		t.Errorf("err = %v, want to mention api_key and cx", err)
+	if !strings.Contains(err.Error(), "api_key") {
+		t.Errorf("err = %v, want to mention api_key", err)
 	}
 }
 
-func TestGoogle_Info(t *testing.T) {
+func TestGoogle_InfoAndInputForm(t *testing.T) {
 	t.Parallel()
 
 	tool := NewGoogleTool()
@@ -167,4 +151,86 @@ func TestGoogle_Info(t *testing.T) {
 	if !strings.Contains(info.Desc, "Google") {
 		t.Errorf("Desc = %q, want to mention Google", info.Desc)
 	}
+	form := tool.InputForm()
+	if _, ok := form["q"]; !ok {
+		t.Fatalf("InputForm missing q: %+v", form)
+	}
+	if _, ok := form["start"]; !ok {
+		t.Fatalf("InputForm missing start: %+v", form)
+	}
+	if _, ok := form["num"]; !ok {
+		t.Fatalf("InputForm missing num: %+v", form)
+	}
+}
+
+func TestGoogle_MergeDefaultsPrefersExplicitInputs(t *testing.T) {
+	t.Parallel()
+
+	got := mergeGoogleDefaults(
+		googleParams{
+			APIKey:  "DEFAULT_KEY",
+			Q:       "default query",
+			Num:     6,
+			Country: "us",
+		},
+		googleParams{
+			Q:   "agent query",
+			Num: 10,
+		},
+	)
+
+	if got.APIKey != "DEFAULT_KEY" {
+		t.Fatalf("APIKey = %q, want DEFAULT_KEY", got.APIKey)
+	}
+	if got.Q != "agent query" {
+		t.Fatalf("Q = %q, want agent query", got.Q)
+	}
+	if got.Num != 10 {
+		t.Fatalf("Num = %d, want 10", got.Num)
+	}
+	if got.Country != "us" {
+		t.Fatalf("Country = %q, want us", got.Country)
+	}
+}
+
+func TestGoogle_BuildByNameAcceptsNodeParams(t *testing.T) {
+	t.Parallel()
+
+	built, err := BuildByName("google", map[string]any{
+		"api_key":  "KEY",
+		"country":  "cn",
+		"language": "zh-cn",
+		"num":      12,
+	})
+	if err != nil {
+		t.Fatalf("BuildByName: %v", err)
+	}
+	tool, ok := built.(*GoogleTool)
+	if !ok {
+		t.Fatalf("built type = %T, want *GoogleTool", built)
+	}
+	if tool.defaults.APIKey != "KEY" {
+		t.Fatalf("defaults.APIKey = %q, want KEY", tool.defaults.APIKey)
+	}
+	if tool.defaults.Country != "cn" || tool.defaults.Language != "zh-cn" {
+		t.Fatalf("defaults locale = %q/%q, want cn/zh-cn", tool.defaults.Country, tool.defaults.Language)
+	}
+	if tool.defaults.Num != 12 {
+		t.Fatalf("defaults.Num = %d, want 12", tool.defaults.Num)
+	}
+}
+
+func TestGoogle_BuildByNameRejectsRemovedAliasNodeParams(t *testing.T) {
+	t.Parallel()
+
+	_, err := BuildByName("google", map[string]any{
+		"query":       "ragflow",
+		"max_results": 5,
+	})
+	if err == nil {
+		t.Fatal("expected error for removed google alias node params")
+	}
+	if !strings.Contains(err.Error(), "does not accept node-level param") {
+		t.Fatalf("err = %q, want unsupported node-level param error", err.Error())
+	}
 }

internal/agent/tool/registry.go

@@ -40,7 +40,7 @@ var registry = map[string]Factory{
 	"execute_sql":       buildExeSQLTool,
 	"exesql":            buildExeSQLTool,
 	"github":            noConfig("github", func() einotool.BaseTool { return NewGitHubTool() }),
-	"google":            noConfig("google", func() einotool.BaseTool { return NewGoogleTool() }),
+	"google":            buildGoogleTool,
 	"google_scholar":    noConfig("google_scholar", func() einotool.BaseTool { return NewGoogleScholarTool() }),
 	"jin10":             noConfig("jin10", func() einotool.BaseTool { return NewJin10Tool() }),
 	"keenable":          buildKeenableTool,
@@ -134,6 +134,39 @@ func buildExeSQLTool(params map[string]any) (einotool.BaseTool, error) {
 	return NewExeSQLTool(conn), nil
 }
 
+func buildGoogleTool(params map[string]any) (einotool.BaseTool, error) {
+	if len(params) == 0 {
+		return NewGoogleTool(), nil
+	}
+	for key := range params {
+		switch key {
+		case "api_key", "country", "language", "q", "start", "num":
+		default:
+			return nil, fmt.Errorf("agent tool: tool %q does not accept node-level param %s", "google", key)
+		}
+	}
+	defaults := googleParams{}
+	if v, ok := stringParam(params, "api_key"); ok {
+		defaults.APIKey = v
+	}
+	if v, ok := stringParam(params, "country"); ok {
+		defaults.Country = v
+	}
+	if v, ok := stringParam(params, "language"); ok {
+		defaults.Language = v
+	}
+	if v, ok := stringParam(params, "q"); ok {
+		defaults.Q = v
+	}
+	if v, ok := intParam(params, "start"); ok {
+		defaults.Start = v
+	}
+	if v, ok := intParam(params, "num"); ok {
+		defaults.Num = v
+	}
+	return NewGoogleToolWithDefaults(nil, defaults), nil
+}
+
 func buildKeenableTool(params map[string]any) (einotool.BaseTool, error) {
 	if len(params) == 0 {
 		return NewKeenableTool(), nil