feat(go-agent): Ported retrieval node, added Keenable web search tool (#16396)

Ported retrieval node, added Keenable web search tool
- [x] New Feature (non-breaking change which adds functionality)

internal/agent/tool/keenable.go

@@ -0,0 +1,312 @@
+//
+//  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 tool
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	neturl "net/url"
+	"os"
+	"strings"
+
+	"github.com/cloudwego/eino/components/tool"
+	"github.com/cloudwego/eino/schema"
+)
+
+const keenableToolName = "keenable"
+
+// keenableToolDescription follows the upstream Python tool's description,
+// trimmed for the chat model. The "no API key required" line is the
+// differentiator from Tavily/DuckDuckGo/SearXNG.
+const keenableToolDescription = `Keenable is a web search API built for AI agents. It returns fresh, relevant web results for a query and works without an API key by default (keyless free tier). When searching:
+   - Use a focused query of the most important terms (and synonyms).
+   - Optionally restrict to a single site/domain.`
+
+// keenableParams is the JSON shape the model sends into InvokableRun.
+// site is an optional single-domain filter. mode is "pro" (default,
+// deeper) or "realtime" (requires a server-configured key). top_n caps
+// how many results we keep from the upstream `results` array.
+type keenableParams struct {
+	Query string `json:"query"`
+	Site  string `json:"site"`
+	Mode  string `json:"mode"`
+	TopN  int    `json:"top_n"`
+}
+
+// keenableRequestBody is the JSON body POSTed to the Keenable search
+// endpoint. Mirrors the upstream Python tool — query, mode, and an
+// optional site filter.
+type keenableRequestBody struct {
+	Query string `json:"query"`
+	Mode  string `json:"mode"`
+	Site  string `json:"site,omitempty"`
+}
+
+// keenableResult mirrors one element of the upstream `results` array.
+// The Python tool's _retrieve_chunks reads `title`, `url`, `description`,
+// so we model those fields and pass everything else through verbatim
+// when serializing to the model.
+type keenableResult struct {
+	Title       string `json:"title"`
+	URL         string `json:"url"`
+	Description string `json:"description"`
+}
+
+// keenableResponse is the envelope returned by Keenable. We only model
+// the fields we care about; the upstream API has more, but they are
+// ignored.
+type keenableResponse struct {
+	Results []keenableResult `json:"results"`
+}
+
+// keenableEnvelope is the shape the model actually sees, identical to
+// the Python tool's output convention.
+type keenableEnvelope struct {
+	Results []keenableResult `json:"results"`
+	Error   string           `json:"_ERROR,omitempty"`
+}
+
+// KeenableTool is the Keenable web search tool. It POSTs a search
+// request to the public keyless endpoint by default and to the keyed
+// endpoint (with X-API-Key) when an API key is provided. The upstream
+// `results` array is returned as JSON.
+type KeenableTool struct {
+	helper *HTTPHelper
+	apiKey string
+
+	// envBaseURL resolves the Keenable API base URL from the
+	// KEENABLE_API_URL env var (HTTPS enforced). Exposed as a
+	// function so tests can inject a fake without mutating process
+	// state — matches the envKey pattern used by TavilyTool.
+	envBaseURL func() string
+}
+
+// NewKeenableTool returns a KeenableTool using the default HTTPHelper
+// and the KEENABLE_API_URL env var for base-URL resolution.
+func NewKeenableTool() *KeenableTool {
+	return NewKeenableToolWith(NewHTTPHelper())
+}
+
+// NewKeenableToolWithAPIKey returns a KeenableTool that uses a
+// server-provided API key instead of model-visible runtime args.
+func NewKeenableToolWithAPIKey(h *HTTPHelper, apiKey string) *KeenableTool {
+	t := NewKeenableToolWith(h)
+	t.apiKey = strings.TrimSpace(apiKey)
+	return t
+}
+
+// NewKeenableToolWith returns a KeenableTool that uses the provided
+// HTTPHelper. Useful for tests that want to inject a custom transport.
+func NewKeenableToolWith(h *HTTPHelper) *KeenableTool {
+	if h == nil {
+		h = NewHTTPHelper()
+	}
+	return &KeenableTool{helper: h, envBaseURL: defaultKeenableEnvBaseURL}
+}
+
+// NewKeenableToolWithEnvBaseURL returns a KeenableTool with a custom
+// base-URL resolver. Useful for tests that want to inject a fake env
+// without mutating process state.
+func NewKeenableToolWithEnvBaseURL(h *HTTPHelper, envBaseURL func() string) *KeenableTool {
+	if h == nil {
+		h = NewHTTPHelper()
+	}
+	if envBaseURL == nil {
+		envBaseURL = defaultKeenableEnvBaseURL
+	}
+	return &KeenableTool{helper: h, envBaseURL: envBaseURL}
+}
+
+// defaultKeenableEnvBaseURL is the production base-URL resolver.
+// Pulled out as a named function (not a var) so tests cannot
+// accidentally mutate it via package-var assignment.
+func defaultKeenableEnvBaseURL() string {
+	if v := strings.TrimSpace(os.Getenv("KEENABLE_API_URL")); v != "" {
+		return v
+	}
+	return "https://api.keenable.ai"
+}
+
+// resolveKeenableBaseURL returns the validated Keenable base URL.
+// HTTPS is required for any non-loopback host; loopback hosts may
+// use plain http for local development. Mirrors the Python tool's
+// _base_url() guard — a misconfigured URL fails fast at request time
+// rather than silently making a request to the wrong host.
+func resolveKeenableBaseURL(raw string) (string, error) {
+	raw = strings.TrimRight(strings.TrimSpace(raw), "/")
+	if raw == "" {
+		return "", fmt.Errorf("keenable: empty base URL")
+	}
+	u, err := neturl.Parse(raw)
+	if err != nil {
+		return "", fmt.Errorf("keenable: parse KEENABLE_API_URL %q: %w", raw, err)
+	}
+	host := u.Hostname()
+	if host == "" {
+		return "", fmt.Errorf("keenable: KEENABLE_API_URL must have a host, got %q", raw)
+	}
+	if u.RawQuery != "" || u.Fragment != "" {
+		return "", fmt.Errorf("keenable: KEENABLE_API_URL must not include query or fragment, got %q", raw)
+	}
+	switch u.Scheme {
+	case "https":
+		return raw, nil
+	case "http":
+		if host == "localhost" || host == "127.0.0.1" || host == "::1" {
+			return raw, nil
+		}
+		return "", fmt.Errorf("keenable: KEENABLE_API_URL must be https://, got %q", raw)
+	default:
+		return "", fmt.Errorf("keenable: KEENABLE_API_URL scheme %q not allowed (https required)", u.Scheme)
+	}
+}
+
+// Info returns the tool's metadata for the chat model. The description
+// is the short prose above; the parameter schema lists the model-emitted
+// fields with sane defaults documented inline.
+func (k *KeenableTool) Info(_ context.Context) (*schema.ToolInfo, error) {
+	return &schema.ToolInfo{
+		Name: keenableToolName,
+		Desc: keenableToolDescription,
+		ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
+			"query": {
+				Type:     schema.String,
+				Desc:     "Search keywords to execute with Keenable. The most important words/terms (and synonyms) from the original request.",
+				Required: true,
+			},
+			"site": {
+				Type:     schema.String,
+				Desc:     "Optional. Restrict results to a single domain, e.g. 'techcrunch.com'. Defaults to '' (no filter).",
+				Required: false,
+			},
+			"mode": {
+				Type:     schema.String,
+				Desc:     `Search mode: "pro" (default, deeper) or "realtime" (low latency; requires a server-configured API key).`,
+				Required: false,
+			},
+			"top_n": {
+				Type:     schema.Integer,
+				Desc:     "Maximum number of results to return. Defaults to 10.",
+				Required: false,
+			},
+		}),
+	}, nil
+}
+
+// InvokableRun performs the Keenable search.
+func (k *KeenableTool) InvokableRun(ctx context.Context, argsJSON string, _ ...tool.Option) (string, error) {
+	var p keenableParams
+	if err := json.Unmarshal([]byte(argsJSON), &p); err != nil {
+		return keenableErrJSON(fmt.Errorf("keenable: parse arguments: %w", err)),
+			fmt.Errorf("keenable: parse arguments: %w", err)
+	}
+	if strings.TrimSpace(p.Query) == "" {
+		return keenableErrJSON(fmt.Errorf("query is required")),
+			fmt.Errorf("keenable: query is required")
+	}
+
+	mode := strings.TrimSpace(p.Mode)
+	if mode == "" {
+		mode = "pro"
+	}
+	if mode != "pro" && mode != "realtime" {
+		return keenableErrJSON(fmt.Errorf("keenable: mode %q must be one of [pro realtime]", p.Mode)),
+			fmt.Errorf("keenable: mode %q must be one of [pro realtime]", p.Mode)
+	}
+	// 'realtime' is only available on the keyed endpoint. Reject the
+	// invalid combination up front instead of letting the upstream
+	// return a confusing error — matches the Python tool's check().
+	if mode == "realtime" && strings.TrimSpace(k.apiKey) == "" {
+		return keenableErrJSON(fmt.Errorf("keenable: 'realtime' mode requires a configured api_key")),
+			fmt.Errorf("keenable: 'realtime' mode requires a configured api_key")
+	}
+
+	topN := p.TopN
+	if topN <= 0 {
+		topN = 10
+	}
+
+	baseURL, err := resolveKeenableBaseURL(k.envBaseURL())
+	if err != nil {
+		// Config/local error — won't be fixed by retrying, so fail fast
+		// (matches the Python tool's behavior for ValueError).
+		return keenableErrJSON(err), err
+	}
+
+	apiKey := strings.TrimSpace(k.apiKey)
+	path := "/v1/search/public"
+	headers := map[string]string{
+		"User-Agent":       "keenable-ragflow",
+		"X-Keenable-Title": "RAGFlow",
+	}
+	if apiKey != "" {
+		path = "/v1/search"
+		headers["X-API-Key"] = apiKey
+	}
+
+	body := keenableRequestBody{
+		Query: p.Query,
+		Mode:  mode,
+	}
+	if site := strings.TrimSpace(p.Site); site != "" {
+		body.Site = site
+	}
+
+	bodyJSON, _ := json.Marshal(body)
+
+	resp, err := k.helper.Do(ctx,
+		http.MethodPost, baseURL+path, string(bodyJSON), "application/json", headers,
+	)
+	if err != nil {
+		return keenableErrJSON(err), err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return keenableErrJSON(fmt.Errorf("keenable: upstream returned %d", resp.StatusCode)),
+			fmt.Errorf("keenable: upstream returned %d", resp.StatusCode)
+	}
+
+	var raw keenableResponse
+	if err := json.NewDecoder(resp.Body).Decode(&raw); err != nil {
+		return keenableErrJSON(fmt.Errorf("keenable: decode response: %w", err)),
+			fmt.Errorf("keenable: decode response: %w", err)
+	}
+
+	results := raw.Results
+	if len(results) > topN {
+		results = results[:topN]
+	}
+
+	return keenableJSON(keenableEnvelope{Results: results}), nil
+}
+
+// keenableJSON marshals the envelope to a JSON string for the model.
+func keenableJSON(env keenableEnvelope) string {
+	b, err := json.Marshal(env)
+	if err != nil {
+		return fmt.Sprintf(`{"_ERROR":"keenable: marshal result: %s"}`, err)
+	}
+	return string(b)
+}
+
+// keenableErrJSON wraps an error in the standard envelope.
+func keenableErrJSON(err error) string {
+	return keenableJSON(keenableEnvelope{Error: err.Error()})
+}

internal/agent/tool/keenable_test.go

@@ -0,0 +1,392 @@
+//
+//  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 tool
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// TestKeenable_KeylessPath verifies that when no api_key is supplied the
+// tool POSTs to /v1/search/public with the attribution headers but
+// without an X-API-Key header.
+func TestKeenable_KeylessPath(t *testing.T) {
+	t.Parallel()
+
+	var gotMethod, gotPath, gotUA, gotTitle, gotAPIKey, gotCT string
+	var gotBody map[string]any
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotMethod = r.Method
+		gotPath = r.URL.Path
+		gotUA = r.Header.Get("User-Agent")
+		gotTitle = r.Header.Get("X-Keenable-Title")
+		gotAPIKey = r.Header.Get("X-API-Key")
+		gotCT = r.Header.Get("Content-Type")
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"results":[]}`))
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithEnvBaseURL(helper, func() string { return "https://" + srv.URL[len("http://"):] })
+
+	if _, err := tool.InvokableRun(context.Background(), `{"query":"ragflow"}`); err != nil {
+		t.Fatalf("InvokableRun: %v", err)
+	}
+
+	if gotMethod != http.MethodPost {
+		t.Errorf("method = %q, want POST", gotMethod)
+	}
+	if gotPath != "/v1/search/public" {
+		t.Errorf("path = %q, want /v1/search/public (keyless endpoint)", gotPath)
+	}
+	if gotUA != "keenable-ragflow" {
+		t.Errorf("User-Agent = %q, want keenable-ragflow", gotUA)
+	}
+	if gotTitle != "RAGFlow" {
+		t.Errorf("X-Keenable-Title = %q, want RAGFlow", gotTitle)
+	}
+	if gotAPIKey != "" {
+		t.Errorf("X-API-Key = %q, want empty on keyless path", gotAPIKey)
+	}
+	if !strings.HasPrefix(gotCT, "application/json") {
+		t.Errorf("Content-Type = %q, want application/json", gotCT)
+	}
+	if gotBody["query"] != "ragflow" {
+		t.Errorf("body.query = %v, want ragflow", gotBody["query"])
+	}
+	if gotBody["mode"] != "pro" {
+		t.Errorf("body.mode = %v, want pro (default)", gotBody["mode"])
+	}
+}
+
+// TestKeenable_KeyedPath verifies that a server-configured api_key
+// switches the tool to the /v1/search endpoint and sets X-API-Key on
+// the request.
+func TestKeenable_KeyedPath(t *testing.T) {
+	t.Parallel()
+
+	var gotPath, gotAPIKey string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		gotAPIKey = r.Header.Get("X-API-Key")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"results":[]}`))
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithAPIKey(helper, "key-xyz")
+	tool.envBaseURL = func() string { return "https://" + srv.URL[len("http://"):] }
+
+	if _, err := tool.InvokableRun(context.Background(),
+		`{"query":"ragflow","mode":"realtime"}`); err != nil {
+		t.Fatalf("InvokableRun: %v", err)
+	}
+
+	if gotPath != "/v1/search" {
+		t.Errorf("path = %q, want /v1/search (keyed endpoint)", gotPath)
+	}
+	if gotAPIKey != "key-xyz" {
+		t.Errorf("X-API-Key = %q, want key-xyz", gotAPIKey)
+	}
+}
+
+// TestKeenable_SiteAndTopN verifies the site filter is forwarded and
+// that the result list is truncated to top_n.
+func TestKeenable_SiteAndTopN(t *testing.T) {
+	t.Parallel()
+
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"results":[
+			{"title":"A","url":"https://a","description":"alpha"},
+			{"title":"B","url":"https://b","description":"beta"},
+			{"title":"C","url":"https://c","description":"gamma"},
+			{"title":"D","url":"https://d","description":"delta"}
+		]}`))
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithEnvBaseURL(helper, func() string { return "https://" + srv.URL[len("http://"):] })
+
+	out, err := tool.InvokableRun(context.Background(),
+		`{"query":"x","site":"example.com","top_n":2}`)
+	if err != nil {
+		t.Fatalf("InvokableRun: %v", err)
+	}
+
+	if gotBody["site"] != "example.com" {
+		t.Errorf("body.site = %v, want example.com", gotBody["site"])
+	}
+
+	var env keenableEnvelope
+	if jerr := json.Unmarshal([]byte(out), &env); jerr != nil {
+		t.Fatalf("output not valid JSON: %v (raw=%s)", jerr, out)
+	}
+	if env.Error != "" {
+		t.Errorf("Error = %q, want empty", env.Error)
+	}
+	if len(env.Results) != 2 {
+		t.Fatalf("Results len = %d, want 2 (capped by top_n)", len(env.Results))
+	}
+	if env.Results[0].Title != "A" || env.Results[1].Title != "B" {
+		t.Errorf("Results = %+v, want first 2 upstream items", env.Results)
+	}
+}
+
+// TestKeenable_DefaultTopN verifies that omitting top_n keeps up to 10
+// results from the upstream response (the default in the Python tool).
+func TestKeenable_DefaultTopN(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 12 results; default top_n is 10, so we expect 10 in the envelope.
+		var results []map[string]string
+		for range 12 {
+			results = append(results, map[string]string{
+				"title":       "T",
+				"url":         "https://u",
+				"description": "d",
+			})
+		}
+		b, _ := json.Marshal(map[string]any{"results": results})
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write(b)
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithEnvBaseURL(helper, func() string { return "https://" + srv.URL[len("http://"):] })
+
+	out, err := tool.InvokableRun(context.Background(), `{"query":"x"}`)
+	if err != nil {
+		t.Fatalf("InvokableRun: %v", err)
+	}
+
+	var env keenableEnvelope
+	if jerr := json.Unmarshal([]byte(out), &env); jerr != nil {
+		t.Fatalf("output not valid JSON: %v", jerr)
+	}
+	if len(env.Results) != 10 {
+		t.Errorf("Results len = %d, want 10 (default top_n)", len(env.Results))
+	}
+}
+
+// TestKeenable_MissingQuery verifies that an empty query is rejected
+// before any HTTP request is made.
+func TestKeenable_MissingQuery(t *testing.T) {
+	t.Parallel()
+
+	tool := NewKeenableTool()
+	_, err := tool.InvokableRun(context.Background(), `{}`)
+	if err == nil {
+		t.Fatal("expected error for missing query")
+	}
+	if !strings.Contains(err.Error(), "query") {
+		t.Errorf("err = %v, want to mention query", err)
+	}
+}
+
+// TestKeenable_RealtimeRequiresAPIKey verifies the config-time rejection
+// of realtime mode without a configured api_key.
+func TestKeenable_RealtimeRequiresAPIKey(t *testing.T) {
+	t.Parallel()
+
+	tool := NewKeenableTool()
+	_, err := tool.InvokableRun(context.Background(), `{"query":"x","mode":"realtime"}`)
+	if err == nil {
+		t.Fatal("expected error for realtime mode without api_key")
+	}
+	if !strings.Contains(err.Error(), "configured api_key") {
+		t.Errorf("err = %v, want to mention configured api_key", err)
+	}
+}
+
+// TestKeenable_InvalidMode verifies that an unknown mode is rejected
+// up front instead of being forwarded to the upstream.
+func TestKeenable_InvalidMode(t *testing.T) {
+	t.Parallel()
+
+	tool := NewKeenableTool()
+	_, err := tool.InvokableRun(context.Background(), `{"query":"x","mode":"bogus"}`)
+	if err == nil {
+		t.Fatal("expected error for invalid mode")
+	}
+	if !strings.Contains(err.Error(), "mode") {
+		t.Errorf("err = %v, want to mention mode", err)
+	}
+}
+
+// TestKeenable_ResolveBaseURL exercises the HTTPS-only / loopback-http
+// guard around KEENABLE_API_URL.
+func TestKeenable_ResolveBaseURL(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name      string
+		raw       string
+		wantOK    bool
+		wantValue string
+	}{
+		{"https default", "https://api.keenable.ai", true, "https://api.keenable.ai"},
+		{"https trailing slash", "https://api.keenable.ai/", true, "https://api.keenable.ai"},
+		{"http loopback ok", "http://localhost:8080", true, "http://localhost:8080"},
+		{"http 127 ok", "http://127.0.0.1:8080", true, "http://127.0.0.1:8080"},
+		{"http ::1 ok", "http://[::1]:8080", true, "http://[::1]:8080"},
+		{"http non-loopback rejected", "http://example.com", false, ""},
+		{"ftp rejected", "ftp://api.keenable.ai", false, ""},
+		{"query rejected", "https://api.keenable.ai?x=1", false, ""},
+		{"fragment rejected", "https://api.keenable.ai#frag", false, ""},
+		{"no host rejected", "https:///path", false, ""},
+		{"empty rejected", "", false, ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := resolveKeenableBaseURL(tc.raw)
+			if tc.wantOK {
+				if err != nil {
+					t.Fatalf("err = %v, want nil", err)
+				}
+				if got != tc.wantValue {
+					t.Errorf("got = %q, want %q", got, tc.wantValue)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("got = %q, want error", got)
+			}
+		})
+	}
+}
+
+// TestKeenable_BaseURLFromEnv verifies that the KEENABLE_API_URL env var
+// is honored. We use a fake resolver that does NOT touch os.Getenv so
+// the test does not depend on the host environment.
+func TestKeenable_BaseURLFromEnv(t *testing.T) {
+	t.Parallel()
+
+	var gotPath string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"results":[]}`))
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithEnvBaseURL(helper, func() string {
+		return "https://" + srv.URL[len("http://"):]
+	})
+
+	if _, err := tool.InvokableRun(context.Background(), `{"query":"x"}`); err != nil {
+		t.Fatalf("InvokableRun: %v", err)
+	}
+	if gotPath != "/v1/search/public" {
+		t.Errorf("path = %q, want /v1/search/public", gotPath)
+	}
+}
+
+// TestKeenable_BadBaseURL verifies that an invalid KEENABLE_API_URL is
+// reported back to the caller instead of being silently sent.
+func TestKeenable_BadBaseURL(t *testing.T) {
+	t.Parallel()
+
+	tool := NewKeenableToolWithEnvBaseURL(NewHTTPHelper(), func() string { return "http://example.com" })
+	_, err := tool.InvokableRun(context.Background(), `{"query":"x"}`)
+	if err == nil {
+		t.Fatal("expected error for non-https non-loopback base URL")
+	}
+	if !strings.Contains(err.Error(), "https") {
+		t.Errorf("err = %v, want to mention https requirement", err)
+	}
+}
+
+// TestKeenable_UpstreamError verifies that a non-2xx upstream response
+// is surfaced as an error and an _ERROR envelope.
+func TestKeenable_UpstreamError(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "boom", http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	helper := NewHTTPHelper().WithClient(&http.Client{
+		Transport: rewriteHostTransport(srv.URL),
+	})
+	tool := NewKeenableToolWithEnvBaseURL(helper, func() string { return "https://" + srv.URL[len("http://"):] })
+
+	out, err := tool.InvokableRun(context.Background(), `{"query":"x"}`)
+	if err == nil {
+		t.Fatal("expected error for 5xx response")
+	}
+	var env keenableEnvelope
+	if jerr := json.Unmarshal([]byte(out), &env); jerr != nil {
+		t.Fatalf("output not valid JSON: %v (raw=%s)", jerr, out)
+	}
+	if env.Error == "" {
+		t.Errorf("envelope Error = %q, want non-empty", env.Error)
+	}
+}
+
+// TestKeenable_Info verifies the model-facing metadata.
+func TestKeenable_Info(t *testing.T) {
+	t.Parallel()
+
+	tool := NewKeenableTool()
+	info, err := tool.Info(context.Background())
+	if err != nil {
+		t.Fatalf("Info: %v", err)
+	}
+	if info.Name != "keenable" {
+		t.Errorf("Name = %q, want keenable", info.Name)
+	}
+	if !strings.Contains(info.Desc, "Keenable") {
+		t.Errorf("Desc = %q, want to mention Keenable", info.Desc)
+	}
+	if info.ParamsOneOf == nil {
+		t.Fatal("ParamsOneOf = nil, want schema definition")
+	}
+	paramsJSON, err := json.Marshal(info.ParamsOneOf)
+	if err != nil {
+		t.Fatalf("marshal ParamsOneOf: %v", err)
+	}
+	if strings.Contains(string(paramsJSON), "api_key") {
+		t.Fatalf("Info ParamsOneOf unexpectedly exposes api_key: %s", string(paramsJSON))
+	}
+}

