feat(agent): enforce model readiness and polish selector UX

Block chat when agents lack an explicit chat or rerank model, guide users
through the selector and editor with field highlight, and align session QA
checks with the same readiness rules on backend and frontend.
This commit is contained in:
wizardchen
2026-06-25 21:02:14 +08:00
committed by lyingbug
parent 1e16834d27
commit 9ca4e1f23a
16 changed files with 1247 additions and 673 deletions
@@ -0,0 +1,68 @@
package service
import (
"testing"
"github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
)
func TestAgentRequiresRerankModel(t *testing.T) {
tests := []struct {
name string
agent *types.CustomAgent
want bool
}{
{
name: "knowledge search with all knowledge bases",
agent: &types.CustomAgent{Config: types.CustomAgentConfig{
KBSelectionMode: "all",
AllowedTools: []string{tools.ToolKnowledgeSearch},
}},
want: true,
},
{
name: "knowledge search with selected knowledge bases",
agent: &types.CustomAgent{Config: types.CustomAgentConfig{
KBSelectionMode: "selected",
AllowedTools: []string{tools.ToolKnowledgeSearch},
}},
want: true,
},
{
name: "knowledge search with knowledge bases disabled",
agent: &types.CustomAgent{Config: types.CustomAgentConfig{
KBSelectionMode: "none",
AllowedTools: []string{tools.ToolKnowledgeSearch},
}},
want: false,
},
{
name: "default tools with knowledge bases disabled",
agent: &types.CustomAgent{Config: types.CustomAgentConfig{
KBSelectionMode: "none",
}},
want: false,
},
{
name: "wiki tools do not use reranker",
agent: &types.CustomAgent{Config: types.CustomAgentConfig{
KBSelectionMode: "all",
AllowedTools: []string{"wiki_search", "wiki_read_page"},
}},
want: false,
},
{
name: "nil agent",
agent: nil,
want: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
assert.Equal(t, tt.want, agentRequiresRerankModel(tt.agent))
})
}
}
+10 -3
View File
@@ -23,9 +23,13 @@ var (
ErrAgentNotConfigured = errors.New("agent is not fully configured (missing required chat model, or rerank model when the knowledge_search tool is enabled)")
)
// agentRequiresRerankModel returns true when the agent's configured tools
// will actually invoke the reranker at runtime. This mirrors the runtime
// check in session_agent_qa.go: only `knowledge_search` uses the reranker.
// agentRequiresRerankModel returns true when the agent's configured scope and
// tools will actually invoke the reranker at runtime. An agent whose knowledge
// base scope is explicitly disabled cannot run knowledge_search, so it does not
// need a rerank model even if that tool remains in AllowedTools.
//
// This mirrors the runtime check in session_agent_qa.go: only
// `knowledge_search` with an enabled knowledge-base scope uses the reranker.
// Wiki-first agents (wiki_search / wiki_read_page / …) never call it and
// therefore don't need a rerank model configured, even when knowledge bases
// are attached.
@@ -37,6 +41,9 @@ func agentRequiresRerankModel(agent *types.CustomAgent) bool {
if agent == nil {
return false
}
if agent.Config.KBSelectionMode == "none" {
return false
}
allowed := agent.Config.AllowedTools
if len(allowed) == 0 {
allowed = tools.DefaultAllowedTools()
@@ -89,17 +89,11 @@ func (s *sessionService) AgentQA(
return fmt.Errorf("failed to get chat model: %w", err)
}
// Get rerank model from custom agent config (only required when knowledge_search is allowed)
// Get rerank model from custom agent config only when knowledge_search can
// actually run. A disabled KB scope makes all KB tools ineffective, so it
// must not force users to configure an otherwise-unused rerank model.
var rerankModel rerank.Reranker
hasKnowledgeSearchTool := false
for _, tool := range agentConfig.AllowedTools {
if tool == tools.ToolKnowledgeSearch {
hasKnowledgeSearchTool = true
break
}
}
if hasKnowledgeSearchTool {
if agentRequiresRerankModel(req.CustomAgent) {
// Rerank model is resolved purely from the agent config now.
// We used to fall back to ConversationConfig.RerankModelID at
// the tenant level, but that path encouraged "leave rerank
@@ -121,7 +115,7 @@ func (s *sessionService) AgentQA(
return fmt.Errorf("failed to get rerank model: %w", err)
}
} else {
logger.Infof(ctx, "knowledge_search tool not enabled, skipping rerank model initialization")
logger.Infof(ctx, "knowledge_search is unavailable for the effective agent scope, skipping rerank model initialization")
}
// Load multi-turn history directly from DB (the single source of truth).
@@ -48,15 +48,16 @@ func (m *captureChatModel) GetModelName() string { return "capture" }
func (m *captureChatModel) GetModelID() string { return "capture" }
type stubModelService struct {
chatModel chat.Chat
chatModel chat.Chat
modelsByID map[string]*types.Model
}
func (s *stubModelService) CreateModel(context.Context, *types.Model) error {
return nil
}
func (s *stubModelService) GetModelByID(context.Context, string) (*types.Model, error) {
return nil, nil
func (s *stubModelService) GetModelByID(_ context.Context, id string) (*types.Model, error) {
return s.modelsByID[id], nil
}
func (s *stubModelService) ListModels(context.Context) ([]*types.Model, error) {
@@ -0,0 +1,85 @@
package service
import (
"context"
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestResolveChatModelIDRequiresConfiguredAgentModel(t *testing.T) {
svc := &sessionService{
modelService: &stubModelService{
modelsByID: map[string]*types.Model{
"builtin-chat": {
ID: "builtin-chat",
Type: types.ModelTypeKnowledgeQA,
},
},
},
}
req := &types.QARequest{
Session: &types.Session{},
CustomAgent: &types.CustomAgent{
ID: "agent-1",
},
// Even a valid request-level model must not hide incomplete agent config.
SummaryModelID: "builtin-chat",
}
modelID, err := svc.resolveChatModelID(context.Background(), req, nil, nil)
require.Error(t, err)
assert.Empty(t, modelID)
assert.Contains(t, err.Error(), "model_id")
}
func TestResolveChatModelIDRejectsUnavailableConfiguredAgentModel(t *testing.T) {
svc := &sessionService{
modelService: &stubModelService{modelsByID: map[string]*types.Model{}},
}
req := &types.QARequest{
Session: &types.Session{},
CustomAgent: &types.CustomAgent{
ID: "agent-1",
Config: types.CustomAgentConfig{
ModelID: "deleted-model",
},
},
}
modelID, err := svc.resolveChatModelID(context.Background(), req, nil, nil)
require.Error(t, err)
assert.Empty(t, modelID)
assert.Contains(t, err.Error(), "unavailable")
}
func TestResolveChatModelIDUsesValidConfiguredAgentModel(t *testing.T) {
svc := &sessionService{
modelService: &stubModelService{
modelsByID: map[string]*types.Model{
"agent-chat": {
ID: "agent-chat",
Type: types.ModelTypeKnowledgeQA,
},
},
},
}
req := &types.QARequest{
Session: &types.Session{},
CustomAgent: &types.CustomAgent{
ID: "agent-1",
Config: types.CustomAgentConfig{
ModelID: "agent-chat",
},
},
}
modelID, err := svc.resolveChatModelID(context.Background(), req, nil, nil)
require.NoError(t, err)
assert.Equal(t, "agent-chat", modelID)
}
@@ -2,6 +2,7 @@ package service
import (
"context"
"fmt"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
@@ -48,10 +49,13 @@ func (s *sessionService) resolveKnowledgeBases(
}
// resolveChatModelID resolves the effective chat model ID for a QA request.
// Priority:
// 1. Request's SummaryModelID (explicit override, validated)
// 2. Custom agent's ModelID
// 3. KB / session / system default (via selectChatModelID)
//
// When an agent is selected, its model configuration must be complete and
// valid. A request-level override may choose another valid model for this
// request, but it must not make an unconfigured or stale agent appear usable.
//
// Without an agent, the legacy KB / session / system fallback remains
// available for non-agent callers.
func (s *sessionService) resolveChatModelID(
ctx context.Context,
req *types.QARequest,
@@ -62,6 +66,17 @@ func (s *sessionService) resolveChatModelID(
customAgent := req.CustomAgent
session := req.Session
if customAgent != nil {
configuredModelID := customAgent.Config.ModelID
if configuredModelID == "" {
return "", fmt.Errorf("chat model is not configured: please set model_id on agent %s", customAgent.ID)
}
model, err := s.modelService.GetModelByID(ctx, configuredModelID)
if err != nil || model == nil || model.Type != types.ModelTypeKnowledgeQA {
return "", fmt.Errorf("configured chat model %s is unavailable for agent %s", configuredModelID, customAgent.ID)
}
}
if summaryModelID != "" {
if model, err := s.modelService.GetModelByID(ctx, summaryModelID); err == nil && model != nil {
logger.Infof(ctx, "Using request's summary model override: %s", summaryModelID)