RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(sdk-agent): restore agent API contracts (#21731)
Sbaaoui Idrissa749eb44185e
diff --git a/internal/handler/agent.go b/internal/handler/agent.goindex d4733f6e68..812641c81d 100644--- a/internal/handler/agent.go+++ b/internal/handler/agent.go@@ -1046,7 +1046,10 @@ func (h *AgentHandler) CreateAgentSession(c *gin.Context) {common.ErrorWithCode(c, code, err.Error())return}- common.SuccessWithData(c, row, "success")+ common.SuccessWithData(c, struct {+ *entity.API4Conversation+ AgentID string `json:"agent_id"`+ }{row, row.DialogID}, "success")}// GetAgentSession GET /api/v1/agents/:canvas_id/sessions/:session_id@@ -1076,7 +1079,7 @@ func (h *AgentHandler) GetAgentSession(c *gin.Context) {//// Path parameter disambiguation:// - /sessions/:session_id -> single item delete-// - /sessions?ids=a,b -> batch delete (delete_all when ids is empty)+// - /sessions -> JSON ids/delete_all, or query parameters without a bodyfunc (h *AgentHandler) DeleteAgentSession(c *gin.Context) {user, code, msg := GetUser(c)if code != common.CodeSuccess {@@ -1105,6 +1108,16 @@ func (h *AgentHandler) DeleteAgentSession(c *gin.Context) {}}}+ var body struct {+ IDs []string `json:"ids"`+ DeleteAll bool `json:"delete_all"`+ }+ if err := c.ShouldBindJSON(&body); err == nil {+ ids, deleteAll = body.IDs, body.DeleteAll+ } else if !errors.Is(err, io.EOF) {+ common.ErrorWithCode(c, common.CodeArgumentError, "Invalid request: "+err.Error())+ return+ }result, code, err := h.agentService.DeleteAgentSessions(ctx, user.ID, canvasID, ids, deleteAll)if err != nil {common.ErrorWithCode(c, code, err.Error())diff --git a/internal/handler/agent_test.go b/internal/handler/agent_test.goindex 1b25003ed6..7f88cfb8df 100644--- a/internal/handler/agent_test.go+++ b/internal/handler/agent_test.go@@ -21,6 +21,7 @@ import ("encoding/json""errors""fmt"+ "io""net/http""net/http/httptest""strings"@@ -58,6 +59,7 @@ func setupHandlerAgentsTestDB(t *testing.T) *gorm.DB {&entity.UserCanvasVersion{},&entity.UserTenant{},&entity.API4Conversation{},+ &entity.API4ConversationMessage{},); err != nil {t.Fatalf("failed to migrate: %v", err)}@@ -354,6 +356,70 @@ func TestCreateAgentUsesAuthenticatedUserID(t *testing.T) {}}+func TestCreateAgentSessionReturnsAgentBinding(t *testing.T) {+ c, w, db := setupGinContextWithUserAndDB(t, http.MethodPost, "/api/v1/agents/canvas-1/sessions")+ c.Params = gin.Params{{Key: "canvas_id", Value: "canvas-1"}}+ if err := db.Create(&entity.UserCanvas{ID: "canvas-1", UserID: "user-1", TenantID: sptr("user-1"), DSL: entity.JSONMap{}}).Error; err != nil {+ t.Fatal(err)+ }+ NewAgentHandler(t.Context(), service.NewAgentService(), nil).CreateAgentSession(c)+ var response struct {+ Code int+ Data map[string]any+ }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatal(err)+ }+ if response.Code != 0 || response.Data["agent_id"] != "canvas-1" {+ t.Fatalf("response: %s", w.Body.String())+ }+}++func TestDeleteAgentSessionsAcceptsBodyAndQuery(t *testing.T) {+ for _, tc := range []struct {+ name, query, body string+ remaining int64+ }{+ {"selected body", "", `{"ids":["first"]}`, 1},+ {"all body", "", `{"delete_all":true}`, 0},+ {"selected query", "?ids=first", "", 1},+ {"all query", "?delete_all=true", "", 0},+ {"empty body is safe", "", `{}`, 2},+ {"null ids are safe", "", `{"ids":null}`, 2},+ {"body takes precedence", "?delete_all=true", `{"ids":["first"]}`, 1},+ } {+ t.Run(tc.name, func(t *testing.T) {+ url := "/api/v1/agents/canvas-1/sessions" + tc.query+ c, w, db := setupGinContextWithUserAndDB(t, http.MethodDelete, url)+ c.Params = gin.Params{{Key: "canvas_id", Value: "canvas-1"}}+ c.Request.Body = io.NopCloser(strings.NewReader(tc.body))+ if err := db.Create(&entity.UserCanvas{ID: "canvas-1", UserID: "user-1", TenantID: sptr("user-1")}).Error; err != nil {+ t.Fatal(err)+ }+ for _, id := range []string{"first", "second"} {+ if err := db.Create(&entity.API4Conversation{ID: id, DialogID: "canvas-1", UserID: "user-1"}).Error; err != nil {+ t.Fatal(err)+ }+ }+ NewAgentHandler(t.Context(), service.NewAgentService(), nil).DeleteAgentSession(c)+ var response struct{ Code int }+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {+ t.Fatal(err)+ }+ if response.Code != 0 {+ t.Fatalf("response: %s", w.Body.String())+ }+ var remaining int64+ if err := db.Model(&entity.API4Conversation{}).Count(&remaining).Error; err != nil {+ t.Fatal(err)+ }+ if remaining != tc.remaining {+ t.Fatalf("remaining=%d, want %d; response: %s", remaining, tc.remaining, w.Body.String())+ }+ })+ }+}+func seedAgentCreationContext(t *testing.T, c *gin.Context, db *gorm.DB) {t.Helper()if err := db.AutoMigrate(&entity.Tenant{}); err != nil {diff --git a/internal/service/agent.go b/internal/service/agent.goindex 03c61c393f..0b17e5af18 100644--- a/internal/service/agent.go+++ b/internal/service/agent.go@@ -17,6 +17,7 @@package serviceimport (+ "cmp""context""encoding/json""errors"@@ -24,6 +25,7 @@ import ("maps""ragflow/internal/service/file""reflect"+ "slices""sort""strings""sync"@@ -749,8 +751,8 @@ func (s *AgentService) listAgentsGroupsOnly(ctx context.Context, userID, keyword}// mergeAgentsAndGroups combines agents and the caller's compilation template-// groups into a single list ordered by update_time, then pages in Go. This-// mirrors Python's merged /agents response. A stable sort retains the original+// groups into a single list ordered by the requested timestamp, then pages in Go.+// A stable sort retains the original// agent-before-group order when timestamps are equal.func (s *AgentService) mergeAgentsAndGroups(ctx context.Context, userID string, agentItems []*AgentItem, keywords string, terms []dao.OrderTerm, page, pageSize int) (*ListAgentsResponse, common.ErrorCode, error) {groups, err := s.compilationTemplateGroupDAO.ListSaved(ctx, dao.DB, userID, keywords, "", terms)@@ -758,11 +760,16 @@ func (s *AgentService) mergeAgentsAndGroups(ctx context.Context, userID string,return nil, common.CodeServerError, fmt.Errorf("failed to list compilation template groups: %w", err)}merged := make([]mergeCanvasItem, 0, len(agentItems)+len(groups))+ byCreation := len(terms) > 0 && terms[0].Column == "create_time"for _, item := range agentItems {item.Type = AgentItemTypeAgent+ timestamp := item.UpdateTime+ if byCreation {+ timestamp = item.CreateTime+ }merged = append(merged, mergeCanvasItem{item: item,- time: intValuePtr(item.UpdateTime),+ time: intValuePtr(timestamp),})}for _, g := range groups {@@ -770,19 +777,21 @@ func (s *AgentService) mergeAgentsAndGroups(ctx context.Context, userID string,if err != nil {return nil, common.CodeServerError, fmt.Errorf("failed to build group item: %w", err)}+ timestamp := g.UpdateTime+ if byCreation {+ timestamp = g.CreateTime+ }merged = append(merged, mergeCanvasItem{raw: raw,- time: intValuePtr(g.UpdateTime),+ time: intValuePtr(timestamp),})}- // The merge orders by update time whatever column was asked for, so it takes- // the direction from the first term the way the fallback clause does.descending := len(terms) > 0 && terms[0].Desc- sort.SliceStable(merged, func(i, j int) bool {+ slices.SortStableFunc(merged, func(a, b mergeCanvasItem) int {if descending {- return merged[i].time > merged[j].time+ return cmp.Compare(b.time, a.time)}- return merged[i].time < merged[j].time+ return cmp.Compare(a.time, b.time)})total := int64(len(merged))merged = slicePage(merged, page, pageSize)diff --git a/internal/service/agent_test.go b/internal/service/agent_test.goindex 77fd4e1064..99e08996de 100644--- a/internal/service/agent_test.go+++ b/internal/service/agent_test.go@@ -944,6 +944,39 @@ func createAgentSessionTestCanvas(t *testing.T, id, userID string) {}}+func TestMergedAgentsRespectRequestedTimestamp(t *testing.T) {+ setupAgentSessionServiceTest(t)+ items := []*AgentItem{+ {ID: "old", CreateTime: new(int64(1)), UpdateTime: new(int64(20))},+ {ID: "new", CreateTime: new(int64(2)), UpdateTime: new(int64(10))},+ }+ for _, tc := range []struct {+ name string+ terms []dao.OrderTerm+ first string+ }{+ {"created ascending", []dao.OrderTerm{{Column: "create_time"}}, "old"},+ {"created descending", []dao.OrderTerm{{Column: "create_time", Desc: true}}, "new"},+ {"updated ascending", []dao.OrderTerm{{Column: "update_time"}}, "new"},+ {"updated descending", []dao.OrderTerm{{Column: "update_time", Desc: true}}, "old"},+ {"default", nil, "new"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ resp, code, err := NewAgentService().mergeAgentsAndGroups(t.Context(), "user-1", items, "", tc.terms, 1, 1)+ if err != nil || code != common.CodeSuccess || resp.Total != 2 || len(resp.Canvas) != 1 {+ t.Fatalf("merge: response=%+v code=%v err=%v", resp, code, err)+ }+ var first AgentItem+ if err := json.Unmarshal(resp.Canvas[0], &first); err != nil {+ t.Fatal(err)+ }+ if first.ID != tc.first {+ t.Fatalf("first=%q, want %q", first.ID, tc.first)+ }+ })+ }+}+func createAgentSessionTestConversation(t *testing.T, id, agentID, userID string, updateTime int64) {t.Helper()updateDate := time.UnixMilli(updateTime)@@ -2462,7 +2495,7 @@ func TestListAgents_MergesCompilationTemplateGroups(t *testing.T) {if err := dao.DB.Create(&entity.UserCanvas{ID: "canvas-1", UserID: "user-1", Title: sptr("Agent canvas"),CanvasCategory: "agent_canvas",- BaseModel: entity.BaseModel{UpdateTime: &canvasUpdate},+ BaseModel: entity.BaseModel{CreateTime: &canvasUpdate, UpdateTime: &canvasUpdate},}).Error; err != nil {t.Fatalf("failed to seed agent: %v", err)}diff --git a/sdk/python/ragflow_sdk/modules/agent.py b/sdk/python/ragflow_sdk/modules/agent.pyindex 41ad34989a..71185a1627 100644--- a/sdk/python/ragflow_sdk/modules/agent.py+++ b/sdk/python/ragflow_sdk/modules/agent.py@@ -1,5 +1,5 @@#-# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.+# 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.@@ -30,7 +30,7 @@ class Agent(Base):class Dsl(Base):def __init__(self, rag, res_dict):self.answer = []- self.components = {"begin": {"downstream": ["Answer:China"], "obj": {"component_name": "Begin", "params": {}}, "upstream": []}}+ self.components = {"begin": {"downstream": [], "obj": {"component_name": "Begin", "params": {}}, "upstream": []}}self.graph = {"edges": [],"nodes": [{"data": {"label": "Begin", "name": "begin"}, "id": "begin", "position": {"x": 50, "y": 200}, "sourcePosition": "left", "targetPosition": "right", "type": "beginNode"}],diff --git a/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_integration.py b/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_integration.pyindex 6f79487131..ef890c6eb2 100644--- a/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_integration.py+++ b/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_integration.py@@ -120,7 +120,6 @@ def test_agent_listing_pages(live_client, dsl):assert [row.update_time for row in rows] == sorted(row.update_time for row in rows)[email protected](reason="Go AgentService.mergeAgentsAndGroups sorts only update_time even when SDK orderby=create_time; remove when the requested column is respected")def test_agent_creation_order_after_update(live_client, dsl):first = create_agent(live_client, dsl)time.sleep(0.02)@@ -161,7 +160,6 @@ def test_agent_session_creation_and_listing(live_client, dsl):@pytest.mark.parametrize("delete_all", [False, True])[email protected](reason="Go AgentHandler.DeleteAgentSession ignores documented JSON ids/delete_all sent by Agent.delete_sessions; it reads query parameters and silently deletes nothing")def test_agent_session_deletion_persists(live_client, dsl, delete_all):agent = create_agent(live_client, dsl)first = agent.create_session(name="delete")@@ -174,7 +172,6 @@ def test_agent_session_deletion_persists(live_client, dsl, delete_all):assert {session.id for session in agent.list_sessions()} == expected[email protected](reason="Go CreateAgentSession serializes dialog_id instead of documented agent_id; SDK Session.__init__ cannot bind agent sessions for ask(); remove when response uses agent_id")def test_created_agent_session_binding(live_client, dsl):agent = create_agent(live_client, dsl)session = agent.create_session()diff --git a/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_unit.py b/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_unit.pyindex 1b122536fe..6682facb15 100644--- a/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_unit.py+++ b/test/testcases/test_sdk_api/test_agent_management/test_agent_crud_unit.py@@ -132,7 +132,6 @@ def test_explicit_dsl_round_trip(client, dsl):assert result["graph"] == dsl["graph"][email protected](reason="SDK Agent.Dsl.__init__ hardcodes missing Answer:China downstream; remove when the default graph has no dangling references")def test_default_dsl_references_existing_components(client):dsl = Agent.Dsl(client, {}).to_json()for component in dsl["components"].values():