feat(agent): add per-agent citation output toggle
Move citation protocol injection to the system layer so custom prompts no longer own citation syntax. Agents can disable inline citations while source aliases still encode and decode tool arguments correctly.
This commit is contained in:
@@ -11,18 +11,20 @@ import (
|
||||
|
||||
// prepareMessagesWithReferences replaces the pipeline's positional context IDs
|
||||
// with request-local chunk references in the copy sent to the model. Persisted
|
||||
// rendered_content and the public citation contract remain unchanged.
|
||||
// rendered_content remains unchanged; public citations are expanded only when
|
||||
// the request's agent setting enables them.
|
||||
func prepareMessagesWithReferences(
|
||||
ctx context.Context,
|
||||
chatManage *types.ChatManage,
|
||||
) ([]chat.Message, *llmreference.Registry) {
|
||||
refs := llmreference.NewRegistry()
|
||||
citationsEnabled := chatManage == nil || chatManage.CitationsEnabled()
|
||||
refs := llmreference.NewRegistry(citationsEnabled)
|
||||
if chatManage == nil {
|
||||
return nil, refs
|
||||
}
|
||||
messages := prepareMessagesWithHistory(chatManage)
|
||||
if len(messages) > 0 {
|
||||
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt
|
||||
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt(citationsEnabled)
|
||||
}
|
||||
if len(chatManage.MergeResult) == 0 || len(messages) == 0 {
|
||||
return messages, refs
|
||||
|
||||
@@ -30,7 +30,7 @@ func TestPrepareMessagesWithReferencesUsesChunkCentricContext(t *testing.T) {
|
||||
|
||||
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
|
||||
require.Len(t, messages, 2)
|
||||
require.Contains(t, messages[0].Content, "Source reference protocol")
|
||||
require.Contains(t, messages[0].Content, "Source handling protocol")
|
||||
require.Contains(t, messages[1].Content, `<document id="d1" kb="b1" title="Doc">`)
|
||||
require.Contains(t, messages[1].Content, `<chunk id="c1" index="1" view="full">`)
|
||||
require.Contains(t, messages[1].Content, `<chunk id="c2" index="2" view="full">`)
|
||||
@@ -110,7 +110,30 @@ func TestPrepareMessagesWithReferencesCompactsHistoryWithoutCurrentRetrieval(t *
|
||||
|
||||
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
|
||||
messages = refs.EncodeMessages(messages)
|
||||
require.Contains(t, messages[0].Content, "Source reference protocol")
|
||||
require.Contains(t, messages[0].Content, "Source handling protocol")
|
||||
require.Contains(t, messages[2].Content, `<ref id="w1"/>`)
|
||||
require.NotContains(t, messages[2].Content, "https://example.com/old")
|
||||
}
|
||||
|
||||
func TestPrepareMessagesWithReferencesSuppressesCitationsWhenDisabled(t *testing.T) {
|
||||
disabled := false
|
||||
manage := &types.ChatManage{
|
||||
PipelineRequest: types.PipelineRequest{
|
||||
Query: "question",
|
||||
CitationEnabled: &disabled,
|
||||
SummaryConfig: types.SummaryConfig{Prompt: "custom system prompt"},
|
||||
},
|
||||
PipelineState: types.PipelineState{
|
||||
UserContent: "question",
|
||||
MergeResult: []*types.SearchResult{{
|
||||
ID: "chunk-1", KnowledgeID: "doc-1", KnowledgeBaseID: "kb-1", KnowledgeTitle: "Doc", Content: "evidence",
|
||||
}},
|
||||
},
|
||||
}
|
||||
|
||||
messages, refs := prepareMessagesWithReferences(context.Background(), manage)
|
||||
require.Contains(t, messages[0].Content, "Source citations are disabled")
|
||||
require.Contains(t, messages[1].Content, `<chunk id="c1"`)
|
||||
require.NotContains(t, messages[1].Content, "chunk-1")
|
||||
require.Equal(t, "answer ", refs.ExpandText(`answer <ref id="c1"/>`))
|
||||
}
|
||||
|
||||
@@ -89,10 +89,25 @@ func TestPrepareFallbackMessagesMigratesHistoricalCitations(t *testing.T) {
|
||||
}}
|
||||
|
||||
messages, refs := prepareFallbackMessages(cm, "legacy fallback prompt")
|
||||
require.Contains(t, messages[0].Content, "Source reference protocol")
|
||||
require.Contains(t, messages[0].Content, "Source handling protocol")
|
||||
require.Equal(t, `Previous <ref id="c1"/>`, messages[2].Content)
|
||||
require.Equal(t,
|
||||
`<kb doc="Legacy" chunk_id="legacy-chunk" kb_id="legacy-kb" />`,
|
||||
refs.ExpandText(`<ref id="c1"/>`),
|
||||
)
|
||||
}
|
||||
|
||||
func TestPrepareFallbackMessagesSuppressesCitationsWhenDisabled(t *testing.T) {
|
||||
disabled := false
|
||||
cm := &types.ChatManage{PipelineRequest: types.PipelineRequest{CitationEnabled: &disabled}}
|
||||
cm.Query = "follow-up"
|
||||
cm.History = []*types.History{{
|
||||
Query: "previous",
|
||||
Answer: `Previous <kb doc="Legacy" chunk_id="legacy-chunk" />`,
|
||||
}}
|
||||
|
||||
messages, refs := prepareFallbackMessages(cm, "legacy fallback prompt")
|
||||
require.Contains(t, messages[0].Content, "Source citations are disabled")
|
||||
require.Equal(t, `Previous <ref id="c1"/>`, messages[2].Content)
|
||||
require.Equal(t, "answer ", refs.ExpandText(`answer <ref id="c1"/>`))
|
||||
}
|
||||
|
||||
@@ -229,6 +229,7 @@ func (s *sessionService) buildAgentConfig(
|
||||
MCPServices: customAgent.Config.MCPServices,
|
||||
MCPAuthWaitTimeout: customAgent.Config.MCPAuthWaitTimeout,
|
||||
Thinking: customAgent.Config.Thinking,
|
||||
CitationEnabled: customAgent.Config.CitationEnabled,
|
||||
RetrieveKBOnlyWhenMentioned: customAgent.Config.RetrieveKBOnlyWhenMentioned,
|
||||
LLMCallTimeout: customAgent.Config.LLMCallTimeout,
|
||||
RetainRetrievalHistory: customAgent.Config.RetainRetrievalHistory,
|
||||
|
||||
@@ -995,11 +995,12 @@ func prepareFallbackMessages(
|
||||
promptContent string,
|
||||
) ([]chat.Message, *llmreference.Registry) {
|
||||
messages := buildFallbackMessages(chatManage, promptContent)
|
||||
refs := llmreference.NewRegistry()
|
||||
citationsEnabled := chatManage == nil || chatManage.CitationsEnabled()
|
||||
refs := llmreference.NewRegistry(citationsEnabled)
|
||||
if len(messages) > 0 && messages[0].Role == "system" {
|
||||
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt
|
||||
messages[0].Content = strings.TrimRight(messages[0].Content, " \t\r\n") + llmreference.ProtocolPrompt(citationsEnabled)
|
||||
} else {
|
||||
messages = append([]chat.Message{{Role: "system", Content: strings.TrimSpace(llmreference.ProtocolPrompt)}}, messages...)
|
||||
messages = append([]chat.Message{{Role: "system", Content: strings.TrimSpace(llmreference.ProtocolPrompt(citationsEnabled))}}, messages...)
|
||||
}
|
||||
return refs.EncodeMessages(messages), refs
|
||||
}
|
||||
@@ -1184,7 +1185,7 @@ func (s *sessionService) consumeFallbackStream(
|
||||
// `references` SSE event. Must run before CHAT_COMPLETION_STREAM so citations
|
||||
// arrive while the connection is still open (complete closes the stream).
|
||||
func emitKnowledgeReferencesEvent(ctx context.Context, chatManage *types.ChatManage) {
|
||||
if chatManage == nil || chatManage.EventBus == nil || len(chatManage.MergeResult) == 0 {
|
||||
if chatManage == nil || !chatManage.CitationsEnabled() || chatManage.EventBus == nil || len(chatManage.MergeResult) == 0 {
|
||||
return
|
||||
}
|
||||
logger.Infof(ctx, "Emitting references event with %d results (pre-answer)", len(chatManage.MergeResult))
|
||||
@@ -1205,6 +1206,9 @@ func (s *sessionService) emitFallbackAnswer(ctx context.Context, chatManage *typ
|
||||
if chatManage.EventBus == nil {
|
||||
return
|
||||
}
|
||||
if !chatManage.CitationsEnabled() {
|
||||
content = llmreference.NewRegistry(false).ExpandText(content)
|
||||
}
|
||||
|
||||
fallbackID := generateEventID("fallback")
|
||||
if err := chatManage.EventBus.Emit(ctx, types.Event{
|
||||
|
||||
@@ -52,6 +52,31 @@ type stubModelService struct {
|
||||
modelsByID map[string]*types.Model
|
||||
}
|
||||
|
||||
func TestEmitKnowledgeReferencesEventHonorsCitationSetting(t *testing.T) {
|
||||
bus := event.NewEventBus()
|
||||
emitted := 0
|
||||
bus.On(event.EventAgentReferences, func(context.Context, event.Event) error {
|
||||
emitted++
|
||||
return nil
|
||||
})
|
||||
disabled := false
|
||||
cm := &types.ChatManage{
|
||||
PipelineRequest: types.PipelineRequest{CitationEnabled: &disabled},
|
||||
PipelineState: types.PipelineState{
|
||||
MergeResult: []*types.SearchResult{{ID: "chunk-1"}},
|
||||
},
|
||||
PipelineContext: types.PipelineContext{EventBus: bus.AsEventBusInterface()},
|
||||
}
|
||||
|
||||
emitKnowledgeReferencesEvent(context.Background(), cm)
|
||||
require.Zero(t, emitted)
|
||||
|
||||
enabled := true
|
||||
cm.CitationEnabled = &enabled
|
||||
emitKnowledgeReferencesEvent(context.Background(), cm)
|
||||
require.Equal(t, 1, emitted)
|
||||
}
|
||||
|
||||
func (s *stubModelService) CreateModel(context.Context, *types.Model) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -154,7 +154,8 @@ func (s *sessionService) resolveRetrievalTenantID(
|
||||
// applyAgentOverridesToChatManage applies custom agent configuration overrides
|
||||
// to a ChatManage object that was initialized with system defaults.
|
||||
// This covers: system prompt, context template, temperature, max tokens, thinking,
|
||||
// retrieval thresholds, rewrite settings, fallback settings, FAQ strategy, and history turns.
|
||||
// citation output, retrieval thresholds, rewrite settings, fallback settings, FAQ strategy,
|
||||
// and history turns.
|
||||
func (s *sessionService) applyAgentOverridesToChatManage(
|
||||
ctx context.Context,
|
||||
customAgent *types.CustomAgent,
|
||||
@@ -188,6 +189,7 @@ func (s *sessionService) applyAgentOverridesToChatManage(
|
||||
// EnsureDefaults pins nil to explicit false so thinking_control wire formats
|
||||
// always receive a value.
|
||||
cm.SummaryConfig.Thinking = customAgent.Config.Thinking
|
||||
cm.CitationEnabled = customAgent.Config.CitationEnabled
|
||||
if customAgent.Config.Thinking != nil {
|
||||
logger.Infof(ctx, "Using custom agent's thinking: %v", *customAgent.Config.Thinking)
|
||||
} else {
|
||||
|
||||
Reference in New Issue
Block a user