internal/agent/tool/qweather_test.go

@@ -31,7 +31,6 @@ func TestQWeather_BuildURL(t *testing.T) {
 	// `qweatherEndpoint` var, which other tests (running in parallel)
 	// temporarily replace with a httptest.Server URL.
 
-
 	cases := []struct {
 		name     string
 		params   qweatherParams

internal/agent/tool/registry.go

@@ -42,6 +42,7 @@ var registry = map[string]Factory{
 	"google":            noConfig("google", func() einotool.BaseTool { return NewGoogleTool() }),
 	"google_scholar":    noConfig("google_scholar", func() einotool.BaseTool { return NewGoogleScholarTool() }),
 	"jin10":             noConfig("jin10", func() einotool.BaseTool { return NewJin10Tool() }),
+	"keenable":          buildKeenableTool,
 	"pubmed":            noConfig("pubmed", func() einotool.BaseTool { return NewPubMedTool() }),
 	"qweather":          noConfig("qweather", func() einotool.BaseTool { return NewQWeatherTool() }),
 	"retrieval":         noConfig("retrieval", func() einotool.BaseTool { return NewRetrievalTool() }),
@@ -112,6 +113,22 @@ func buildExeSQLTool(params map[string]any) (einotool.BaseTool, error) {
 	return NewExeSQLTool(conn), nil
 }
 
+func buildKeenableTool(params map[string]any) (einotool.BaseTool, error) {
+	if len(params) == 0 {
+		return NewKeenableTool(), nil
+	}
+	for key := range params {
+		if key != "api_key" {
+			return nil, fmt.Errorf("agent tool: tool %q only accepts node-level param api_key", "keenable")
+		}
+	}
+	apiKey, ok := params["api_key"].(string)
+	if !ok || strings.TrimSpace(apiKey) == "" {
+		return nil, fmt.Errorf("agent tool: tool %q requires non-empty string node-level param api_key", "keenable")
+	}
+	return NewKeenableToolWithAPIKey(nil, apiKey), nil
+}
+
 func decodeExeSQLConnParams(params map[string]any) (exesqlConnParams, error) {
 	if len(params) == 0 {
 		return exesqlConnParams{}, fmt.Errorf(

internal/agent/tool/registry_test.go

@@ -49,12 +49,12 @@ func TestBuildAll_AllRegisteredTools(t *testing.T) {
 	}
 	params := map[string]map[string]any{
 		"execute_sql": {
-			"db_type":   "mysql",
-			"host":      "127.0.0.1",
-			"port":      3306,
-			"database":  "demo",
-			"username":  "u",
-			"password":  "p",
+			"db_type":     "mysql",
+			"host":        "127.0.0.1",
+			"port":        3306,
+			"database":    "demo",
+			"username":    "u",
+			"password":    "p",
 			"max_records": 10,
 		},
 	}
@@ -77,6 +77,18 @@ func TestBuildAll_ExeSQLRequiresNodeParams(t *testing.T) {
 	}
 }
 
+func TestBuildAll_KeenableRejectsEmptyNodeAPIKey(t *testing.T) {
+	_, err := BuildAll([]string{"keenable"}, map[string]map[string]any{
+		"keenable": {"api_key": ""},
+	})
+	if err == nil {
+		t.Fatal("expected keenable config error")
+	}
+	if !strings.Contains(err.Error(), "requires non-empty string node-level param api_key") {
+		t.Fatalf("err = %q, want keenable api_key validation error", err.Error())
+	}
+}
+
 // TestToolRegistry_SchemasAreComplete sweeps every name the public
 // registry advertises (including the execute_sql/exesql and
 // retrieval/search_my_dateset alias pairs), builds the tool, and
@@ -95,7 +107,7 @@ func TestToolRegistry_SchemasAreComplete(t *testing.T) {
 	names := []string{
 		"akshare", "arxiv", "code_exec", "crawler", "deepl", "duckduckgo",
 		"email", "execute_sql", "exesql", "github", "google",
-		"google_scholar", "jin10", "pubmed", "qweather", "retrieval",
+		"google_scholar", "jin10", "keenable", "pubmed", "qweather", "retrieval",
 		"search_my_dateset", "searxng", "tavily", "tushare", "wencai",
 		"wikipedia", "yahoo_finance",
 	}
@@ -118,6 +130,9 @@ func TestToolRegistry_SchemasAreComplete(t *testing.T) {
 			"password":    "p",
 			"max_records": 10,
 		},
+		"keenable": {
+			"api_key": "key-xyz",
+		},
 	}
 	tools, err := BuildAll(names, params)
 	if err != nil {
@@ -150,9 +165,9 @@ func TestToolRegistry_SchemasAreComplete(t *testing.T) {
 	// search_my_dateset. A bug here would mean an alias was
 	// accidentally pointed at a different tool.
 	canonicalByAlias := map[string]string{
-		"execute_sql":      "execute_sql",
-		"exesql":           "execute_sql",
-		"retrieval":        "search_my_dateset",
+		"execute_sql":       "execute_sql",
+		"exesql":            "execute_sql",
+		"retrieval":         "search_my_dateset",
 		"search_my_dateset": "search_my_dateset",
 	}
 	for _, name := range names {

internal/agent/tool/retrieval.go

@@ -25,8 +25,10 @@ import (
 
 	"github.com/cloudwego/eino/components/tool"
 	"github.com/cloudwego/eino/schema"
+	"go.uber.org/zap"
 
 	"ragflow/internal/agent/runtime"
+	"ragflow/internal/common"
 )
 
 // ErrGraphRAGNotSupported is returned by the Retrieval tool when
@@ -134,6 +136,12 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
 			return "", fmt.Errorf("retrieval: parse arguments: %w", err)
 		}
 	}
+	common.Debug("agent retrieval tool: parsed arguments",
+		zap.String("query", args.Query),
+		zap.Strings("dataset_ids", args.DatasetIDs),
+		zap.Int("top_n", args.TopN),
+		zap.Bool("use_kg", args.UseKG),
+	)
 
 	if args.UseKG {
 		// Plan  + §9 Q3: GraphRAG is out of scope for the Go
@@ -166,6 +174,9 @@ func (r *RetrievalTool) InvokableRun(ctx context.Context, argumentsInJSON string
 			Error: err.Error(),
 		}), err
 	}
+	common.Debug("agent retrieval tool: search result",
+		zap.Int("chunks_count", len(chunks)),
+	)
 	// Map the chunks into the result envelope. The retrievalResult
 	// type carries the eino-tool envelope shape (chunkPayload, not
 	// RetrievalChunk), so we translate.

internal/agent/tool/retrieval_nlp.go

@@ -62,6 +62,7 @@ import (
 
 	"ragflow/internal/dao"
 	"ragflow/internal/engine"
+	"ragflow/internal/entity"
 	"ragflow/internal/service/nlp"
 )
 
@@ -71,13 +72,21 @@ import (
 // beyond its docEngine + documentDAO handles, both of which the
 // nlp package treats as concurrent-safe.
 type NLPRetrievalAdapter struct {
-	svc *nlp.RetrievalService
+	svc   *nlp.RetrievalService
+	kbDAO knowledgebaseLookup
+}
+
+type knowledgebaseLookup interface {
+	GetByIDs(ids []string) ([]*entity.Knowledgebase, error)
 }
 
 // NewNLPRetrievalAdapter wraps an already-constructed
 // *nlp.RetrievalService.
 func NewNLPRetrievalAdapter(svc *nlp.RetrievalService) *NLPRetrievalAdapter {
-	return &NLPRetrievalAdapter{svc: svc}
+	return &NLPRetrievalAdapter{
+		svc:   svc,
+		kbDAO: dao.NewKnowledgebaseDAO(),
+	}
 }
 
 // NewNLPRetrievalAdapterFromDeps is the convenience constructor
@@ -88,7 +97,10 @@ func NewNLPRetrievalAdapter(svc *nlp.RetrievalService) *NLPRetrievalAdapter {
 // matches chat_session.go's newChatSessionServiceWithRetrieval
 // call site.
 func NewNLPRetrievalAdapterFromDeps(docEngine engine.DocEngine, documentDAO *dao.DocumentDAO) *NLPRetrievalAdapter {
-	return &NLPRetrievalAdapter{svc: nlp.NewRetrievalService(docEngine, documentDAO)}
+	return &NLPRetrievalAdapter{
+		svc:   nlp.NewRetrievalService(docEngine, documentDAO),
+		kbDAO: dao.NewKnowledgebaseDAO(),
+	}
 }
 
 // Search implements RetrievalService. The translation rules live
@@ -120,6 +132,7 @@ func (a *NLPRetrievalAdapter) Search(ctx context.Context, req RetrievalRequest)
 	// headroom — matches the chat_session.go call pattern).
 	nlpReq := &nlp.RetrievalRequest{
 		Question:  req.Query,
+		TenantIDs: a.resolveTenantIDs(req),
 		KbIDs:     append([]string(nil), req.DatasetIDs...),
 		Page:      1,
 		PageSize:  topN,
@@ -148,6 +161,24 @@ func (a *NLPRetrievalAdapter) Search(ctx context.Context, req RetrievalRequest)
 	return out, nil
 }
 
+func (a *NLPRetrievalAdapter) resolveTenantIDs(req RetrievalRequest) []string {
+	seen := map[string]struct{}{}
+	tenantIDs := make([]string, 0, 1)
+	appendTenantID := func(tenantID string) {
+		if tenantID == "" {
+			return
+		}
+		if _, ok := seen[tenantID]; ok {
+			return
+		}
+		seen[tenantID] = struct{}{}
+		tenantIDs = append(tenantIDs, tenantID)
+	}
+
+	appendTenantID(req.TenantID)
+	return tenantIDs
+}
+
 // translateChunk converts one nlp chunk map into a RetrievalChunk.
 // Tolerates missing fields (returns zero values) and wrong types
 // (returns zero values) so a single bad chunk from the doc engine

internal/agent/tool/retrieval_nlp_test.go

@@ -207,3 +207,18 @@ func TestNewNLPRetrievalAdapter_NilService(t *testing.T) {
 		t.Errorf("err = %v, want ErrRetrievalServiceMissing", err)
 	}
 }
+
+func TestNLPRetrievalAdapter_ResolveTenantIDsStaysWithinRequestTenant(t *testing.T) {
+	a := &NLPRetrievalAdapter{}
+	got := a.resolveTenantIDs(RetrievalRequest{
+		TenantID:   "tenant-a",
+		DatasetIDs: []string{"kb-1", "kb-2", "kb-missing"},
+	})
+
+	if len(got) != 1 {
+		t.Fatalf("tenantIDs len=%d want 1, got=%v", len(got), got)
+	}
+	if got[0] != "tenant-a" {
+		t.Fatalf("tenantIDs=%v want [tenant-a]", got)
+	}
+}