Skip to content

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

fix(sdk-agent): restore agent API contracts (#21731)

Sbaaoui Idrissa749eb44185e
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 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 body
func (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.go
index 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.go
index 03c61c393f..0b17e5af18 100644
--- a/internal/service/agent.go
+++ b/internal/service/agent.go
@@ -17,6 +17,7 @@
package service
import (
+ "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.go
index 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.py
index 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.py
index 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.py
index 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():