Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Feat/agentic kg outline and caller identity (#21053)

Caobaining12b8c97cbae66
diff --git a/internal/agentic_rag/agent.go b/internal/agentic_rag/agent.go
index a09c3710de..991b956e00 100644
--- a/internal/agentic_rag/agent.go
+++ b/internal/agentic_rag/agent.go
@@ -347,11 +347,29 @@ func Run(ctx context.Context, in Input) (string, error) {
tools := toolsFor(ctx, tmpl, in.TenantID, in.DatasetIDs, in.Tools)
// The compiled-knowledge tools are injected, never declared: they only make
// sense when the bound datasets have produced knowledge-compilation products
- // (navigation tree / compiled structure / knowledge graph), so an uncompiled
- // corpus never offers - or pays for - them. A caller that passes explicit
- // tools owns its own set and is left untouched.
- if len(in.Tools) == 0 && datasetsHaveCompiledKnowledge(ctx, in.TenantID, in.DatasetIDs) {
- tools = append(tools, compiledKnowledgeTools(in.TenantID, in.DatasetIDs)...)
+ // (navigation tree / compiled structure / knowledge graph / per-document
+ // panorama), so an uncompiled corpus never offers - or pays for - them. A
+ // caller that passes explicit tools owns its own set and is left untouched.
+ //
+ // The decision is logged on every run. The injection is otherwise silent, so
+ // "the tool was never offered" would be indistinguishable from "the tool was
+ // offered and the model ignored it" in the server log - which is exactly the
+ // question a tool-usage review asks.
+ if len(in.Tools) != 0 {
+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",
+ zap.Strings("datasets", in.DatasetIDs),
+ zap.String("reason", "caller supplied an explicit tool list"))
+ } else if datasetsHaveCompiledKnowledge(ctx, in.TenantID, in.DatasetIDs) {
+ compiled := compiledKnowledgeTools(in.TenantID, in.DatasetIDs)
+ tools = append(tools, compiled...)
+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools injected",
+ zap.Strings("datasets", in.DatasetIDs),
+ zap.String("reason", "compile_kwd rows present in the bound datasets"),
+ zap.Int("tools", len(compiled)))
+ } else {
+ common.InfoCtx(ctx, "agentic_rag: compiled-knowledge tools skipped",
+ zap.Strings("datasets", in.DatasetIDs),
+ zap.String("reason", "no compile_kwd row in the bound datasets"))
}
agentModel, err := modelForTools(ctx, in.Model, tools, in.DatasetIDs)
if err != nil {
diff --git a/internal/agentic_rag/compiled_knowledge.go b/internal/agentic_rag/compiled_knowledge.go
index 7af9d93bb5..904a79cce1 100644
--- a/internal/agentic_rag/compiled_knowledge.go
+++ b/internal/agentic_rag/compiled_knowledge.go
@@ -20,20 +20,29 @@ import (
"context"
"github.com/cloudwego/eino/components/tool"
+ "go.uber.org/zap"
+ "ragflow/internal/common"
"ragflow/internal/engine"
enginetypes "ragflow/internal/engine/types"
)
// compiledKnowledgeToolNames are the tools that only make sense on a corpus that
// has produced knowledge-compilation products (a navigation tree, a compiled
-// structure, a knowledge graph). They are INJECTED, never declared in a
-// template's tool list: Run adds them only when the bound datasets actually hold
-// compiled products, so an uncompiled corpus never offers - or pays for - them.
+// structure, a knowledge graph, a per-document panorama). They are INJECTED,
+// never declared in a template's tool list: Run adds them only when the bound
+// datasets actually hold compiled products, so an uncompiled corpus never
+// offers - or pays for - them.
+//
+// The injected set is the whole compiled-knowledge surface on purpose: a tool
+// that is registered but neither declared by a template nor injected here is
+// unreachable at runtime, which is indistinguishable from "the model chose not
+// to use it" unless someone reads the tool list.
var compiledKnowledgeToolNames = []string{
navigateTreeToolName,
navigateStructureToolName,
graphExploreToolName,
+ graphDocOutlineToolName,
}
// compiledKnowledgeTools builds the injected compiled-knowledge tool set scoped
@@ -71,6 +80,13 @@ func datasetsHaveCompiledKnowledge(ctx context.Context, tenantID string, dataset
IncludeUnavailable: true,
})
if err != nil || res == nil {
+ // A probe that fails for an infrastructure reason (engine down, index
+ // missing) must not read as "this corpus was never compiled": say so,
+ // and let the caller's own INFO line carry the decision.
+ common.DebugCtx(ctx, "agentic_rag: compiled-knowledge probe failed",
+ zap.String("tenant_id", tenantID),
+ zap.Strings("datasets", datasetIDs),
+ zap.Error(err))
return false
}
return len(res.Chunks) > 0
diff --git a/internal/agentic_rag/compiled_knowledge_test.go b/internal/agentic_rag/compiled_knowledge_test.go
new file mode 100644
index 0000000000..c7affed316
--- /dev/null
+++ b/internal/agentic_rag/compiled_knowledge_test.go
@@ -0,0 +1,84 @@
+//
+// 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 agentic_rag
+
+import (
+ "sort"
+ "testing"
+)
+
+// TestCompiledKnowledgeSurfaceIsReachable pins the two ways a compiled-knowledge
+// tool can reach the model: declared by a template's tool list, or injected by
+// Run when the bound datasets hold compiled products. A tool that is neither is
+// registered but dead - and a review that only reads the registry, or only reads
+// the template, cannot tell that apart from "the model chose not to use it".
+func TestCompiledKnowledgeSurfaceIsReachable(t *testing.T) {
+ reg := toolRegistry()
+ for _, name := range compiledKnowledgeToolNames {
+ if _, ok := reg[name]; !ok {
+ t.Errorf("%s is injected but not registered in the tool registry", name)
+ }
+ }
+
+ // The per-document panorama belongs to the same corpus products (a `graph`
+ // row is written by the compiler, like a navigation tree or an entity row),
+ // so it must be injected with the rest rather than left to a template.
+ injected := map[string]bool{}
+ for _, name := range compiledKnowledgeToolNames {
+ injected[name] = true
+ }
+ for _, name := range []string{
+ navigateTreeToolName,
+ navigateStructureToolName,
+ graphExploreToolName,
+ graphDocOutlineToolName,
+ } {
+ if !injected[name] {
+ t.Errorf("%s is never injected: a template that omits it leaves it unreachable", name)
+ }
+ }
+
+ // Build must yield one tool per name, in the same order, with nothing
+ // silently dropped by a missing registry entry.
+ built := compiledKnowledgeTools("tenant", []string{"kb1"})
+ if len(built) != len(compiledKnowledgeToolNames) {
+ t.Errorf("compiledKnowledgeTools built %d tools, want %d", len(built), len(compiledKnowledgeToolNames))
+ }
+}
+
+// TestCompiledKnowledgeNamesAreStable guards the injection list itself: the set
+// is part of the runtime contract (what the model is offered on a compiled
+// corpus), so losing an entry is a behaviour change, not a refactor.
+func TestCompiledKnowledgeNamesAreStable(t *testing.T) {
+ got := append([]string(nil), compiledKnowledgeToolNames...)
+ sort.Strings(got)
+ want := []string{
+ graphDocOutlineToolName,
+ graphExploreToolName,
+ navigateStructureToolName,
+ navigateTreeToolName,
+ }
+ sort.Strings(want)
+ if len(got) != len(want) {
+ t.Fatalf("compiledKnowledgeToolNames = %v, want %v", got, want)
+ }
+ for i := range want {
+ if got[i] != want[i] {
+ t.Fatalf("compiledKnowledgeToolNames = %v, want %v", got, want)
+ }
+ }
+}
diff --git a/internal/agentic_rag/config.go b/internal/agentic_rag/config.go
index abc2e2d467..5c404c6059 100644
--- a/internal/agentic_rag/config.go
+++ b/internal/agentic_rag/config.go
@@ -86,6 +86,11 @@ func toolRegistry() map[string]toolFactory {
// The compiled-knowledge-graph walk. Registered always; a template that
// omits it simply never offers it to the model.
"graph_explore": func(t string, d []string) tool.BaseTool { return NewGraphExploreTool(t, d) },
+ // The compiled-graph panorama read: one call returns a whole document's
+ // entities and relations instead of scanning it chunk by chunk.
+ // Registered always; a template that omits it never offers it to the
+ // model (same pattern as graph_explore).
+ "graph_doc_outline": func(t string, d []string) tool.BaseTool { return NewGraphDocOutlineTool(t, d) },
// The compiled-navigation-tree router. Registered always; a template that
// omits it simply never offers it to the model (same pattern as
// graph_explore).
diff --git a/internal/agentic_rag/grep_service.go b/internal/agentic_rag/grep_service.go
index c4f639c706..c97327f901 100644
--- a/internal/agentic_rag/grep_service.go
+++ b/internal/agentic_rag/grep_service.go
@@ -619,15 +619,22 @@ func regexpLiteralTokens(branch string) []string {
// per-query timeout — the run-level smartReasoningTimeout in
// internal/service/chat_pipeline.go caps the whole agent run. The only concern
// here is a defensive one: eino's streaming ReAct can hand the tool an
-// already-canceled context right after the model emits tool_calls; deriving
-// from context.Background() in that case keeps the query alive instead of being
-// killed by that streaming artifact. Live parents are honored as-is so genuine
-// run-level cancellation still reaches the engine.
+// already-canceled context right after the model emits tool_calls; dropping
+// that parent's cancellation in that case keeps the query alive instead of
+// being killed by that streaming artifact. Live parents are honored as-is so
+// genuine run-level cancellation still reaches the engine.
+//
+// The dropped-cancellation fallback strips the DEADLINE, not the VALUES: the
+// retrieval tools authorize their datasets from the run's identity, which
+// travels in the context (state.Sys["user_id"], see
+// internal/agent/tool/retrieval_nlp.go). Rebuilding from context.Background()
+// here silently erased that identity — and with it every dataset permission
+// check — whenever the streaming artifact above fired.
func engineCallContext(ctx context.Context) (context.Context, context.CancelFunc) {
if ctx.Err() == nil {
return context.WithCancel(ctx)
}
- return context.WithCancel(context.Background())
+ return context.WithCancel(context.WithoutCancel(ctx))
}
// translateGrepChunks converts ES regexp-search result maps into RetrievalChunk.
diff --git a/internal/agentic_rag/kg_service.go b/internal/agentic_rag/kg_service.go
index 770fd3bdea..2e0b83684a 100644
--- a/internal/agentic_rag/kg_service.go
+++ b/internal/agentic_rag/kg_service.go
@@ -48,13 +48,24 @@ const (
kgScopeDataset = "dataset"
kgScopeDoc = "doc"
- kgSeeds = 2 // top-N entities matched directly to the question
- kgSeedPool = 64 // KNN candidate pool before the mention_count re-sort
- kgSeedSim = 0.8 // dense seed similarity floor
- kgHops = 2 // relation hops out from the seeds
- kgNeighbors = 128 // cap on neighbour entity rows resolved per hop
- kgRelLimit = 32 // relations fetched per endpoint filter
- kgMaxPassages = 6 // source passages returned per walk
+ kgSeeds = 2 // top-N entities matched directly to the question
+ kgSeedPool = 64 // KNN candidate pool before the mention_count re-sort
+ kgSeedSim = 0.8 // dense seed similarity floor
+ kgHops = 2 // relation hops out from the seeds
+ kgNeighbors = 128 // cap on neighbour entity rows resolved per hop
+ kgRelLimit = 32 // relations fetched per endpoint filter
+ kgMaxPassages = 6 // source passages returned per walk
+
+ kgOutlineMaxDocs = 3 // documents per outline call
+ kgOutlineRowsEach = 1 // a document has exactly one `graph` row
+ // kgOutlineMaxEntities / kgOutlineMaxRelations bound the skeleton to what
+ // the model can actually use: the hubs. An outline enters the ReAct
+ // transcript and is re-sent on EVERY later turn, so a 60-entity dump costs
+ // more than the deep read it was meant to replace. The mention-count sort
+ // already puts the useful entities first, so cutting the tail is free.
+ kgOutlineMaxEntities = 15
+ kgOutlineMaxRelations = 20
+
kgPassageRunes = 1500
)
@@ -66,6 +77,9 @@ type KgEntity struct {
Aliases []string
SourceChunkIDs []string
DocID string
+ // MentionCount is how often the corpus mentions the entity: a centrality
+ // proxy that lets the caller tell a hub from a leaf.
+ MentionCount int
}
// KgRelation is one relation (edge) row of the compiled graph.
@@ -115,6 +129,7 @@ type KgExploreResult struct {
// so the server can install the engine-backed adapter at boot.
type KgService interface {
Explore(ctx context.Context, req KgExploreRequest) (KgExploreResult, error)
+ DocOutline(ctx context.Context, req KgDocOutlineRequest) (KgExploreResult, error)
}
var (
@@ -147,6 +162,10 @@ func (stubKgService) Explore(context.Context, KgExploreRequest) (KgExploreResult
return KgExploreResult{}, ErrKgServiceMissing
}
+func (stubKgService) DocOutline(context.Context, KgDocOutlineRequest) (KgExploreResult, error) {
+ return KgExploreResult{}, ErrKgServiceMissing
+}
+
// KgAdapter walks the compiled graph rows through the document engine. It is
// stateless and safe to share across goroutines.
type KgAdapter struct {
@@ -586,6 +605,7 @@ func kgParseEntity(row map[string]interface{}) (KgEntity, bool) {
Description: kgStrOr(payload["description"], ""),
SourceChunkIDs: kgStrSlice(row["source_chunk_ids"]),
DocID: kgStr(row["doc_id"]),
+ MentionCount: kgMentionCount(row),
}
if aliases, ok := payload["aliases"].([]interface{}); ok {
for _, alias := range aliases {
@@ -676,3 +696,229 @@ func kgStrSlice(v interface{}) []string {
}
return nil
}
+
+// KgDocOutlineRequest asks for the per-document graph panorama. DocIDs are the
+// documents whose outline the caller wants.
+type KgDocOutlineRequest struct {
+ TenantID string
+ DatasetIDs []string
+ DocIDs []string
+}
+
+// DocOutline returns each document's compiled graph in one shot. Every document
+// the compiler processed carries a single `graph` row holding all of its
+// entities and relations together, so the caller gets the whole skeleton of a
+// long document for the price of one fetch instead of scanning it chunk by
+// chunk. Entities are returned in descending mention order - the hubs first.
+func (a *KgAdapter) DocOutline(ctx context.Context, req KgDocOutlineRequest) (KgExploreResult, error) {
+ empty := KgExploreResult{}
+ if a == nil || a.docEngine == nil {
+ return empty, ErrKgServiceMissing
+ }
+ docIDs := nonEmptyStrings(req.DocIDs)
+ datasetIDs := nonEmptyStrings(req.DatasetIDs)
+ if len(docIDs) == 0 || len(datasetIDs) == 0 {
+ return empty, nil
+ }
+ if len(docIDs) > kgOutlineMaxDocs {
+ docIDs = docIDs[:kgOutlineMaxDocs]
+ }
+
+ var entities []KgEntity
+ var relations []KgRelation
+ seenNames := map[string]bool{}
+ seenRel := map[string]bool{}
+ collectEntities := func(list []KgEntity) {
+ for _, e := range list {
+ key := strings.ToLower(e.Name)
+ if key == "" || seenNames[key] {
+ continue
+ }
+ seenNames[key] = true
+ entities = append(entities, e)
+ }
+ }
+ collectRelations := func(list []KgRelation) {
+ for _, r := range list {
+ key := r.From + "|" + r.To + "|" + r.Type
+ if seenRel[key] {
+ continue
+ }
+ seenRel[key] = true
+ relations = append(relations, r)
+ }
+ }
+ // outlined tracks which of the requested documents actually carry a `graph`
+ // panorama row: the compiler writes exactly one per processed document, but
+ // a document it never processed has none at all.
+ outlined := map[string]bool{}
+ absent := true
+ for _, kbID := range datasetIDs {
+ rows := a.kgSearchRaw(ctx, req.TenantID, kbID, docIDs, "graph", "",
+ nil, nil, "", kgOutlineMaxDocs*kgOutlineRowsEach)
+ if len(rows) > 0 {
+ absent = false
+ }
+ for _, row := range rows {
+ if id := kgStr(row["doc_id"]); id != "" {
+ outlined[id] = true
+ }
+ ents, rels := kgParseGraphRow(row)
+ collectEntities(ents)
+ collectRelations(rels)
+ }
+ }
+
+ // Fallback for documents with no `graph` row. Such a document still carries
+ // its own entity and relation rows, and returning the caller an empty
+ // outline reads to the agent as "this document has no compiled knowledge" -
+ // which is wrong and sends it to the text tools for a skeleton that exists.
+ var fallbackDocs []string
+ for _, id := range docIDs {
+ if id != "" && !outlined[id] {
+ fallbackDocs = append(fallbackDocs, id)
+ }
+ }
+ for _, kbID := range datasetIDs {
+ if len(fallbackDocs) == 0 {
+ break
+ }
+ for _, kind := range []string{"entity", "relation"} {
+ limit := kgOutlineMaxEntities
+ if kind == "relation" {
+ limit = kgOutlineMaxRelations
+ }
+ rows := a.kgSearchRaw(ctx, req.TenantID, kbID, fallbackDocs, kind, "",
+ nil, nil, "mention_count_int", limit)
+ if len(rows) == 0 {
+ continue
+ }
+ absent = false
+ for _, row := range rows {
+ if kind == "entity" {
+ if e, ok := kgParseEntity(row); ok {
+ collectEntities([]KgEntity{e})
+ }
+ continue
+ }
+ if r, ok := kgParseRelation(row); ok {
+ collectRelations([]KgRelation{r})
+ }
+ }
+ }
+ }
+
+ // `absent` so far only says that THESE documents yielded nothing, which is a
+ // document-scoped miss - not the dataset-level fact GraphAbsent carries (see
+ // the KgExploreResult contract). The distinction decides whether the tool
+ // disables itself for the conversation, so a scoped miss must not claim it:
+ // one unprocessed document, or a transient engine failure (kgSearchRaw
+ // reports a failed read as no rows), would otherwise turn graph_doc_outline
+ // off until the TTL expires - and the renderKgDocOutline branch that
+ // explains "these documents carry no compiled graph row" could never be
+ // reached. Probe the datasets exactly as Explore does: propagate a probe
+ // failure instead of reading an infrastructure error as "no graph", let any
+ // dataset that does carry compiled rows turn this into a scoped miss, and
+ // report the absence only when every probe succeeded and found nothing.
+ if absent {
+ for _, kbID := range datasetIDs {
+ has, probeErr := a.graphRowsExist(ctx, req.TenantID, kbID, nil, "")
+ if probeErr != nil {
+ return empty, probeErr
+ }
+ if has {
+ absent = false
+ break
+ }
+ }
+ }
+
+ // Mention count is the only centrality signal the panorama carries, and the
+ // caller reads a bounded payload: sort so the hubs survive the cap.
+ sort.SliceStable(entities, func(i, j int) bool {
+ return entities[i].MentionCount > entities[j].MentionCount
+ })
+ if len(entities) > kgOutlineMaxEntities {
+ entities = entities[:kgOutlineMaxEntities]
+ }
+ if len(relations) > kgOutlineMaxRelations {
+ relations = relations[:kgOutlineMaxRelations]
+ }
+
+ passages := a.evidencePassages(ctx, req.TenantID, datasetIDs, entities, relations)
+ return KgExploreResult{
+ Entities: entities,
+ Relations: relations,
+ Passages: passages,
+ GraphAbsent: absent,
+ }, nil
+}
+
+// kgParseGraphRow projects a document's `graph` panorama row - every entity
+// and relation the compiler extracted from that document, serialised as
+// entities and relations in a single JSON payload - into the shared types.
+func kgParseGraphRow(row map[string]interface{}) ([]KgEntity, []KgRelation) {
+ raw := kgStr(row["content_with_weight"])
+ if raw == "" {
+ return nil, nil
+ }
+ var payload struct {
+ Entities []struct {
+ Name string `json:"name"`
+ Type string `json:"type"`
+ Description string `json:"description"`
+ MentionCount interface{} `json:"mention_count"`
+ SourceChunkIDs interface{} `json:"source_chunk_ids"`
+ } `json:"entities"`
+ Relations []struct {
+ From string `json:"from"`
+ To string `json:"to"`
+ Type string `json:"type"`
+ } `json:"relations"`
+ }
+ if err := json.Unmarshal([]byte(raw), &payload); err != nil {
+ return nil, nil
+ }
+ docID := kgStr(row["doc_id"])
+ entities := make([]KgEntity, 0, len(payload.Entities))
+ for _, e := range payload.Entities {
+ name := strings.TrimSpace(e.Name)
+ if name == "" {
+ continue
+ }
+ entities = append(entities, KgEntity{
+ Name: name,
+ Type: kgStrOr(e.Type, "other"),
+ Description: e.Description,
+ SourceChunkIDs: kgStrSlice(e.SourceChunkIDs),
+ DocID: docID,
+ MentionCount: int(kgFloat(e.MentionCount)),
+ })
+ }
+ relations := make([]KgRelation, 0, len(payload.Relations))
+ for _, r := range payload.Relations {
+ from, to := strings.TrimSpace(r.From), strings.TrimSpace(r.To)
+ if from == "" || to == "" {
+ continue
+ }
+ relations = append(relations, KgRelation{
+ From: from, To: to, Type: kgStrOr(r.Type, "other"), DocID: docID,
+ })
+ }
+ return entities, relations
+}
+
+// kgFloat reads a JSON number that may decode as any numeric type.
+func kgFloat(v interface{}) float64 {
+ switch x := v.(type) {
+ case float64:
+ return x
+ case float32:
+ return float64(x)
+ case int:
+ return float64(x)
+ case int64:
+ return float64(x)
+ }
+ return 0
+}
diff --git a/internal/agentic_rag/tool_doc_outline.go b/internal/agentic_rag/tool_doc_outline.go
new file mode 100644
index 0000000000..09e96937f3
--- /dev/null
+++ b/internal/agentic_rag/tool_doc_outline.go
@@ -0,0 +1,281 @@
+//
+// 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 agentic_rag
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ einotool "github.com/cloudwego/eino/components/tool"
+ "github.com/cloudwego/eino/schema"
+ "github.com/eino-contrib/jsonschema"
+ "go.uber.org/zap"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+)
+
+// graphDocOutlineToolName returns a whole document's compiled skeleton in one
+// call: entities plus relations, hubs first.
+const graphDocOutlineToolName = "graph_doc_outline"
+
+const graphDocOutlineToolDescription = `Get the COMPILED GRAPH SKELETON of whole documents in one call: the entities and relations the compiler extracted from each, TOGETHER, every entity carrying its mention count, type and description, hubs first.
+
+## Two ways in
+- **query** (the way in when you do NOT yet hold a doc_id): a short keyword phrase naming what the document is about. The tool locates the candidate documents for that phrase ITSELF and returns their skeletons, so you do not have to search first.
+- **doc_ids** (1-3): documents you already identified in earlier tool output.
+
+Pass either doc_ids or query; doc_ids wins when both are given.
+
+Use it BEFORE you deep-read: one call gives you a document's key entities and the edges between them, which is far cheaper than scanning it chunk by chunk, and it tells you which entities are worth following up with graph_path or a keyword search. It also returns the source passages behind the entities so the skeleton comes with citable text.
+
+Returns an XML <kg_doc_outline> document: <entity name type mentions description> children in descending mention order, <relation from to type> children, then one <passage chunk_id doc_id doc_name ref> element per source chunk with a <content> body. The ref attribute is the [ID:n] handle to cite.
+
+An empty result with error="no compiled knowledge graph" is a DATASET-level absence - do not retry this tool. An empty result carrying located_nothing="true" is a QUERY-level miss: the query matched no document - rephrase it with the corpus's own wording, or locate documents with grep_chunks / search_bm25_chunks and call again with their doc_ids. Otherwise an empty result means these documents carry no compiled graph row: that is a finding about the document, not a failure - read it with list_chunks instead.`
+
+// graphDocOutlineArgs is the JSON the model sends into InvokableRun.
+type graphDocOutlineArgs struct {
+ DocIDs []string `json:"doc_ids"`
+ Query string `json:"query,omitempty"`
+ DatasetIDs []string `json:"dataset_ids,omitempty"`
+}
+
+// Rendering caps: the model reads a bounded payload, not the whole graph.
+const (
+ graphDocOutlineMaxPassages = 3
+ graphDocOutlineMaxDatasets = 10
+ // graphDocOutlineLocateTopN is the chunk window one BM25 pass reads to turn
+ // a query into candidate documents. Only the documents matter, and the
+ // first few hits are the ones whose skeleton is worth the graph read.
+ graphDocOutlineLocateTopN = 12
+)
+
+// GraphDocOutlineTool reads per-document graph panoramas via KgService. It is
+// stateless: the tenant and dataset scope are injected at construction.
+type GraphDocOutlineTool struct {
+ tenantID string
+ datasetIDs []string
+}
+
+// NewGraphDocOutlineTool returns a GraphDocOutlineTool scoped to the given
+// tenant and datasets, implementing eino's runtime.InvokableTool.
+func NewGraphDocOutlineTool(tenantID string, datasetIDs []string) *GraphDocOutlineTool {
+ return &GraphDocOutlineTool{tenantID: tenantID, datasetIDs: datasetIDs}
+}
+
+// Info returns the tool's metadata for the chat model.
+func (g *GraphDocOutlineTool) Info(_ context.Context) (*schema.ToolInfo, error) {
+ schemaJSON := `{
+ "type": "object",
+ "properties": {
+ "doc_ids": {
+ "type": "array",
+ "description": "1-3 document ids whose compiled skeleton you want, taken from earlier tool output. Omit this and pass query instead when you do not have a doc_id yet.",
+ "items": { "type": "string" },
+ "minItems": 1,
+ "maxItems": 3
+ },
+ "query": {
+ "type": "string",
+ "description": "A short keyword phrase naming what the document is about. Use this when you do NOT yet hold a doc_id: the tool locates the candidate documents for the phrase itself and returns their compiled skeletons. Pass either doc_ids or query.",
+ "minLength": 1
+ },
+ "dataset_ids": {
+ "type": "array",
+ "description": "Optional dataset ids to restrict the lookup to (at most 10). When omitted, the conversation's bound datasets are used.",
+ "items": { "type": "string" },
+ "maxItems": 10
+ }
+ }
+}`
+ s := &jsonschema.Schema{}
+ if err := json.Unmarshal([]byte(schemaJSON), s); err != nil {
+ return nil, fmt.Errorf("graph_doc_outline: parse schema: %w", err)
+ }
+ return &schema.ToolInfo{
+ Name: graphDocOutlineToolName,
+ Desc: graphDocOutlineToolDescription,
+ ParamsOneOf: schema.NewParamsOneOfByJSONSchema(s),
+ }, nil
+}
+
+// InvokableRun returns the XML <kg_doc_outline> document.
+func (g *GraphDocOutlineTool) InvokableRun(ctx context.Context, argumentsInJSON string, _ ...einotool.Option) (string, error) {
+ return guardedToolRun(ctx, graphDocOutlineToolName, g.invokableRun, argumentsInJSON)
+}
+
+func (g *GraphDocOutlineTool) invokableRun(ctx context.Context, argumentsInJSON string) (string, error) {
+ var args graphDocOutlineArgs
+ if err := json.Unmarshal([]byte(argumentsInJSON), &args); err != nil {
+ return "", fmt.Errorf("graph_doc_outline: parse arguments: %w", err)
+ }
+ docIDs := nonEmptyStrings(args.DocIDs)
+ query := strings.TrimSpace(args.Query)
+ // Entry trace: logged BEFORE validation and before the service call, so the
+ // A/B gate can tell "never called" from "called and failed".
+ common.InfoCtx(ctx, "agentic_rag: graph_doc_outline called",
+ zap.Int("docs", len(docIDs)),
+ zap.Bool("via_query", len(docIDs) == 0 && query != ""))
+ if len(docIDs) == 0 && query == "" {
+ return "", fmt.Errorf("graph_doc_outline: pass either 1-%d doc_ids or a query to locate them", kgOutlineMaxDocs)
+ }
+ if len(docIDs) > kgOutlineMaxDocs {
+ return "", fmt.Errorf("graph_doc_outline: at most %d doc_ids allowed, got %d", kgOutlineMaxDocs, len(docIDs))
+ }
+ if !navToolEnabled(ctx, graphDocOutlineToolName) {
+ return renderKgDocOutline(ctx, docIDs, KgExploreResult{GraphAbsent: true}), nil
+ }
+
+ datasetIDs, err := resolveDatasetScope(g.datasetIDs, args.DatasetIDs)
+ if err != nil {
+ return "", fmt.Errorf("graph_doc_outline: %w", err)
+ }
+ if len(datasetIDs) == 0 {
+ // Bound scope is empty: short-circuit before touching the backend so the
+ // tool never reads outside the conversation's allowed datasets.
+ return renderKgDocOutline(ctx, docIDs, KgExploreResult{GraphAbsent: true}), nil
+ }
+
+ // Query entry: the model knows the question but not which document holds
+ // it. Locating here costs one BM25 pass and saves the model a whole search
+ // call plus a second outline call carrying the doc_ids that search returned.
+ if len(docIDs) == 0 {
+ docIDs = locateDocIDsForOutline(ctx, g.tenantID, datasetIDs, query)
+ if len(docIDs) == 0 {
+ return renderKgDocOutlineLocateMiss(ctx, query), nil
+ }
+ }
+
+ result, err := GetKgService().DocOutline(ctx, KgDocOutlineRequest{
+ TenantID: g.tenantID,
+ DatasetIDs: datasetIDs,
+ DocIDs: docIDs,
+ })
+ if err != nil {
+ return "", fmt.Errorf("graph_doc_outline: %w", err)
+ }
+ if result.GraphAbsent {
+ markNavToolUnavailable(ctx, graphDocOutlineToolName)
+ common.DebugCtx(ctx, "graph_doc_outline: marking unavailable for conversation (no compiled knowledge graph)")
+ }
+ common.InfoCtx(ctx, "agentic_rag: graph_doc_outline",
+ zap.Int("docs", len(docIDs)),
+ zap.Int("datasets", len(datasetIDs)),
+ zap.Int("entities", len(result.Entities)),
+ zap.Int("relations", len(result.Relations)),
+ zap.Int("passages", len(result.Passages)))
+ return renderKgDocOutline(ctx, docIDs, result), nil
+}
+
+// renderKgDocOutline serialises one skeleton read. Passages carry the same
+// `ref` handles the locate/deep-read tools stamp, so a fact read from the graph
+// is citable exactly like one read from a chunk.
+func renderKgDocOutline(ctx context.Context, docIDs []string, result KgExploreResult) string {
+ passages := result.Passages
+ if len(passages) > graphDocOutlineMaxPassages {
+ passages = passages[:graphDocOutlineMaxPassages]
+ }
+
+ var b strings.Builder
+ b.WriteString(fmt.Sprintf("<kg_doc_outline docs=\"%d\" entities=\"%d\" relations=\"%d\" passages=\"%d\">\n",
+ len(docIDs), len(result.Entities), len(result.Relations), len(passages)))
+ if len(result.Entities) == 0 && len(result.Relations) == 0 {
+ if result.GraphAbsent {
+ b.WriteString("<note error=\"no compiled knowledge graph\">This dataset has NO compiled knowledge graph (or none in the given scope). graph_doc_outline is unavailable here - do not retry it; read the documents with list_chunks instead.</note>\n")
+ } else {
+ b.WriteString("<note>These documents carry no compiled graph row. That is a finding about the document, not a failure - read it with list_chunks instead.</note>\n")
+ }
+ b.WriteString("</kg_doc_outline>")
+ return b.String()
+ }
+ for _, e := range result.Entities {
+ b.WriteString(fmt.Sprintf("<entity name=\"%s\" type=\"%s\" mentions=\"%d\"",
+ xmlEscape(e.Name), xmlEscape(e.Type), e.MentionCount))
+ if e.Description != "" {
+ b.WriteString(fmt.Sprintf(" description=\"%s\"", xmlEscape(truncateRunes(e.Description, 150))))
+ }
+ b.WriteString("/>\n")
+ }
+ for _, r := range result.Relations {
+ b.WriteString(fmt.Sprintf("<relation from=\"%s\" to=\"%s\" type=\"%s\"/>\n",
+ xmlEscape(r.From), xmlEscape(r.To), xmlEscape(r.Type)))
+ }
+ reg := evidenceRegistryFrom(ctx)
+ if len(passages) > 0 {
+ // These passages are the full chunk text with the same ref handles the
+ // deep-read tools stamp. Saying so in the payload is what stops the
+ // agent from paying for the same evidence twice: an outline followed by
+ // list_chunks on the chunks it already carried is pure duplicated cost.
+ b.WriteString("<note>The passages below are FULL chunk text with ref handles - cite them directly. Do NOT re-read them with list_chunks; that would duplicate text you already hold.</note>\n")
+ }
+ for _, p := range passages {
+ b.WriteString(fmt.Sprintf(
+ "<passage chunk_id=\"%s\" doc_id=\"%s\" doc_name=\"%s\" dataset_id=\"%s\"%s>\n",
+ xmlEscape(p.ChunkID), xmlEscape(p.DocID), xmlEscape(p.DocName), xmlEscape(p.DatasetID),
+ refAttrOf(reg, p.ChunkID)))
+ b.WriteString(fmt.Sprintf("<content>%s</content>\n", xmlEscape(p.Content)))
+ b.WriteString("</passage>\n")
+ }
+ b.WriteString("</kg_doc_outline>")
+ return b.String()
+}
+
+// locateDocIDsForOutline turns a query into the documents whose compiled
+// skeletons should be read: one lexical BM25 pass, documents taken in
+// retrieval order, capped at kgOutlineMaxDocs. It is the entry point that lets
+// the model reach the compiled graph before it holds any doc_id. The pass is
+// lexical on purpose - that keeps the entry working on a corpus whose
+// embedding backend is unavailable.
+func locateDocIDsForOutline(ctx context.Context, tenantID string, datasetIDs []string, query string) []string {
+ chunks, err := runtime.GetBm25Service().SearchBm25(ctx, runtime.Bm25Request{
+ Queries: []string{query},
+ DatasetIDs: datasetIDs,
+ TopN: graphDocOutlineLocateTopN,
+ TenantID: tenantID,
+ })
+ if err != nil {
+ common.WarnCtx(ctx, "graph_doc_outline: query entry locate failed",
+ zap.String("query", query), zap.Error(err))
+ return nil
+ }
+ ids := make([]string, 0, kgOutlineMaxDocs)
+ seen := make(map[string]bool, len(chunks))
+ for _, c := range chunks {
+ if c.DocumentID == "" || seen[c.DocumentID] {
+ continue
+ }
+ seen[c.DocumentID] = true
+ ids = append(ids, c.DocumentID)
+ if len(ids) == kgOutlineMaxDocs {
+ break
+ }
+ }
+ return ids
+}
+
+// renderKgDocOutlineLocateMiss reports a query-entry miss. It is a QUERY-level
+// miss - the graph itself is present - so it must neither disable the tool nor
+// read as a dataset-level absence.
+func renderKgDocOutlineLocateMiss(ctx context.Context, query string) string {
+ var b strings.Builder
+ b.WriteString("<kg_doc_outline docs=\"0\" entities=\"0\" relations=\"0\" passages=\"0\" located_nothing=\"true\">\n")
+ b.WriteString(fmt.Sprintf("<note>The query %q located no document, so there is no skeleton to read. This is a QUERY-level miss, not a missing graph - the tool still works here. Rephrase it with the corpus's own wording, or locate documents with grep_chunks / search_bm25_chunks and call graph_doc_outline again with their doc_ids.</note>\n", xmlEscape(query)))
+ b.WriteString("</kg_doc_outline>")
+ return b.String()
+}
diff --git a/internal/agentic_rag/tool_graph_explore.go b/internal/agentic_rag/tool_graph_explore.go
index a298b00032..9615bb80fd 100644
--- a/internal/agentic_rag/tool_graph_explore.go
+++ b/internal/agentic_rag/tool_graph_explore.go
@@ -25,6 +25,7 @@ import (
einotool "github.com/cloudwego/eino/components/tool"
"github.com/cloudwego/eino/schema"
"github.com/eino-contrib/jsonschema"
+ "go.uber.org/zap"
"ragflow/internal/common"
)
@@ -116,6 +117,10 @@ func (g *GraphExploreTool) invokableRun(ctx context.Context, argumentsInJSON str
if query == "" {
return "", fmt.Errorf("graph_explore: query is required and must be a non-empty string")
}
+ // Entry trace: logged BEFORE the enablement check and the backend call, so
+ // the tool-usage gate can tell "never called" from "called and bailed out".
+ common.InfoCtx(ctx, "agentic_rag: graph_explore called",
+ zap.String("query", query), zap.Int("doc_scope", len(args.DocScope)))
if !navToolEnabled(ctx, graphExploreToolName) {
// Marked unavailable for this conversation (bound datasets have no
// compiled knowledge graph): skip the backend and return the same
@@ -151,6 +156,15 @@ func (g *GraphExploreTool) invokableRun(ctx context.Context, argumentsInJSON str
markNavToolUnavailable(ctx, graphExploreToolName)
common.DebugCtx(ctx, "graph_explore: marking unavailable for conversation (no compiled knowledge graph)")
}
+ // Per-call INFO: the tool-usage gate (kg_tool_calls) is read off the server
+ // log, so a graph tool that calls the backend without leaving a line here
+ // cannot be told from one that was never called.
+ common.InfoCtx(ctx, "agentic_rag: graph_explore",
+ zap.String("query", query),
+ zap.Int("datasets", len(datasetIDs)),
+ zap.Int("entities", len(result.Entities)),
+ zap.Int("relations", len(result.Relations)),
+ zap.Int("passages", len(result.Passages)))
return renderKgExplore(ctx, query, result), nil
}
diff --git a/internal/agentic_rag/tool_graph_explore_test.go b/internal/agentic_rag/tool_graph_explore_test.go
index a2e920421a..0e8dfdc9da 100644
--- a/internal/agentic_rag/tool_graph_explore_test.go
+++ b/internal/agentic_rag/tool_graph_explore_test.go
@@ -38,6 +38,13 @@ func (f *fakeKgService) Explore(_ context.Context, req KgExploreRequest) (KgExpl
return f.result, f.err
}
+// DocOutline completes KgService. This fake only ever backs the explore tool's
+// tests, so it carries the fake's canned error (nil by default) and returns no
+// skeleton.
+func (f *fakeKgService) DocOutline(context.Context, KgDocOutlineRequest) (KgExploreResult, error) {
+ return KgExploreResult{}, f.err
+}
+
func installFakeKgService(t *testing.T, svc KgService) {
t.Helper()
previous := GetKgService()
@@ -373,3 +380,175 @@ func TestKgAdapterExploreProbeFailureIsAnError(t *testing.T) {
t.Fatalf("probe failure must surface as an error, got %v", err)
}
}
+
+// kgOutlineFakeEngine serves the per-document panorama read and the
+// entity/relation fallback from separate row sets, so a test can hand a
+// document only one of them.
+type kgOutlineFakeEngine struct {
+ engine.DocEngine
+ graphRows []map[string]interface{}
+ entityRows []map[string]interface{}
+ relationRows []map[string]interface{}
+ searchErr error
+ reads []string
+}
+
+func (e *kgOutlineFakeEngine) Search(_ context.Context, req *enginetypes.SearchRequest) (*enginetypes.SearchResult, error) {
+ kind, _ := req.Filter["knowledge_graph_kwd"].(string)
+ e.reads = append(e.reads, kind)
+ if e.searchErr != nil {
+ return nil, e.searchErr
+ }
+ var rows []map[string]interface{}
+ switch kind {
+ case "graph":
+ rows = e.graphRows
+ case "entity":
+ rows = e.entityRows
+ case "relation":
+ rows = e.relationRows
+ }
+ // A real engine applies the doc_id term filter, and the outline relies on it:
+ // the fallback read is scoped to the requested documents, while the dataset
+ // probe is unscoped. Without this, a fixture row for another document would
+ // answer a document-scoped read.
+ if docs, ok := req.Filter["doc_id"].([]string); ok && len(docs) > 0 {
+ keep := make(map[string]bool, len(docs))
+ for _, d := range docs {
+ keep[d] = true
+ }
+ scoped := make([]map[string]interface{}, 0, len(rows))
+ for _, row := range rows {
+ if id, _ := row["doc_id"].(string); keep[id] {
+ scoped = append(scoped, row)
+ }
+ }
+ rows = scoped
+ }
+ return &enginetypes.SearchResult{Chunks: rows}, nil
+}
+
+// TestKgAdapterDocOutlineFallsBackToPerDocumentRows pins the gap fix: a document
+// the compiler wrote no `graph` panorama for still carries its own entity and
+// relation rows, so the outline is built from those instead of coming back
+// empty - which the agent reads as "this document has no compiled knowledge".
+func TestKgAdapterDocOutlineFallsBackToPerDocumentRows(t *testing.T) {
+ eng := &kgOutlineFakeEngine{
+ entityRows: []map[string]interface{}{{
+ "doc_id": "d1", "mention_count_int": 7,
+ "content_with_weight": `{"name":"Marie Curie","type":"person"}`,
+ }},
+ relationRows: []map[string]interface{}{{
+ "doc_id": "d1", "from_entity_kwd": "marie curie", "to_entity_kwd": "radium",
+ "content_with_weight": `{"type":"discovered"}`,
+ }},
+ }
+ got, err := NewKgAdapter(eng).DocOutline(context.Background(), KgDocOutlineRequest{
+ TenantID: "t1", DatasetIDs: []string{"kb1"}, DocIDs: []string{"d1"},
+ })
+ if err != nil {
+ t.Fatalf("DocOutline: %v", err)
+ }
+ if got.GraphAbsent {
+ t.Error("entity rows exist for the document: a dataset-level absence must not be reported")
+ }
+ if len(got.Entities) != 1 || got.Entities[0].Name != "Marie Curie" || got.Entities[0].MentionCount != 7 {
+ t.Errorf("entities = %+v, want the fallback entity row", got.Entities)
+ }
+ if len(got.Relations) != 1 || got.Relations[0].Type != "discovered" {
+ t.Errorf("relations = %+v, want the fallback relation row", got.Relations)
+ }
+ if len(eng.reads) == 0 || eng.reads[0] != "graph" {
+ t.Errorf("reads = %v, want the panorama read first", eng.reads)
+ }
+}
+
+// TestKgAdapterDocOutlinePrefersThePanoramaRows: when the document HAS a
+// panorama row the fallback must not run, so a document is never read twice.
+func TestKgAdapterDocOutlinePrefersThePanoramaRows(t *testing.T) {
+ eng := &kgOutlineFakeEngine{
+ graphRows: []map[string]interface{}{{
+ "doc_id": "d1",
+ "content_with_weight": `{"entities":[{"name":"Hub","type":"org"}],` +
+ `"relations":[{"from":"Hub","to":"Leaf","type":"owns"}]}`,
+ }},
+ entityRows: []map[string]interface{}{{
+ "doc_id": "d1", "content_with_weight": `{"name":"Fallback","type":"other"}`,
+ }},
+ }
+ got, err := NewKgAdapter(eng).DocOutline(context.Background(), KgDocOutlineRequest{
+ TenantID: "t1", DatasetIDs: []string{"kb1"}, DocIDs: []string{"d1"},
+ })
+ if err != nil {
+ t.Fatalf("DocOutline: %v", err)
+ }
+ if len(got.Entities) != 1 || got.Entities[0].Name != "Hub" {
+ t.Errorf("entities = %+v, want only the panorama entity", got.Entities)
+ }
+ for _, kind := range eng.reads {
+ if kind == "entity" || kind == "relation" {
+ t.Errorf("reads = %v: the fallback ran for a document that has a panorama", eng.reads)
+ break
+ }
+ }
+}
+
+// TestKgAdapterDocOutlineScopedMissIsNotDatasetAbsence pins the contract the
+// tool's self-disable rides on: GraphAbsent is a dataset-level fact, so a
+// document that yielded no row - an unprocessed document, or a BM25 hit whose
+// document was never compiled - must come back as a plain empty result. Were it
+// reported as an absence, one such document would turn graph_doc_outline off for
+// the rest of the conversation (markNavToolUnavailable), and the renderer's
+// "these documents carry no compiled graph row" note could never be reached.
+func TestKgAdapterDocOutlineScopedMissIsNotDatasetAbsence(t *testing.T) {
+ eng := &kgOutlineFakeEngine{
+ entityRows: []map[string]interface{}{{
+ "doc_id": "other-doc", "content_with_weight": `{"name":"Someone else","type":"person"}`,
+ }},
+ }
+ got, err := NewKgAdapter(eng).DocOutline(context.Background(), KgDocOutlineRequest{
+ TenantID: "t1", DatasetIDs: []string{"kb1"}, DocIDs: []string{"d-never-compiled"},
+ })
+ if err != nil {
+ t.Fatalf("DocOutline: %v", err)
+ }
+ if got.GraphAbsent {
+ t.Error("a document-scoped miss must not report a dataset-level absence: the tool would disable itself")
+ }
+ if len(got.Entities) != 0 || len(got.Relations) != 0 {
+ t.Errorf("entities/relations = %d/%d, want the requested document's empty payload", len(got.Entities), len(got.Relations))
+ }
+}
+
+// TestKgAdapterDocOutlineAbsentOnlyWhenNothingIsCompiled is the other half: the
+// absence IS reported when every scoped read came back empty AND the dataset
+// holds no compiled row at all, which is the only case that may disable the tool.
+func TestKgAdapterDocOutlineAbsentOnlyWhenNothingIsCompiled(t *testing.T) {
+ got, err := NewKgAdapter(&kgOutlineFakeEngine{}).DocOutline(context.Background(), KgDocOutlineRequest{
+ TenantID: "t1", DatasetIDs: []string{"kb1"}, DocIDs: []string{"d1"},
+ })
+ if err != nil {
+ t.Fatalf("DocOutline: %v", err)
+ }
+ if !got.GraphAbsent {
+ t.Error("an uncompiled dataset must report the dataset-level absence")
+ }
+}
+
+// TestKgAdapterDocOutlineProbeFailureIsNotAbsence: a read failure looks like "no
+// rows" to this code path, so it must be settled by the probe, not assumed. A
+// failing probe has to surface as an error - a transient engine failure may
+// never masquerade as "this dataset has no compiled knowledge", because that
+// answer disables the tool for the conversation.
+func TestKgAdapterDocOutlineProbeFailureIsNotAbsence(t *testing.T) {
+ eng := &kgOutlineFakeEngine{searchErr: errors.New("engine down")}
+ got, err := NewKgAdapter(eng).DocOutline(context.Background(), KgDocOutlineRequest{
+ TenantID: "t1", DatasetIDs: []string{"kb1"}, DocIDs: []string{"d1"},
+ })
+ if err == nil {
+ t.Fatalf("probe failure must surface as an error, got GraphAbsent=%v", got.GraphAbsent)
+ }
+ if !strings.Contains(err.Error(), "engine down") {
+ t.Errorf("error = %v, want the probe failure", err)
+ }
+}
diff --git a/internal/agentic_rag/tool_navigate_structure.go b/internal/agentic_rag/tool_navigate_structure.go
index 440b3998d5..ad06bfbbcd 100644
--- a/internal/agentic_rag/tool_navigate_structure.go
+++ b/internal/agentic_rag/tool_navigate_structure.go
@@ -1091,6 +1091,11 @@ func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSO
if query == "" {
return "", fmt.Errorf("navigate_structure: query is required and must be a non-empty string")
}
+ // Entry trace: logged BEFORE the enablement check and the backend call, so
+ // the tool-usage gate can tell "never called" from "called and bailed out".
+ common.InfoCtx(ctx, "agentic_rag: navigate_structure called",
+ zap.String("query", query), zap.String("kind", args.Kind),
+ zap.Int("docs", len(args.DocIDs)))
if !navToolEnabled(ctx, navigateStructureToolName) {
// Marked unavailable for this conversation (bound datasets have no
// compiled structure): skip the backend and return the same verdict the
@@ -1125,5 +1130,14 @@ func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSO
text := strings.TrimSpace(query + " " + strings.TrimSpace(args.Keywords))
out, reason := navigateStructures(ctx, g.tenantID, text, docIDs, datasetIDs, args.Kind, reader)
_ = reason
+ // Per-call INFO: the tool-usage gate (kg_tool_calls) is read off the server
+ // log, so a graph tool that rendered a structure without leaving a line here
+ // cannot be told from one that was never called.
+ common.InfoCtx(ctx, "agentic_rag: navigate_structure",
+ zap.String("query", query),
+ zap.Int("datasets", len(datasetIDs)),
+ zap.Int("docs", len(docIDs)),
+ zap.Strings("names", docIDs),
+ zap.Int("out_bytes", len(out)))
return out, nil
}
diff --git a/internal/agentic_rag/tool_navigate_tree.go b/internal/agentic_rag/tool_navigate_tree.go
index 359d9b5c48..99eb64c47b 100644
--- a/internal/agentic_rag/tool_navigate_tree.go
+++ b/internal/agentic_rag/tool_navigate_tree.go
@@ -133,6 +133,10 @@ func (g *NavigateTreeTool) invokableRun(ctx context.Context, argumentsInJSON str
if query == "" {
return "", fmt.Errorf("navigate_tree: query is required and must be a non-empty string")
}
+ // Entry trace: logged BEFORE the enablement check and the backend call, so
+ // the tool-usage gate can tell "never called" from "called and bailed out".
+ common.InfoCtx(ctx, "agentic_rag: navigate_tree called",
+ zap.String("query", query), zap.Int("doc_scope", len(args.DocScope)))
datasetIDs, err := resolveDatasetScope(g.datasetIDs, args.DatasetIDs)
if err != nil {
return "", fmt.Errorf("navigate_tree: %w", err)
@@ -208,6 +212,18 @@ func (g *NavigateTreeTool) invokableRun(ctx context.Context, argumentsInJSON str
if len(ordered) > navTreeMaxDocs {
ordered = ordered[:navTreeMaxDocs]
}
+ // Per-call INFO: the tool-usage gate (kg_tool_calls) is read off the server
+ // log, so a graph tool that routed documents without leaving a line here
+ // cannot be told from one that was never called.
+ names := make([]string, 0, len(ordered))
+ for _, pair := range ordered {
+ names = append(names, pair[0])
+ }
+ common.InfoCtx(ctx, "agentic_rag: navigate_tree",
+ zap.String("query", query),
+ zap.Int("datasets", len(datasetIDs)),
+ zap.Int("docs", len(ordered)),
+ zap.Strings("names", names))
parts := []string{fmt.Sprintf(`<tree_navigation count="%d" query="%s">`, len(ordered), xmlEscape(query))}
for i, pair := range ordered {
if pair[1] != "" {
diff --git a/internal/service/agentic_pipeline.go b/internal/service/agentic_pipeline.go
index febb9041f6..3d74a9c5fa 100644
--- a/internal/service/agentic_pipeline.go
+++ b/internal/service/agentic_pipeline.go
@@ -25,6 +25,7 @@ import (
"github.com/cloudwego/eino/schema"
"go.uber.org/zap"
+ "ragflow/internal/agent/runtime"
"ragflow/internal/agentic_rag"
"ragflow/internal/common"
"ragflow/internal/entity"
@@ -95,6 +96,18 @@ func (s *ChatPipelineService) agenticRag(
// those handles against the same numbering.
registry := agentic_rag.NewEvidenceRegistry()
runCtx = agentic_rag.WithEvidenceRegistry(runCtx, registry)
+ // The retrieval tools authorize their datasets as the CALLER of the run,
+ // not as the chat's tenant: NLPRetrievalAdapter.Search reads that identity
+ // from the run's runtime state (state.Sys["user_id"]) and treats a missing
+ // state as an empty subject, which fails every dataset permission check and
+ // kills the vector-only locate tool. The canvas path gets this state from
+ // its compile step; the agentic path has no canvas, so attach it here.
+ runState := runtime.NewCanvasState("", chat.ID)
+ if userID != "" {
+ runState.Sys["user_id"] = userID
+ runState.Sys["tenant_id"] = chat.TenantID
+ }
+ runCtx = runtime.WithState(runCtx, runState)
emitResult := func(result AsyncChatResult) bool {
select {
case out <- result: