feat(agent): add question suggestions with after-answer follow-ups

Enable agents to configure starter prompts and async follow-up questions after completed answers, with durable caching, analytics events, and chat/embed UI integration.
This commit is contained in:
wizardchen
2026-07-14 11:06:13 +08:00
committed by lyingbug
parent a6c85dad28
commit 087fcc9fe7
50 changed files with 3781 additions and 179 deletions
+10
View File
@@ -93,6 +93,11 @@ func (h *CustomAgentHandler) CreateAgent(c *gin.Context) {
Avatar: req.Avatar,
Config: req.Config,
}
agent.EnsureDefaults()
if err := agent.Config.QuestionSuggestions.Validate(); err != nil {
c.Error(errors.NewBadRequestError(err.Error()))
return
}
logger.Infof(ctx, "Creating custom agent, name: %s, agent_mode: %s",
secutils.SanitizeForLog(req.Name), req.Config.AgentMode)
@@ -332,6 +337,11 @@ func (h *CustomAgentHandler) UpdateAgent(c *gin.Context) {
Avatar: req.Avatar,
Config: req.Config,
}
agent.EnsureDefaults()
if err := agent.Config.QuestionSuggestions.Validate(); err != nil {
c.Error(errors.NewBadRequestError(err.Error()))
return
}
logger.Infof(ctx, "Updating custom agent, ID: %s, name: %s",
secutils.SanitizeForLog(id), secutils.SanitizeForLog(req.Name))
+42
View File
@@ -30,6 +30,7 @@ type EmbedChannelHandler struct {
sessionService interfaces.SessionService
sessionHandler *session.Handler
messageHandler *MessageHandler
suggestionHandler *MessageSuggestionHandler
mcpOAuthHandler *MCPOAuthHandler
mcpServiceHandler *MCPServiceHandler
redis *redis.Client
@@ -40,6 +41,7 @@ func NewEmbedChannelHandler(
sessionService interfaces.SessionService,
sessionHandler *session.Handler,
messageHandler *MessageHandler,
suggestionHandler *MessageSuggestionHandler,
mcpOAuthHandler *MCPOAuthHandler,
mcpServiceHandler *MCPServiceHandler,
redisClient *redis.Client,
@@ -49,6 +51,7 @@ func NewEmbedChannelHandler(
sessionService: sessionService,
sessionHandler: sessionHandler,
messageHandler: messageHandler,
suggestionHandler: suggestionHandler,
mcpOAuthHandler: mcpOAuthHandler,
mcpServiceHandler: mcpServiceHandler,
redis: redisClient,
@@ -462,6 +465,45 @@ func (h *EmbedChannelHandler) EmbedStopSession(c *gin.Context) {
h.sessionHandler.StopSession(c)
}
func (h *EmbedChannelHandler) EmbedEnsureMessageSuggestions(c *gin.Context) {
if err := h.ensureEmbedSession(c); err != nil {
return
}
ch, _ := middleware.EmbedChannelFromContext(c.Request.Context())
if ch == nil || !ch.ShowSuggestedQuestions || h.suggestionHandler == nil {
c.JSON(http.StatusOK, gin.H{"success": true, "data": gin.H{
"status": "suppressed", "suppression_reason": "channel_disabled", "questions": []any{},
}})
return
}
h.suggestionHandler.Ensure(c)
}
func (h *EmbedChannelHandler) EmbedGetMessageSuggestions(c *gin.Context) {
if err := h.ensureEmbedSession(c); err != nil {
return
}
ch, _ := middleware.EmbedChannelFromContext(c.Request.Context())
if ch == nil || !ch.ShowSuggestedQuestions || h.suggestionHandler == nil {
c.JSON(http.StatusOK, gin.H{"success": true, "data": gin.H{
"status": "suppressed", "suppression_reason": "channel_disabled", "questions": []any{},
}})
return
}
h.suggestionHandler.Get(c)
}
func (h *EmbedChannelHandler) EmbedRecordSuggestionEvent(c *gin.Context) {
if err := h.ensureEmbedSession(c); err != nil {
return
}
if h.suggestionHandler == nil {
c.JSON(http.StatusServiceUnavailable, gin.H{"error": "suggestion service unavailable"})
return
}
h.suggestionHandler.RecordEvent(c)
}
func (h *EmbedChannelHandler) EmbedResolveMCPOAuth(c *gin.Context) {
if err := h.ensureEmbedSession(c); err != nil {
return
+150
View File
@@ -0,0 +1,150 @@
package handler
import (
"errors"
"net/http"
"strings"
apperrors "github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types/interfaces"
secutils "github.com/Tencent/WeKnora/internal/utils"
"github.com/gin-gonic/gin"
"gorm.io/gorm"
)
type MessageSuggestionHandler struct {
service interfaces.MessageSuggestionService
}
func NewMessageSuggestionHandler(service interfaces.MessageSuggestionService) *MessageSuggestionHandler {
return &MessageSuggestionHandler{service: service}
}
type EnsureMessageSuggestionsRequest struct {
Regenerate bool `json:"regenerate"`
}
type SuggestionEventRequest struct {
SuggestionSetID string `json:"suggestion_set_id" binding:"required"`
QuestionID string `json:"question_id"`
EventType string `json:"event_type" binding:"required"`
}
// Ensure godoc
// @Summary 确保生成回答后推荐问题
// @Description 对已完成的助手消息异步生成或重新生成推荐问题;相同配置快照会复用持久化结果
// @Tags 会话
// @Accept json
// @Produce json
// @Param session_id path string true "会话 ID"
// @Param message_id path string true "助手消息 ID"
// @Param request body EnsureMessageSuggestionsRequest false "生成选项"
// @Success 200 {object} map[string]interface{}
// @Success 202 {object} map[string]interface{}
// @Security Bearer
// @Security ApiKeyAuth
// @Router /sessions/{session_id}/messages/{message_id}/suggestions [post]
func (h *MessageSuggestionHandler) Ensure(c *gin.Context) {
var request EnsureMessageSuggestionsRequest
if c.Request.ContentLength > 0 {
if err := c.ShouldBindJSON(&request); err != nil {
c.Error(apperrors.NewBadRequestError("invalid request body"))
return
}
}
set, err := h.service.EnsureFollowUps(
c.Request.Context(),
secutils.SanitizeForLog(c.Param("session_id")),
secutils.SanitizeForLog(c.Param("message_id")),
request.Regenerate,
)
if err != nil {
h.writeError(c, err)
return
}
status := http.StatusOK
if set != nil && set.Status == "generating" {
status = http.StatusAccepted
}
c.JSON(status, gin.H{"success": true, "data": set})
}
// Get godoc
// @Summary 获取回答后推荐问题
// @Tags 会话
// @Produce json
// @Param session_id path string true "会话 ID"
// @Param message_id path string true "助手消息 ID"
// @Success 200 {object} map[string]interface{}
// @Security Bearer
// @Security ApiKeyAuth
// @Router /sessions/{session_id}/messages/{message_id}/suggestions [get]
func (h *MessageSuggestionHandler) Get(c *gin.Context) {
set, err := h.service.GetFollowUps(
c.Request.Context(),
messageSuggestionSessionID(c),
secutils.SanitizeForLog(c.Param("message_id")),
)
if err != nil {
h.writeError(c, err)
return
}
c.JSON(http.StatusOK, gin.H{"success": true, "data": set})
}
func messageSuggestionSessionID(c *gin.Context) string {
sessionID := c.Param("session_id")
if sessionID == "" {
sessionID = c.Param("id")
}
return secutils.SanitizeForLog(sessionID)
}
// RecordEvent godoc
// @Summary 上报推荐问题事件
// @Description 记录曝光、点击或关闭事件
// @Tags 会话
// @Accept json
// @Param session_id path string true "会话 ID"
// @Param request body SuggestionEventRequest true "事件"
// @Success 204
// @Security Bearer
// @Security ApiKeyAuth
// @Router /sessions/{session_id}/suggestion-events [post]
func (h *MessageSuggestionHandler) RecordEvent(c *gin.Context) {
var request SuggestionEventRequest
if err := c.ShouldBindJSON(&request); err != nil {
c.Error(apperrors.NewBadRequestError("invalid request body"))
return
}
err := h.service.RecordEvent(
c.Request.Context(),
secutils.SanitizeForLog(c.Param("session_id")),
strings.TrimSpace(request.SuggestionSetID),
strings.TrimSpace(request.QuestionID),
strings.TrimSpace(request.EventType),
)
if err != nil {
h.writeError(c, err)
return
}
c.Status(http.StatusNoContent)
}
func (h *MessageSuggestionHandler) writeError(c *gin.Context, err error) {
switch {
case errors.Is(err, gorm.ErrRecordNotFound):
c.Error(apperrors.NewNotFoundError("suggestions not found"))
case strings.Contains(err.Error(), "completed assistant"):
c.Error(apperrors.NewBadRequestError(err.Error()))
case strings.Contains(err.Error(), "invalid suggestion event"),
strings.Contains(err.Error(), "requires question_id"),
strings.Contains(err.Error(), "does not belong"),
strings.Contains(err.Error(), "not allowed"):
c.Error(apperrors.NewBadRequestError(err.Error()))
default:
logger.Error(c.Request.Context(), "message suggestion operation failed", err)
c.Error(apperrors.NewInternalServerError("message suggestion operation failed"))
}
}
+4 -1
View File
@@ -16,7 +16,8 @@ import (
// Handler handles all HTTP requests related to conversation sessions
type Handler struct {
messageService interfaces.MessageService // Service for managing messages
messageService interfaces.MessageService // Service for managing messages
suggestionService interfaces.MessageSuggestionService
sessionService interfaces.SessionService // Service for managing sessions
streamManager interfaces.StreamManager // Manager for handling streaming responses
config *config.Config // Application configuration
@@ -35,6 +36,7 @@ type Handler struct {
func NewHandler(
sessionService interfaces.SessionService,
messageService interfaces.MessageService,
suggestionService interfaces.MessageSuggestionService,
streamManager interfaces.StreamManager,
config *config.Config,
knowledgebaseService interfaces.KnowledgeBaseService,
@@ -51,6 +53,7 @@ func NewHandler(
return &Handler{
sessionService: sessionService,
messageService: messageService,
suggestionService: suggestionService,
streamManager: streamManager,
config: config,
knowledgebaseService: knowledgebaseService,
+12 -11
View File
@@ -277,18 +277,19 @@ func createAgentQueryEvent(sessionID, assistantMessageID string) interfaces.Stre
}
// createUserMessage creates a user message and returns the created message.
func (h *Handler) createUserMessage(ctx context.Context, sessionID, query, requestID string, mentionedItems types.MentionedItems, images types.MessageImages, attachments types.MessageAttachments, channel string) (*types.Message, error) {
func (h *Handler) createUserMessage(ctx context.Context, sessionID, query, requestID string, mentionedItems types.MentionedItems, images types.MessageImages, attachments types.MessageAttachments, channel string, attribution *types.SuggestionAttribution) (*types.Message, error) {
return h.messageService.CreateMessage(ctx, &types.Message{
SessionID: sessionID,
Role: "user",
Content: query,
RequestID: requestID,
CreatedAt: time.Now(),
IsCompleted: true,
MentionedItems: mentionedItems,
Images: images,
Attachments: attachments,
Channel: channel,
SessionID: sessionID,
Role: "user",
Content: query,
RequestID: requestID,
CreatedAt: time.Now(),
IsCompleted: true,
MentionedItems: mentionedItems,
Images: images,
Attachments: attachments,
Channel: channel,
ExecutionContext: types.MessageExecutionContext{SuggestionAttribution: attribution},
})
}
+149 -46
View File
@@ -2,6 +2,7 @@ package session
import (
"context"
"crypto/sha256"
"encoding/json"
"fmt"
"net/http"
@@ -20,30 +21,31 @@ import (
// qaRequestContext holds all the common data needed for QA requests
type qaRequestContext struct {
ctx context.Context
c *gin.Context
sessionID string
requestID string
receivedAt time.Time // Wall-clock time the handler started processing the request
query string
session *types.Session
customAgent *types.CustomAgent
assistantMessage *types.Message
knowledgeBaseIDs []string
knowledgeIDs []string
tagScopes []types.TagScope
tagIDs []string
mcpServiceIDs []string
skillNames []string
summaryModelID string
webSearchEnabled bool
enableMemory bool // Whether memory feature is enabled
mentionedItems types.MentionedItems
effectiveTenantID uint64 // when using shared agent, tenant ID for model/KB/MCP resolution; 0 = use context tenant
images []ImageAttachment // Uploaded images with analysis text
userMessageID string // Created user message ID (populated after createUserMessage)
channel string // Source channel: "web", "api", "im", etc.
attachments types.MessageAttachments // Processed file attachments
ctx context.Context
c *gin.Context
sessionID string
requestID string
receivedAt time.Time // Wall-clock time the handler started processing the request
query string
session *types.Session
customAgent *types.CustomAgent
assistantMessage *types.Message
knowledgeBaseIDs []string
knowledgeIDs []string
tagScopes []types.TagScope
tagIDs []string
mcpServiceIDs []string
skillNames []string
summaryModelID string
webSearchEnabled bool
enableMemory bool // Whether memory feature is enabled
mentionedItems types.MentionedItems
effectiveTenantID uint64 // when using shared agent, tenant ID for model/KB/MCP resolution; 0 = use context tenant
images []ImageAttachment // Uploaded images with analysis text
userMessageID string // Created user message ID (populated after createUserMessage)
channel string // Source channel: "web", "api", "im", etc.
attachments types.MessageAttachments // Processed file attachments
suggestionAttribution *types.SuggestionAttribution
// Snapshot of the request fields needed to persist the input-bar state
// for session restoration. Kept verbatim from the request so we record
@@ -102,6 +104,11 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
logger.Error(ctx, "Query content is empty")
return nil, nil, errors.NewBadRequestError("Query content cannot be empty")
}
if h.suggestionService != nil && request.SuggestionAttribution != nil {
if err := h.suggestionService.ValidateAttribution(ctx, sessionID, request.Query, request.SuggestionAttribution); err != nil {
return nil, nil, errors.NewBadRequestError("invalid suggestion attribution")
}
}
// SSRF protection: strip client-supplied URL/Caption fields from image attachments.
// The URL field must only be populated server-side by saveImageAttachments; an
@@ -259,6 +266,18 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
tagIDs := dedupRequestStrings(append(request.TagIDs, mentionedIDsByType(request.MentionedItems, "tag")...))
mcpServiceIDs := dedupRequestStrings(append(request.MCPServiceIDs, mentionedIDsByType(request.MentionedItems, "mcp")...))
skillNames := dedupRequestStrings(append(request.SkillNames, mentionedIDsByType(request.MentionedItems, "skill")...))
executionContext, agentID, agentTenantID, modelID := buildMessageExecutionContext(
ctx,
customAgent,
effectiveTenantID,
request.SummaryModelID,
secutils.SanitizeForLogArray(kbIDs),
secutils.SanitizeForLogArray(knowledgeIDs),
secutils.SanitizeForLogArray(tagIDs),
secutils.SanitizeForLogArray(mcpServiceIDs),
secutils.SanitizeForLogArray(skillNames),
request.WebSearchEnabled,
)
// Build request context
reqCtx := &qaRequestContext{
@@ -271,33 +290,108 @@ func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestCo
session: session,
customAgent: customAgent,
assistantMessage: &types.Message{
SessionID: sessionID,
Role: "assistant",
RequestID: c.GetString(types.RequestIDContextKey.String()),
IsCompleted: false,
Channel: request.Channel,
SessionID: sessionID,
Role: "assistant",
RequestID: c.GetString(types.RequestIDContextKey.String()),
IsCompleted: false,
Channel: request.Channel,
AgentID: agentID,
AgentTenantID: agentTenantID,
ModelID: modelID,
ExecutionContext: executionContext,
},
knowledgeBaseIDs: secutils.SanitizeForLogArray(kbIDs),
knowledgeIDs: secutils.SanitizeForLogArray(knowledgeIDs),
tagScopes: tagScopes,
tagIDs: secutils.SanitizeForLogArray(tagIDs),
mcpServiceIDs: secutils.SanitizeForLogArray(mcpServiceIDs),
skillNames: secutils.SanitizeForLogArray(skillNames),
summaryModelID: secutils.SanitizeForLog(request.SummaryModelID),
webSearchEnabled: request.WebSearchEnabled,
enableMemory: enableMemory,
mentionedItems: convertMentionedItems(request.MentionedItems),
effectiveTenantID: effectiveTenantID,
images: request.Images,
channel: request.Channel,
attachments: processedAttachments,
reqAgentEnabled: request.AgentEnabled,
reqAgentID: request.AgentID,
knowledgeBaseIDs: secutils.SanitizeForLogArray(kbIDs),
knowledgeIDs: secutils.SanitizeForLogArray(knowledgeIDs),
tagScopes: tagScopes,
tagIDs: secutils.SanitizeForLogArray(tagIDs),
mcpServiceIDs: secutils.SanitizeForLogArray(mcpServiceIDs),
skillNames: secutils.SanitizeForLogArray(skillNames),
summaryModelID: secutils.SanitizeForLog(request.SummaryModelID),
webSearchEnabled: request.WebSearchEnabled,
enableMemory: enableMemory,
mentionedItems: convertMentionedItems(request.MentionedItems),
effectiveTenantID: effectiveTenantID,
images: request.Images,
channel: request.Channel,
attachments: processedAttachments,
suggestionAttribution: request.SuggestionAttribution,
reqAgentEnabled: request.AgentEnabled,
reqAgentID: request.AgentID,
}
return reqCtx, &request, nil
}
func buildMessageExecutionContext(
ctx context.Context,
agent *types.CustomAgent,
effectiveTenantID uint64,
modelOverride string,
knowledgeBaseIDs []string,
knowledgeIDs []string,
tagIDs []string,
mcpServiceIDs []string,
skillNames []string,
webSearchEnabled bool,
) (types.MessageExecutionContext, string, uint64, string) {
locale, ok := types.LanguageFromContext(ctx)
if !ok {
locale = types.DefaultLanguage()
}
snapshot := types.MessageExecutionContext{
KnowledgeBaseIDs: knowledgeBaseIDs,
KnowledgeIDs: knowledgeIDs,
TagIDs: tagIDs,
MCPServiceIDs: mcpServiceIDs,
SkillNames: skillNames,
WebSearchEnabled: webSearchEnabled,
Locale: locale,
}
if agent == nil {
return snapshot, "", effectiveTenantID, modelOverride
}
modelID := modelOverride
if modelID == "" {
modelID = agent.Config.ModelID
}
agentTenantID := effectiveTenantID
if agentTenantID == 0 {
agentTenantID = agent.TenantID
}
// Marshal/unmarshal gives the snapshot independent backing slices, so a
// later agent edit cannot mutate an in-flight message context.
if agent.Config.QuestionSuggestions != nil {
if encoded, err := json.Marshal(agent.Config.QuestionSuggestions); err == nil {
var suggestions types.QuestionSuggestionConfig
if json.Unmarshal(encoded, &suggestions) == nil {
snapshot.QuestionSuggestions = &suggestions
}
}
}
hashInput := struct {
QuestionSuggestions *types.QuestionSuggestionConfig `json:"question_suggestions,omitempty"`
KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"`
KnowledgeIDs []string `json:"knowledge_ids,omitempty"`
TagIDs []string `json:"tag_ids,omitempty"`
ModelID string `json:"model_id,omitempty"`
}{
QuestionSuggestions: snapshot.QuestionSuggestions,
KnowledgeBaseIDs: knowledgeBaseIDs,
KnowledgeIDs: knowledgeIDs,
TagIDs: tagIDs,
ModelID: modelID,
}
if encoded, err := json.Marshal(hashInput); err == nil {
hash := sha256.Sum256(encoded)
snapshot.AgentConfigHash = fmt.Sprintf("%x", hash[:])
}
return snapshot, agent.ID, agentTenantID, modelID
}
// resolveEnableMemory decides whether the memory pipeline runs for this
// request. See the call-site comment in parseQARequest for the resolution
// order. Lookup errors are logged but never propagate — a failure to read
@@ -688,7 +782,7 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle
}
// Create user message
userMsg, err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images), reqCtx.attachments, reqCtx.channel)
userMsg, err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images), reqCtx.attachments, reqCtx.channel, reqCtx.suggestionAttribution)
if err != nil {
reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
return
@@ -964,4 +1058,13 @@ func (h *Handler) completeAssistantMessage(ctx context.Context, assistantMessage
// Use WithoutCancel so the goroutine survives after the HTTP request context is done.
bgCtx := context.WithoutCancel(ctx)
go h.messageService.IndexMessageToKB(bgCtx, userQuery, assistantMessage.Content, assistantMessage.ID, assistantMessage.SessionID)
if userQuery != "" && h.suggestionService != nil {
go func() {
if _, err := h.suggestionService.EnsureFollowUps(
bgCtx, assistantMessage.SessionID, assistantMessage.ID, false,
); err != nil {
logger.Warnf(bgCtx, "follow-up suggestion generation failed for message %s: %v", assistantMessage.ID, err)
}
}()
}
}
+5 -4
View File
@@ -65,10 +65,11 @@ type CreateKnowledgeQARequest struct {
// user's personal memory setting doesn't leak into a widget
// context; older clients that still send a literal bool also
// land here (back-compat).
EnableMemory *bool `json:"enable_memory,omitempty"`
Images []ImageAttachment `json:"images"` // Attached images for multimodal chat
AttachmentUploads []AttachmentUpload `json:"attachment_uploads,omitempty"` // Attached files (documents, audio, etc.)
Channel string `json:"channel"` // Source channel: "web", "api", "im", etc.
EnableMemory *bool `json:"enable_memory,omitempty"`
Images []ImageAttachment `json:"images"` // Attached images for multimodal chat
AttachmentUploads []AttachmentUpload `json:"attachment_uploads,omitempty"` // Attached files (documents, audio, etc.)
Channel string `json:"channel"` // Source channel: "web", "api", "im", etc.
SuggestionAttribution *types.SuggestionAttribution `json:"suggestion_attribution,omitempty"`
}
// AttachmentUpload represents a file attachment upload from the client